У меня есть несколько готовых, старых PHP-проектов, в которых много всего, что я хотел бы документировать в стиле javadoc / phpDocumentor.
Работая через каждый файл вручную и будучи вынужденным выполнять обзор кода наряду с документированием, было бы лучше всего, я просто избавляюсь от ограничений времени, интересующихся инструментами, которые помогают мне автоматизировать задачу как можно больше.
Инструмент, о котором я думаю, в идеале имел бы следующие возможности:
Разберите дерево проектов PHP и скажите мне, где есть недокументированные файлы, классы и функции / методы (т.е. элементы, отсутствующие в соответствующем комментарии докблока)
Предоставьте метод на полпути, легко добавьте недостающие докблоки, создав пустые структуры и, в идеале, открыв файл в редакторе (внутреннем или внешнем, мне все равно), поэтому я могу добавить описание.
Необязательный:
Язык, о котором идет речь, – это PHP, хотя я мог представить, что инструмент C / Java может обрабатывать файлы PHP после некоторой настройки.
Спасибо за большой вклад!
Я думаю, 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 как вывод, который будет проще анализировать с помощью некоторого автоматизированного инструмента – это может быть первым шагом некоторого docblock-generator 😉
Кроме того, если вы используете phpDocumentor для генерации документации, может ли она не сообщать об ошибках для недостающих блоков?
После нескольких тестов он может, например, запускать его в файле класса с --undocumentedelements документацией, с параметром --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 для метода, когда вы редактирование определенного файла / метода) .
Appart от этого, я действительно не знаю полностью автоматизированного инструмента для создания docblocks … Но я уверен, что нам удалось создать интересный инструмент, используя либо:
token_get_all для анализа источника файла PHP. Однако после немного большего поиска я нашел этот блог-пост (он на французском языке – возможно, некоторые люди здесь смогут понять) : Ajout automatique de Tags phpDoc à l'aide de PHP_Beautifier .
Возможный перевод названия: «Автоматическое добавление тегов phpDoc с помощью PHP_Beautifier»
Идея на самом деле неплохая:
PHP_Beautifier довольно приятный и мощный, когда дело доходит до формирования некоторого кода PHP, который не очень хорошо сформирован
PHP_Beautifier_Filter для списка предоставленных фильтров Идея, которая используется в блоге, я связан с:
T_CLASS T_FUNCTION T_INTERFACE Чтобы запустить этот инструмент в файле 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 (основываясь на том, что предлагается в блоге, которое я связал, еще раз) , что будет:
MyClass.php PHP_Beautifier phpDoc мы только что загрузили Код сценария beautifier-1.php понравится:
(Еще раз, самая большая часть – копия-вставка из блога, я только перевел комментарии и изменил несколько мелких вещей)
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 две мелочи в phpDoc.filter.php , чтобы избежать предупреждения и уведомления …
Соответствующий патч можно загрузить там: http://extern.pascal-martin.fr/so/phpDoc.filter-pmn.patch
Теперь, если мы запустим этот скрипт beautifier-1.php :
$ php ./beautifier-1.php
С файлом MyClass.php, который содержит этот код:
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 license@php.net 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 на doSomething уже присутствовали в нашем коде: он не был удален. @todo ^^ Конечно, это не идеально, конечно:
protected $_myVar Но я уверен, что эту идею можно использовать в качестве отправной точки для чего-то более интересного:
Поскольку PHPCS уже упоминался, я вбрасываю API Reflection, чтобы проверить отсутствие DocBlocks. Статья, приведенная ниже, представляет собой короткий учебник о том, как вы могли бы подойти к своей проблеме:
Существует также пакет PEAR PHP_DocBlockGenerator который может создавать блок страницы страницы и DocBlocks для включения, глобальные переменные, функции, параметры, классы, константы, свойства и методы (и другие вещи).
Вы можете использовать Code Sniffer для PHP, чтобы проверить свой код на предопределенный набор правил кодирования. Он также проверит наличие недостающих докблоков и сформирует отчет, который вы можете использовать для идентификации файлов.
php-tracer-weaver может кодировать код и генерировать докблоки с типами параметров, вычитаться из анализа времени выполнения.
В версиях phpDocumentor версии 1.4.x есть опция -ue (–undocumentedelements) [1], что приведет к тому, что недокументированные элементы будут отображаться в виде предупреждений на странице errors.html, которые она генерирует во время выполнения документа.
Кроме того, PHP_DocBlockGenerator [2] из PEAR выглядит так, что он может генерировать недостающие докблоки для вас.
Мы используем коды для этой функциональности на работе, используя стандартные стандарты PEAR или Zend. Это не позволит вам редактировать файлы «на лету», но, безусловно, даст вам список, с строками и описанием того, какого типа док-блок отсутствует.
HTH, Jc
Не знаю, если это какая-то помощь, но если 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)
Не совсем автоматическое решение, но достаточно быстрое для меня как ленивый разработчик 🙂
Вы хотите фактически автоматизировать проблему заполнения данных типа «javadoc»?
Для этого можно настроить DMS Software Reengineering Toolkit .
Он анализирует исходный текст так же, как и компиляторы, строит внутренние структуры компилятора, позволяет выполнять произвольные анализы, вносить изменения в эти структуры, а затем восстанавливать («prettyprint») исходный текст, изменяемый в соответствии с изменениями структуры. Он даже сохраняет комментарии и форматирование исходного текста; вы можете, конечно, добавить дополнительные комментарии, и они появятся, и это, кажется, ваша основная цель. DMS делает это для многих языков, включая PHP
То, что вы хотели бы сделать, – разобрать каждый файл PHP, найти каждый класс / метод, генерировать комментарии «javadoc», которые должны быть этим объектом (разница для классов и методов, правильно?), А затем проверить, что соответствующие комментарии действительно присутствовали в структуры компилятора. Если нет, просто вставьте их. PrettyPrint конечный результат. Поскольку он имеет доступ к структурам компилятора, которые представляют код, нетрудно будет генерировать информацию о параметрах и возврате, как вы предложили. Разумеется, то, что он не может сделать, генерирует комментарии о намерении intendend; но он может создать заполнитель для вас, чтобы заполнить его позже.
В последнее время мне пришлось сделать большую партию автоматизации фиксации docblock, в основном на основе правильного ответа выше с некоторыми изменениями, специфичными для контекста. Это взломать, но я связываюсь здесь, если он будет полезен кому-либо еще в будущем. По сути, он выполняет базовый синтаксический разбор токенов блока комментариев в PHP Beautifier.