Инструмент для добавления и завершения документации исходного кода PHP

Ответ 1

Я думаю, PHP_Codesniffer может указывать, когда нет докблока - см. примеры отчетов эта страница (цитируя один из них):

--------------------------------------------------------------------------------
FOUND 5 ERROR(S) AND 1 WARNING(S) AFFECTING 5 LINE(S)
--------------------------------------------------------------------------------
  2 | ERROR   | Missing file doc comment
 20 | ERROR   | PHP keywords must be lowercase; expected "false" but found
    |         | "FALSE"
 47 | ERROR   | Line not indented correctly; expected 4 spaces but found 1
 47 | WARNING | Equals sign not aligned with surrounding assignments
 51 | ERROR   | Missing function doc comment
 88 | ERROR   | Line not indented correctly; expected 9 spaces but found 6
--------------------------------------------------------------------------------

Я полагаю, вы могли бы использовать PHP_Codesniffer, чтобы хотя бы получить список всех файлов/классов/методов, у которых нет документации; из того, что я помню, он может генерировать XML как результат, который будет проще анализировать с помощью какого-либо автоматизированного инструмента - это может быть первым шагом какого-либо генератора докроблоков; -)

Кроме того, если вы используете phpDocumentor для создания документации, может ли она не сообщать об ошибках для отсутствующих блоков?

После нескольких тестов он может, например, запускать его в файле класса с небольшой документацией с параметром --undocumentedelements, например:

phpdoc --filename MyClass.php --target doc --undocumentedelements

Дает это в середине вывода:

Reading file /home/squale/developpement/tests/temp/test-phpdoc/MyClass.php -- Parsing file
WARNING in MyClass.php on line 2: Class "MyClass" has no Class-level DocBlock.
WARNING in MyClass.php on line 2: no @package tag was used in a DocBlock for class MyClass
WARNING in MyClass.php on line 5: Method "__construct" has no method-level DocBlock.
WARNING in MyClass.php on line 16: File "/home/squale/developpement/tests/temp/test-phpdoc/MyClass.php" has no page-level DocBlock, use @package in the first DocBlock to create one
done

Но и здесь, даже если это полезно в качестве инструмента для создания отчетов, это не так полезно, когда дело доходит до создания недостающих докблоков...

Теперь я не знаю какого-либо инструмента, который будет предварительно генерировать недостающие докблоки для вас: я обычно использую PHP_Codesniffer и/или phpDocumentor в своем непрерывном интегрировании mecanism, он сообщает о недостающих документах, а затем каждый разработчик добавляет недостающие, из его IDE...

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

Из этого я действительно не знаю полностью автоматизированного инструмента для создания docblocks... Но я уверен, что нам удастся создать интересный инструмент, используя либо:

• API отражения
• token_get_all для анализа источника файла PHP.

Однако после немного большего поиска я нашел этот блог-пост (он на французском языке - возможно, некоторые люди здесь смогут понять): Ajout automatique de Tags phpDoc à l'aide de PHP_Beautifier.
Возможный перевод названия: "Автоматическое добавление тегов phpDoc с помощью PHP_Beautifier"

Идея на самом деле неплохая:

• Инструмент PHP_Beautifier довольно приятный и мощный, когда дело доходит до формирования некоторого PHP-кода, который недостаточно хорошо сформирован
  • Я использовал его много раз для кода, который я даже не читал ^^
• И он может быть расширен, используя то, что он называет "фильтрами".
  • см. PHP_Beautifier_Filter для списка предоставленных фильтров.

Идея, которая используется в блоге, я связан с:

• создайте новый фильтр PHP_Beautifier, который будет обнаруживать следующие токены:
  • T_CLASS
  • T_FUNCTION
  • T_INTERFACE
• И добавьте "черновик" doc-блока непосредственно перед ними, если его еще нет

Чтобы запустить инструмент в некотором MyClass.php файле, мне пришлось сначала установить PHP_Beautifier:

pear install --alldeps Php_Beautifier-beta

Затем загрузите фильтр в каталог, в котором я работал (возможно, он поместил его в каталог по умолчанию):

wget http://fxnion.free.fr/downloads/phpDoc.filter.phpcs
cp phpDoc.filter.phpcs phpDoc.filter.php

И после этого я создал новый beautifier-1.php script (на основе того, что было предложено в блоге, которое я связал, еще раз), который будет:

