Ответ 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?