我认为 PHP_Codesniffer
可以指示何时没有文档块-请参阅this page的报告示例(引用其中之一):
--------------------------------------------------------------------------------
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
选项在没有太多文档的类文件上运行它,例如:
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,它会报告丢失的文档块,然后,每个开发人员都会添加丢失的文档块,来自他的IDE ...
...效果很好:通常每天不多于几个丢失的docblock,因此可以手动完成任务(Eclipse PDT提供了一种为方法预先生成docblock的功能。编辑特定的文件/方法)。
Appart从那开始,我真的不知道有什么全自动工具可以生成文档块...但是我很确定我们可以使用以下任意一种方法来创建一个有趣的工具:
The Reflection API
token_get_all
解析PHP文件的源。
经过更多的搜索之后,我发现了这个博客文章(它是法文的-也许这里的一些人能够理解):
Ajout automatique de Tags phpDoc à l'aide de PHP_Beautifier。
标题的可能翻译:“使用PHP_Beautifier自动添加phpDoc标签”
这个想法实际上还不错:
在格式化某些格式不正确的PHP代码时, PHP_Beautifier
工具非常好用且功能强大
我已经用了很多次我什至无法阅读的代码^^
而且可以使用所谓的“过滤器”进行扩展。
有关提供的过滤器列表,请参见 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
文件的内容
实例化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
类上的docblock
已添加到__construct
方法上的docblock
我们的代码中已经存在doSomething
上的docblock:尚未将其删除。
有一些@todo
标签^^
现在,它并不完美,当然:
它也没有记录我们可能想要的所有东西
例如,在这里,它没有记录protected $_myVar
它不会增强现有的文档块
而且它不会在任何图形编辑器中打开文件
但这会困难得多,我想...
但是我很确定,这个想法可以作为更多有趣的事情的起点:
关于未记录的内容:添加将被识别的新标签应该不太难
您只需要将它们添加到过滤器开头的列表中
增强现有文档块可能会更困难,我不得不承认
一件好事是,这可以是全自动的
使用Eclipse PDT,也许可以将其设置为外部工具,所以我们至少可以从IDE中启动它?
我是一名优秀的程序员,十分优秀!