• Загрузите содержимое моего файла MyClass.php
• Ученик PHP_Beautifier
• Добавьте несколько фильтров, чтобы украсить код.
• Добавьте фильтр phpDoc, который мы только что загрузили
• Украсьте источник нашего файла и повторите его до стандартного вывода.

Код beautifier-1.php script будет выглядеть следующим образом:
(Еще раз, самая большая часть - копия-вставка из блога, я только перевел комментарии и изменил несколько мелких вещей)

require_once 'PHP/Beautifier.php';

// Load the content of my source-file, with missing docblocks
$sourcecode = file_get_contents('MyClass.php');

$oToken = new PHP_Beautifier(); 

// The phpDoc.filter.php file is not in the default directory,
// but in the "current" one => we need to add it to the list of
// directories that PHP_Beautifier will search in for filters
$oToken->addFilterDirectory(dirname(__FILE__));

// Adding some nice filters, to format the code
$oToken->addFilter('ArrayNested');  
$oToken->addFilter('Lowercase');        
$oToken->addFilter('IndentStyles', array('style'=>'k&r'));

// Adding the phpDoc filter, asking it to add a license
// at the beginning of the file
$oToken->addFilter('phpDoc', array('license'=>'php'));

// The code is in $sourceCode
// We could also have used the setInputFile method,
// instead of having the code in a variable
$oToken->setInputString($sourcecode);        
$oToken->process();

// And here we get the result, all clean !              
echo $oToken->get();

Обратите внимание, что мне также пришлось проложить две мелочи в phpDoc.filter.php, чтобы избежать предупреждения и уведомления...
Соответствующий патч можно скачать там: http://extern.pascal-martin.fr/so/phpDoc.filter-pmn.patch

Теперь, если мы запустим этот beautifier-1.php script:

$ php ./beautifier-1.php

С файлом MyClass.php, который initialy содержит этот код:

class MyClass {
    public function __construct($myString, $myInt) {
        // 
    }

    /**
     * Method with some comment
     * @param array $params blah blah
     */
    public function doSomething(array $params = array()) {
        // ...
    }

    protected $_myVar;
}

Вот такой результат, который мы получаем - как только наш файл украшен:

<?php
/**
 *
 * PHP version 5
 *
 * LICENSE: This source file is subject to version 3.0 of the PHP license
 * that is available through the world-wide-web at the following URI:
 * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
 * the PHP License and are unable to obtain it through the web, please
 * send a note to [email protected] so we can mail you a copy immediately.
 * @category   PHP
 * @package
 * @subpackage Filter
 * @author FirstName LastName <mail>
 * @copyright 2009 FirstName LastName
 * @link
 * @license     http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    CVS: $Id:$
 */


/**
 * @todo Description of class MyClass
 * @author 
 * @version 
 * @package 
 * @subpackage 
 * @category 
 * @link 
 */
class MyClass {

    /**
     * @todo Description of function __construct
     * @param  $myString 
     * @param  $myInt
     * @return 
     */
    public function __construct($myString, $myInt) {
        //

    }
    /**
     * Method with some comment
     * @param array $params blah blah
     */
    public function doSomething(array $params = array()) {
        // ...

    }

    protected $_myVar;
}

Можно отметить:

• Блок лицензий в начале файла
• Докблоки, добавленные в класс MyClass
• Докблоки, добавленные по методу __construct
• Докблоки на doSomething уже присутствовали в нашем коде: он не был удален.
• Есть теги @todo ^^

Теперь, конечно, это не идеально:

• Он не документирует все то, что нам тоже может понадобиться
  • Например, здесь он не документировал protected $_myVar
• Он не улучшает существующие docblocks
• И он не открывает файл в любом графическом редакторе
  • Но это было бы намного сложнее, я думаю...

Но я уверен, что эту идею можно использовать в качестве отправной точки для чего-то более интересного:

• О материалах, которые не документируются: добавление новых тегов, которые будут распознаны, не должно быть слишком сложным
  • Вам просто нужно добавить их в список в начале фильтра.
• Усиление существующих докблоков может быть сложнее, я должен признать
• Приятно, что это может быть полностью автоматизировано
• Используя Eclipse PDT, возможно, это можно установить как внешний инструмент, поэтому мы можем хотя бы запустить его из нашей среды IDE?

Ответ 2

Поскольку PHPCS уже упоминался, я вбрасываю API Reflection, чтобы проверить отсутствие DocBlocks. Статья, приведенная ниже, представляет собой короткий учебник о том, как вы могли бы подойти к своей проблеме:

