Как вы документируете свои PHP-функции и классы inline?

Я знаю, что существует много разных стандартов для встроенной документации PHP-кода. Вот что я подразумеваю под встроенной документацией, и, пожалуйста, исправьте меня, если есть лучший термин:

/**
* This is the description for the class below.
*
* @package    my-package
* @subpackage my-subpackage
* @author     my-name
* @version    my-version
* ...
*/
class orderActions {
...

Какая самая лучшая и наиболее общепринятая форма встроенной документации? Существуют ли какие-либо инструменты для автоматической генерации такой документации или это нужно сделать вручную?

Мне не интересно создавать руководства - я хочу знать, как сгенерировать тип комментария кода выше, или "встроенную документацию".

Ответы

Ответ 1

PHPDoc, как и то, что вы опубликовали, является общепринятой формой документации PHP.

Вы можете использовать Doxygen для автоматического создания документов.

Изменить. Что касается генерации встроенной документации в вашем коде, я никогда не сталкивался с инструментом, который вернется и сделает это извне для проекта. Как правило, он остался в области среды IDE для генерации шаблона во время кода.

Eclipse действительно выполняет достойную работу (это одна из немногих вещей, которые мне нравятся в Eclipse), и я считаю, что Netbeans также работает. Любая основная IDE, скорее всего, будет иметь функциональные возможности для создания этого типа генерации шаблонов.

Ответ 3

Документация? Что это?

Я просто пытаюсь написать чистый код.

Ответ 4

Обычно вы пишете комментарий к docblock, но я полагаю, что некоторые IDE могут создать для вас шаблон.

Я действительно написал программу, которая может отслеживать запущенную программу и определять типы параметров и записывать их как комментарии docblock. Это немного багги, но это вроде работает.

Ответ 5

Я создал документатор, который очень прост в использовании и совместим с phpdoc:

Пример:

<?php
    $docs = new QuickDocumenter();
    $docs->parseString("
    /**
    *   Sanitize string
    *
    *   @since      1.0
    *   @version    1.0
    */
    ");
    foreach( $docs->result() as $doc)
    {
        highlight_string( print_r( $doc , true ) );
        echo "<hr/>";
    }
?>

Смотрите в Github:

https://github.com/olaferlandsen/QuickDocumenter

Ответ 6

Хотя я не использовал его полностью, Doxygen выглядит многообещающим для этой задачи.

Если вы знакомы с JavaDoc-инструментом для Java, это очень похоже на это. Вы используете стиль Doxygen, а затем запускаете инструмент поверх исходных файлов для создания документации.

Ответ 7

Не уверен, что вы кодируете, но у меня есть несколько фрагментов (я использую Textmate), которые я просто добавляю, когда я работаю). Я нашел, что это заканчивается лучшими результатами, поскольку я заполняю детали доверять системе, чтобы сделать это для меня.

Это больше работает в начале, но, похоже, стоит того, чтобы в конечном итоге