用于添加和完成PHP源代码文档的工具

Question

我有几个完成的,较旧的PHP项目,包含很多我想用javadoc/phpDocumentor样式记录的包含.

虽然手动处理每个文件并被迫与文档一起进行代码审查将是最好的事情,但我只是出于时间限制,对工具感兴趣,以帮助我尽可能地自动完成任务.

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

• 解析PHP项目树并告诉我哪里有未记录的文件,类和函数/方法(即元素缺少相应的docblock注释)

• 提供一种方法,通过创建空结构轻松添加缺少的docblocks ,理想情况下,在编辑器中打开文件(内部或外部我不在乎),这样我就可以放入描述中.

可选的:

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

有问题的语言是PHP,虽然我可以想象一个C/Java工具可能能够在经过一些调整后处理PHP文件.

感谢您的宝贵意见!

Answer 1

我想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提供了一个功能来为一个方法预生成docblock,当你是编辑特定文件/方法).

从那以后,我真的不知道任何生成docblocks的全自动工具......但我很确定我们可以创建一个有趣的工具,使用以下任一方法:

• Reflection API
• token_get_all 解析PHP文件的来源.

经过一番搜索后,我发现这篇博文(它是法语版的 - 也许这里有些人能够理解):Ajout automatique de TagsphpDocàl'aidede 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.phpinitialy包含此代码的文件:

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
• 它不会增强现有的docblock
• 它不会在任何图形编辑器中打开文件
  • 但那会更难,我想......

但我很确定这个想法可以作为一个更有趣的东西的起点:

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