• http://www.phpriot.com/articles/reflection-api

Существует также PEAR Package PHP_DocBlockGenerator, который может создать блок страницы страницы и DocBlocks для включений, глобальные переменные, функции, параметры, классы, константы, свойства и методы (и другие вещи).

Ответ 3

Вы можете использовать Code Sniffer для PHP, чтобы проверить свой код на предопределенный набор правил кодирования. Он также проверит наличие недостающих докблоков и сформирует отчет, который вы можете использовать для идентификации файлов.

Ответ 4

php-tracer-weaver может программировать код и генерировать docблоки с типами параметров, вычитаться из анализа времени выполнения.

Ответ 5

В версиях phpDocumentor версии 1.4.x есть опция -ue (--undocumentedelements) [1], которая приведет к тому, что недокументированные элементы будут перечислены в качестве предупреждений на странице errors.html, которые она генерирует во время выполнения документа.

Кроме того, PHP_DocBlockGenerator [2] из PEAR выглядит так, что он может генерировать недостающие докблоки для вас.

[1] - http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.undocumentedelements

[2] - http://pear.php.net/package/PHP_DocBlockGenerator

Ответ 6

Мы используем коды для этой функциональности, используя стандартные стандарты PEAR или Zend. Это не позволит вам редактировать файлы "на лету", но, безусловно, даст вам список, с строками и описанием того, какого типа док-блок отсутствует.

НТН, Jc

Ответ 7

Вы хотите фактически автоматизировать проблему заполнения данных типа "javadoc"?

DMS Software Reengineering Toolkit может быть настроен для этого.

Он анализирует исходный текст так же, как компиляторы делают, строит внутренние структуры компилятора, позволяет выполнять произвольные анализы, вносить изменения в эти структуры, а затем восстанавливать ( "prettyprint" ) исходный текст, изменяемый в соответствии с изменениями структуры. Он даже сохраняет комментарии и форматирование исходного текста; вы можете, конечно, добавить дополнительные комментарии, и они появятся, и это, кажется, ваша основная цель. DMS делает это для многих языков, включая PHP

Что вы хотели бы сделать, это разобрать каждый файл PHP, найти каждый класс/метод, создать комментарии "javadoc", которые должны быть этим объектом (разница для классов и методов, правильно?), а затем проверить, что соответствующие комментарии были фактически присутствующих в структурах компилятора. Если нет, просто вставьте их. PrettyPrint конечный результат. Поскольку он имеет доступ к структурам компилятора, которые представляют код, нетрудно будет генерировать информацию о параметрах и возврате, как вы предложили. Разумеется, то, что он не может сделать, генерирует комментарии о намерении intendend; но он может создать заполнитель для заполнения позже.

Ответ 8

Не знаю, если это поможет, но если Codesniffer может указать функции/методы, то достойная PHP IDE (я предлагаю PHPEd) может легко проверить и подделать комментарии PHPDoc для каждой функции.

Просто введите /** над каждой функцией и нажмите ENTER, а PHPEd автоматически выполнит код с @param1, @param1, @return и т.д., правильно заполненный, готовый к вашим дополнительным описаниям. Вот первый, который я попробовал, чтобы привести пример:

  /**
  * put your comment here...
  * 
  * @param mixed $url
  * @param mixed $method
  * @param mixed $timeout
  * @param mixed $vars
  * @param mixed $allow_redirects
  * @return mixed
  */
  public static function curl_get_file_contents($url, $method = 'get', $timeout = 30, $vars = array(), $allow_redirects = true)

Это легко настроить:

  /**
  * Retrieves a file using the cURL extension
  * 
  * @param string $url
  * @param string $method
  * @param int $timeout
  * @param array $vars parameters to pass to cURL
  * @param int $allow_redirects boolean choice to follow any redirects $url serves up
  * @return mixed
  */
  public static function curl_get_file_contents($url, $method = 'get', $timeout = 30, $vars = array(), $allow_redirects = true)  

Не совсем автоматизированное решение, но достаточно быстрое для меня как ленивый разработчик:)

Ответ 9

Мне пришлось сделать большую партию автоматизации фиксации docblock в последнее время, в основном на основе правильного ответа выше kwith некоторых изменений, специфичных для контекста. Это взломать, но я связываюсь здесь, если он будет полезен кому-либо еще в будущем. По сути, он выполняет базовый синтаксический разбор токенов блока комментариев в PHP Beautifier.

https://gist.github.com/israelshirk/408f2656100196e73367