Я знаю, что существует много разных стандартов для встроенной документации PHP-кода. Вот что я подразумеваю под встроенной документацией, и, пожалуйста, исправьте меня, если есть лучший термин:
/** * This is the description for the class below. * * @package my-package * @subpackage my-subpackage * @author my-name * @version my-version * ... */ class orderActions { ... Какая самая лучшая и наиболее распространенная форма встроенной документации? Существуют ли какие-либо инструменты для автоматической генерации такой документации, или это нужно делать вручную?
Я не заинтересован в создании руководств – я хочу знать, как генерировать тип комментария кода выше, или «встроенная документация».
PHPDoc , как и то, что вы опубликовали, является широко распространенной формой документации PHP.
Вы можете использовать Doxygen для автоматического создания документов.
Изменить: Что касается генерации встроенной документации в вашем коде, я никогда не сталкивался с инструментом, который вернется и сделает это извне для проекта. Как правило, в области среды IDE формируется шаблон при кодировании.
Eclipse на самом деле делает достойную работу (это одна из немногих вещей, которые мне нравятся в Eclipse), и я считаю, что Netbeans тоже делает это. Любая основная IDE, вероятно, будет иметь функциональные возможности для создания такого типа шаблонов.
Выбери из:
См. Также статью в Википедии «Сравнение генераторов документации», раздел «по языку» .
Документация? Что это?
Я просто пытаюсь написать чистый код.
Обычно вы пишете комментарий docblock, но я полагаю, что некоторые IDE могут создать для вас шаблон.
Я действительно написал программу, которая может отслеживать запущенную программу и определять типы параметров и записывать их как комментарии докблока . Это немного багги, но это работает.
я создал документатор, очень простой в использовании и совместимый с phpdoc:
Пример:
<?php $docs = new QuickDocumenter(); $docs->parseString(" /** * Sanitize string * * @sinse 1.0 * @version 1.0 */ "); foreach( $docs->result() as $doc) { highlight_string( print_r( $doc , true ) ); echo "<hr/>"; } ?>
См. В Github:
До свидания!
Хотя я еще не полностью использовал его, Doxygen выглядит многообещающим для этой задачи.
Если вы знакомы с JavaDoc-инструментом для Java, это очень похоже на это. Вы используете стиль Doxygen, а затем запускаете инструмент поверх исходных файлов для создания документации.
Не уверен, что вы кодируете, но у меня есть несколько фрагментов (я использую Textmate), которые я просто добавляю, когда работаю). Я нашел, что это приводит к лучшим результатам, поскольку я заполняю детали, а не доверяю чтобы сделать это для меня.
Это больше работает в начале, но, похоже, это стоит того, в конечном счете