添加和完善PHP源代码文档的工具

Question

我有几个已完成的较旧的PHP项目，其中包含许多我想以javadoc / phpDocumentor风格进行记录的项目。

最好是手动处理每个文件并被迫与文档一起进行代码审查，但由于时间有限，我对帮助我尽可能自动执行任务的工具感兴趣。

我正在考虑的工具理想情况下应具有以下功能：

• 解析一个PHP项目树，并告诉我哪里有未记录的文件，类和函数/方法（即缺少适当docblock注释的元素）

• 提供一种方法，可以通过 创建空结构 轻松地中途添加缺失的文档块，并且理想情况下，可以在编辑器中打开文件（无论是内部还是外部，我都不在乎），因此可以放入描述中。

可选的：

• 自动识别参数类型，返回值等。但这并不是真正需要的。

有问题的语言是PHP，尽管我可以想象经过一些调整后C / Java工具可能能够处理PHP文件。

感谢您的宝贵意见！

Answer 1

我认为PHP_Codesniffer可以指出何时没有docblock-
请参阅本页
上的报告示例 （引用其中之一） ：

--------------------------------------------------------------------------------
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从那开始，我真的不知道有什么全自动工具可以生成docblocks …但是我很确定我们可以使用以下任一方法来创建一个有趣的工具：

• 反射API
• token_get_all 解析PHP文件的源。

经过更多的搜索之后，我发现了这个博客文章 （它是法语的-也许这里的一些人会理解） ：Ajout automatique de Tags
phpDocàl’aide de PHP_Beautifier。
标题的可能翻译：“使用PHP_Beautifier自动添加phpDoc标签”

这个想法实际上还不错：

• 在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文件的内容
• 实例化 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。补丁

现在，如果我们运行该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 [e-mail] 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课程上添加的文档块
• __construct方法中已添加的文档块
• 上的docblock doSomething已经存在于我们的代码中：尚未删除。
• 有一些@todo标签^^

现在，它并不完美，当然：

• 它并没有记录我们可能想要的所有东西
  • 例如，在这里，它没有记录 protected $_myVar
• 它不会增强现有的文档块
• 而且它不会在任何图形编辑器中打开文件
  • 但这会困难得多，我想…

但是我很确定，这个想法可以作为更多有趣的事情的起点：

• 关于未记录的内容：添加将被识别的新标签应该不太难
  • 您只需要将它们添加到过滤器开头的列表中
• 我不得不承认，增强现有文档块可能会更困难
• 一件好事是，这可以是全自动的
• 使用Eclipse PDT，也许可以将其设置为 外部工具 ，所以我们至少可以从IDE中启动它？