php加入java源代码,java – 添加和完成PHP源代码文档的工具
我认为
PHP_Codesniffer可以指出什么时候没有docblock – 参见
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生成器的第一步;-)
另外，如果您使用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
但是，在这里，即使它作为一个报告工具很有用，在生成缺少的文档块时也不是很有用…
现在，我不知道任何可以为您预先生成缺少的docblock的工具：我通常使用PHP_Codesniffer和/或phpDocumentor来进行我的持续集成，它会报告缺少的docblocks，然后每个开发人员都会添加缺少的内容，从他的IDE …
…哪个工作很好：每天通常不会有几个缺少的docblock，所以可以手工完成任务(Eclipse PDT提供了一个功能来预先生成一个方法的docblock，当你是编辑一个特定的文件/方法)。
从此，我不知道任何完全自动化的工具来生成docblock …但是我很确定我们可以设法创建一个有趣的工具，使用：
经过一段时间的搜索之后，我发现这个博客文章(这是法语的 – 也许有些人在这里可以理解)：Ajout automatique de Tags phpDoc à l’aide de PHP_Beautifier。
可能翻译的标题：“自动添加phpDoc标签，使用PHP_Beautifier”
这个想法其实并不错：
> PHP_Beautifier工具是非常好的和强大的，当涉及到形成一些不太好的PHP代码
>我已经使用了很多次代码，我甚至不能读^^
>它可以扩展，使用它所谓的“过滤器”。
在我链接到的博客文章中使用的想法是：
>创建一个新的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
之后，我创建了一个新的美化者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
现在，如果我们运行这个美化者1.php脚本：
$ php ./beautifier-1.php
使用一个MyClass.php文件，该initialize包含此代码：
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 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
* @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标签^^
现在呢，当然不完美，
>它不记录我们也想要的所有东西
>例如，在这里，它没有记录受保护的$ _myVar
>它不会增强现有的docblock
>它不会在任何图形编辑器中打开该文件
但是这会更难，我猜…
但我很确定这个想法可以作为一个更有意思的起点：
>关于没有记录的东西：添加将被识别的新标签不应该太难
>您只需将它们添加到过滤器开头的列表中即可
>加强现有的docblock可能会更难，我不得不承认这是一个很好的事情，这可以是全自动化的>使用Eclipse PDT，也许这可以设置为外部工具，所以我们至少可以从IDE启动它？