添加和完成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时也没那么有用……

现在,我不知道有什么工具可以为您预先生成丢失的docblock:在我的持续集成机制中,我通常使用php_codesniffer和/或phpdocumentor,它报告丢失的docblock,然后,每个开发人员从他的ide中添加丢失的东西……

…它的工作原理很好:通常每天丢失的docblock不超过两个,因此可以手动完成任务 (当您编辑一个特定的文件/方法时,EclipsePDT提供了一个为方法预生成docblock的特性) .

从那开始,我真的不知道任何全自动的工具来生成docblock…但我很确定我们可以创建一个有趣的工具,使用:

• The Reflection API
• token_get_all 解析php文件的源代码。

不过,在进一步搜索之后,我发现了这篇博文 (法语——也许这里的一些人能听懂) : Ajout automatique de Tags phpDoc à l'aide de PHP_Beautifier .
标题的可能翻译:“自动添加phpdoc标记,使用php美化程序”

这个想法其实并不坏:

• 这个 PHP_Beautifier 当涉及到格式化一些格式不好的php代码时,该工具非常好而且功能强大。
  • 我已经用过很多次了,我都看不懂^^
• 它可以扩展,使用它所称的 过滤器 “。
  • 看见 PHP_Beautifier_Filter 对于提供的筛选器列表

我链接到的博客文章中使用的想法是:

• 创建一个新的php美化过滤器,该过滤器将检测以下令牌:
  • T_CLASS
  • T_FUNCTION
  • T_INTERFACE
• 如果还没有“草稿”文档块,则在它们之前添加一个“草稿”文档块

在一些 MyClass.php 文件,我必须先安装 php_美容师 :

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 脚本 (根据我链接到的博客中的建议,再次) ,它将:

• 加载我的内容 MyCase.PHP 文件
• 实例化 php_美容师
• 添加一些过滤器来美化代码
• 添加 phpDoc 筛选我们刚刚下载的
• 美化我们的文件源,并将其回声到标准输出。

的代码 美化-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

用一个 MyCase.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 班
• 添加到 __construct 方法
• 上的Docblock doSomething 已经存在于我们的代码中:它没有被删除。
• 有一些 @todo 标签^ ^

当然,这并不完美:

• 它没有记录所有我们想要的东西
  • 例如,在这里,它没有记录 protected $_myVar
• 它不能增强现有的docblock
• 它不会在任何图形编辑器中打开文件
  • 但我想那会更难…

但我很肯定这个想法可以作为一个起点,去做一些更有趣的事情:

• 关于那些没有记录在案的东西:添加新的可以识别的标签不应该太难
  • 你只需要把它们添加到过滤器开头的列表中
• 我不得不承认,增强现有的docblock可能更难
• 好的是这可以完全自动化
• 使用EclipsePDT,也许可以将其设置为 外部工具 ,所以我们至少可以从IDE启动它?

既然已经提到了phpc,我就抛出反射api来检查缺少的docblock。下面链接的文章是关于如何解决问题的简短教程:

• http://www.phpriot.com/articles/reflection-api

还有一个 PEAR Package PHP_DocBlockGenerator 它可以为include、全局变量、函数、参数、类、常量、属性和方法(以及其他东西)创建文件页块和docblocks。

php-tracer-weaver 可以插入代码并生成带有参数类型的docblock,通过运行时分析得到。

你可以使用 Code Sniffer 让php根据一组预定义的编码准则来测试代码。它还将检查缺少的文档块并生成一个报告,您可以使用它来标识文件。

phpdocumentor的1.4.x版本具有-ue选项(--undocumented elements)[1],这将导致未记录的元素在其doc运行期间生成的errors.html页面上作为警告列出。

此外,pear中的php_docblockgenerator[2]看起来可以为您生成缺少的docblock。

〔1〕 http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.undocumentedelements

〔2〕 http://pear.php.net/package/PHP_DocBlockGenerator

我们在工作中使用代码嗅探器实现这个功能,使用标准pear或zend标准。它不允许您动态编辑文件,但肯定会给您一个列表,其中有行和描述什么类型的docblock丢失。

小精灵, JC

不知道这是否有帮助,但是如果代码嗅探器可以指出函数/方法,那么一个像样的php ide(我提供phped)可以很容易地检查和构建每个函数的phpdoc注释。

简单型 /** 在每个功能上方按回车键,phped将自动完成代码 @param1 , PARAM1 , @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”注释(类和方法的区别,对吧?)然后检查编译器结构中是否实际存在相应的注释。如果没有,只需插入它们。预打印最终结果。 因为它可以访问表示代码的编译器结构,所以如您所建议的那样,生成参数并返回信息并不困难。当然,它不能做的是生成关于intended的评论 目的 ;但它可以生成一个占位符供您稍后填写。

最近我不得不做了大量的docblock修复的自动化工作,主要是基于上面的正确答案和一些特定于上下文的更改。这是一个黑客,但我在这里链接回来,以防将来对其他人有用。本质上,它在php beautifier中对注释块标记进行基本解析。

https://gist.github.com/israelshirk/408f2656100196e73367