I think PHP_Codesniffer http://pear.php.net/manual/en/package.php.php-codesniffer.php可以指示何时没有文档块 - 请参阅报告示例这一页 http://pear.php.net/manual/en/package.php.php-codesniffer.usage.php （引用其中之一） :
--------------------------------------------------------------------------------
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 作为输出，这将更容易使用一些自动化工具进行解析——这可能是某些文档块生成器的第一步;-)
Also, if you are using [phpDocumentor](http://www.phpdoc.org/) to generate the documentation, can this one not report errors for missing blocks ?
经过几次测试后，它可以 - 例如，在没有太多文档的类文件上运行它，使用--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
但是，在这里，即使它作为报告工具很有用，但在生成丢失的文档块时却没有那么有用......
Now, I don't know of any tool that will pre-generate the missing docblocks for you : I generally use PHP_Codesniffer and/or phpDocumentor in my continuous integration mecanism, it reports missing docblocks, and, then, each developper adds what is missing, from his IDE...
...这工作得很好：每天通常不会有超过几个丢失的文档块，因此该任务可以手动完成（当您编辑特定文件/方法时，Eclipse PDT 提供了为方法预先生成文档块的功能）.
除此之外，我真的不知道有什么全自动工具来生成文档块......但我很确定我们可以使用以下任一方法来创建一个有趣的工具：
- 反射 API https://www.php.net/reflection
-
token_get_all https://www.php.net/manual/en/function.token-get-all.php解析 PHP 文件的源代码。
After a bit more searching, though, I found this blog-post *(it's in french -- maybe some people here will be able to understand)* : [Ajout automatique de Tags phpDoc à l'aide de PHP_Beautifier](http://fxnion.free.fr/articles/phpdoc-tags-php-beautifier.php).
*Possible translation of the title : "Automatically adding phpDoc tags, using PHP_Beautifier"*
这个想法其实还不错：
- The PHP_Beautifier http://pear.php.net/package/PHP_Beautifier tool is pretty nice and powerful, when it comes to formating some PHP code that's not well formated
- And it can be extended, using what it calls "filters".
- see PHP_Beautifier_Filter http://beautifyphp.sourceforge.net/docs/PHP_Beautifier/Filter/PHP_Beautifier_Filter.html获取提供的过滤器列表
我链接到的博客文章中使用的想法是：
- create a new PHP_Beautifier filter, that will detect the following tokens :
T_CLASST_FUNCTIONT_INTERFACE
- 并在它们之前添加一个“草稿”文档块（如果还没有）
To run the tool on some `MyClass.php` file, I've had to first install `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 file
- 实例化
PHP_Beautifier
- 添加一些过滤器来美化代码
- Add the
phpDoc我们刚刚下载的过滤器
- 美化文件的源代码，并将其回显到标准输出。
The code of the `beautifier-1.php` script will like this :
*(Once again, the biggest part is a copy-paste from the blog-post ; I only translated the comments, and changed a couple of small things)*
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 http://extern.pascal-martin.fr/so/phpDoc.filter-pmn.patch
Now, if we run that `beautifier-1.php` script :
$ php ./beautifier-1.php
With a 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 [email protected] /cdn-cgi/l/email-protection 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 class
- 已添加的文档块
__construct method
- 文档块上
doSomething已经存在于我们的代码中：它尚未被删除。
- 有一些
@todo tags ^^
Now, it's not perfect, of course :
- It doesn't document all the stuff we could want it too
- 例如，在这里，它没有记录
protected $_myVar
- 它不会增强现有的文档块
- And it doesn't open the file in any graphical editor
But I'm pretty sure that this idea could be used as a starting point to something a lot more interesting :
- About the stuff that doesn't get documented : adding new tags that will be recognized should not be too hard
- 我不得不承认，增强现有的文档块可能会更困难
- 一件好事是这可以完全自动化
- 使用 Eclipse PDT，也许可以将其设置为外部工具，所以我们至少可以从我们的 IDE 启动它？
