Инструмент, чтобы добавить и завершить [закрытую] документацию исходного кода 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; -)

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

После пары тестов он может - например, запустив его в файле класса с небольшим количеством документации, с - параметр undocumentedelements , например:
Возможный перевод названия: «Автоматическое добавление тегов phpDoc с использованием PHP_Beautifier»

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

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

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

• создать новый фильтр PHP_Beautifier, который будет обнаруживать следующие токены :
  • 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
• Instanciate 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 , чтобы избежать предупреждения и уведомления ...
Соответствующий патч можно скачать здесь: 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 класс
• Док-блок, добавленный в конструкцию __ method
• Док-блок на doSomething уже присутствовал в нашем коде: он не был удален.
• Есть несколько тегов @todo ^^

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

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

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

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