一个添加和完成PHP源代码文档的工具
我有几个完成的，较旧的PHP项目，包含很多我想用javadoc / phpDocumentor样式记录的包含。
虽然手动处理每个文件并被迫与文档一起进行代码审查将是最好的事情，但我只是出于时间限制，对工具感兴趣，以帮助我尽可能地自动完成任务。
我正在考虑的工具理想情况下具有以下function：
-
解析PHP项目树并告诉我哪里有未记录的文件，类和函数/方法（即元素缺少相应的docblock注释）
-
提供一种方法，通过创建空结构轻松添加缺少的docblocks，理想情况下，在编辑器中打开文件（内部或外部我不在乎），这样我就可以放入描述中。
可选的：
- 自动识别参数类型，返回值等。 但这并不是真的需要。
有问题的语言是PHP，虽然我可以想象一个C / Java工具可能能够在经过一些调整后处理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-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
但是，在这里，即使它作为报告工具很有用，在生成缺少的文档块时也没有用…
现在，我不知道有任何工具会为你预先生成缺失的docblock：我通常在我的持续集成机制中使用PHP_Codesniffer和/或phpDocumentor，它报告缺少docblocks，然后，每个开发人员添加缺少的内容，从他的IDE ……
…哪个工作得很好：每天通常只有几个缺失的docblock，所以任务可以手工完成（Eclipse PDT提供了一个function来预先生成方法的docblock，当你是编辑特定文件/方法） 。
从那以后，我真的不知道任何生成docblocks的全自动工具……但我很确定我们可以设法创建一个有趣的工具，使用以下任一方法：
- Reflection API
-
token_get_all用于解析PHP文件的源。
经过一番搜索后，我发现这篇博文（它是法语版的 – 也许这里有些人能够理解） ： Ajout automatique de TagsphpDocàl’aidede PHP_Beautifier 。
可能的标题翻译：“使用PHP_Beautifier自动添加phpDoc标签”
这个想法实际上并不坏：
-
PHP_Beautifier工具相当不错，function强大，当涉及到格式化一些格式不正确的PHP代码时- 我已经多次使用它代码，我甚至无法阅读^^
- 它可以使用它所谓的“ filter ”进行扩展。
- 请参阅
PHP_Beautifier_Filter以获取提供的filter列表
- 请参阅
在我链接的博客文章中使用的想法是：
- 创建一个新的PHP_Beautifierfilter，它将检测以下标记：
-
T_CLASS -
T_FUNCTION -
T_INTERFACE
-
- 如果还没有，那么在它们之前添加一个“草稿”文档块
要在某些MyClass.php文件上运行该工具，我必须先安装PHP_Beautifier ：
pear install --alldeps Php_Beautifier-beta
然后，将filter下载到我正在使用的目录中（当然可以将它放在默认目录中） ：
wget http://fxnion.free.fr/downloads/phpDoc.filter.phpcs cp phpDoc.filter.phpcs phpDoc.filter.php
之后，我创建了一个新beautifier-1.php脚本（基于我再次链接到的博客文章中提出的内容） ，它将：
- 加载我的
MyClass.php文件的内容 - Instanciate
PHP_Beautifier - 添加一些filter来美化代码
- 添加我们刚刚下载的
phpDocfilter - 美化我们文件的来源，并将其回显到标准输出。
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中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; }
这是我们获得的结果 – 一旦我们的文件被美化：
* @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
- 例如，在这里，它没有记录
- 它不会增强现有的docblock
- 它不会在任何图形编辑器中打开文件
- 但那会更难，我想……
但我很确定这个想法可以作为一个更有趣的东西的起点：
- 关于没有记录的内容：添加将被识别的新标签不应该太难
- 您只需将它们添加到filter开头的列表中即可
- 我不得不承认，增强现有的文档块可能会更难
- 一件好事是这可以完全自动化
- 使用Eclipse PDT，也许可以将其设置为外部工具 ，因此我们至少可以从IDE中启动它？
由于已经提到过PHPCS，因此我将使用Reflection API检查是否缺少DocBlock。 下面链接的文章是关于如何解决问题的简短教程：
还有一个PEAR包PHP_DocBlockGenerator ，可以创建文件页面块和DocBlocks for includes，全局变量，函数，参数，类，常量，属性和方法（以及其他东西）。
您可以使用Code Sniffer for PHP根据一组预定义的编码指南测试您的代码。 它还将检查缺少的文档块并生成可用于标识文件的报告。
php-tracer-weaver可以使用参数类型检测代码并生成docblock，并通过运行时分析进行推导。
phpDocumentor的1.4.x版本具有-ue选项（–undocumentedelements）[1]，这将导致未记录的元素在其doc运行期间生成的errors.html页面上列为警告。
此外，来自PEAR的PHP_DocBlockGenerator [2]看起来可能会为您生成缺少的docblock。
我们使用标准PEAR或Zend标准在工作中使用codesniffer来实现此function。 它不允许您动态编辑文件，但肯定会为您提供一个列表，其中包含缺少哪种docblock的行和说明。
HTH，Jc
不知道它是否有任何帮助，但如果Codesniffer可以指出函数/方法，那么一个不错的PHP IDE（我提供PHPEd）可以轻松检查和搭建每个函数的PHPDoc注释。
只需在每个函数上方键入/**并按ENTER键，PHPEd将自动填写代码，并正确填写@param1 ， @param1 ， @return return等，以备您的额外说明。 这是我试图提供一个例子的第一个：
/** * put your comment here... * * @param mixed $url * @param mixed $method * @param mixed $timeout * @param mixed $vars * @param mixed $allow_redirects * @return mixed */ public static function curl_get_file_contents($url, $method = 'get', $timeout = 30, $vars = array(), $allow_redirects = true)
这很容易调整为：
/** * Retrieves a file using the cURL extension * * @param string $url * @param string $method * @param int $timeout * @param array $vars parameters to pass to cURL * @param int $allow_redirects boolean choice to follow any redirects $url serves up * @return mixed */ public static function curl_get_file_contents($url, $method = 'get', $timeout = 30, $vars = array(), $allow_redirects = true)
不完全是一个自动化的解决方案，但作为一个懒惰的开发人员，我足够快:)
您想实际上自动填充“javadoc”类型数据的问题？
DMS Software Reengineering Toolkit可以配置为执行此操作。
它像编译器一样解析源文本，构建内部编译器结构，允许您实现任意分析，修改这些结构，然后根据结构更改重新生成（“prettyprint”）源文本。 它甚至保留了原始文本的注释和格式; 你当然可以插入其他评论，它们会出现，这似乎是你的主要目标。 DMS为许多语言（包括PHP）执行此操作
你想要做的是解析每个PHP文件，找到每个类/方法，生成应该是该实体的“javadoc”注释（类和方法的区别，对吗？）然后检查相应的注释是否实际存在于编译器结构。 如果没有，只需插入它们即可。 PrettyPrint的最终结果。 因为它可以访问代表代码的编译器结构，所以生成参数和返回信息并不困难，如您所建议的那样。 当然，它不能做的是产生关于意图目的的评论; 但它可以生成一个占位符供您稍后填写。
我最近不得不做大量的docblock修复自动化，主要基于上面的正确答案，并进行了一些特定于上下文的修改。 这是一个黑客攻击，但我将链接回来，以防将来对其他任何人都有用。 本质上，它在PHP Beautifier中对注释块标记进行基本解析。