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

Question

Closed. This question is seeking recommendations for software libraries, tutorials, tools, books, or other off-site resources. It does not meet Stack Overflow guidelines. It is not currently accepting answers.

---

我们不允许提出寻求软件库、教程、工具、书籍或其他场外资源推荐的问题。您可以编辑问题，以便用事实和引文来回答。

6 年前已关闭。

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 作为输出，这会更容易使用一些自动化工具进行解析——这可能是某些文档块生成器的第一步；-)

Also, if you are using [phpDocumentor](http://www.phpdoc.org/) to generate the documentation, can this one not report errors for missing blocks ?

经过几次测试后，它可以——例如，在没有太多文档的类文件上运行它，使用 --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

但是，在这里，即使它很有用作为一个报告工具，它在生成丢失的文档块时并没有那么有帮助......

Now, I don't know of any tool that will pre-generate the missing docblocks for you : I generally use PHP_Codesniffer and/or phpDocumentor in my continuous integration mecanism, it reports missing docblocks, and, then, each developper adds what is missing, from his IDE...

这工作得很好：每天通常不超过几个丢失的文档块，因此该任务可以手动完成（当您编辑特定文件/方法时，Eclipse PDT 提供了为方法预先生成文档块的功能）。

除此之外，我真的不知道有任何全自动工具来生成文档块......但我很确定我们可以使用以下任一方法创建一个有趣的工具：

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

After a bit more searching, though, I found this blog-post *(it's in french -- maybe some people here will be able to understand)* : [Ajout automatique de Tags phpDoc à l'aide de PHP_Beautifier](http://fxnion.free.fr/articles/phpdoc-tags-php-beautifier.php).

*Possible translation of the title : "Automatically adding phpDoc tags, using PHP_Beautifier"*

这个想法实际上还不错：

• PHP_Beautifier 工具非常好当涉及到格式化一些格式不正确的 PHP 代码时，它非常强大
  • 我已经多次使用它来编写我什至无法阅读的代码^^
• 并且它可以使用它所谓的“过滤器”进行扩展。
  • 请参阅 PHP_Beautifier_Filter 了解提供的过滤器列表

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

• 一个新的 PHP_Beautifier 过滤器，它将检测以下标记：
  • T_CLASS
  • T_FUNCTION
  • T_INTERFACE
• 并在它们之前添加一个“草稿”文档块（如果还没有）

To run the tool on some `MyClass.php` file, I've had to first install `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 过滤器
• 美化文件的源代码，并将其回显到标准输出。

The code of the `beautifier-1.php` script will like this :

*(Once again, the biggest part is a copy-paste from the blog-post ; I only translated the comments, and changed a couple of small things)*

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

Now, if we run that `beautifier-1.php` script :

$ 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 [email protected] 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
• 上添加的docblock
• 在__construct方法 doSomething 上的 docblock 已经存在于我们的代码中：它尚未被删除。
• 有一些 @todo 标签 ^^

Now, it's not perfect, of course :

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

But I'm pretty sure that this idea could be used as a starting point to something a lot more interesting :

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

Answer 2

由于已经提到了 PHPCS，我引入了 Reflection API 来检查是否缺少 DocBlock。下面链接的文章是关于如何解决您的问题的简短教程：

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

还有一个 PEAR 包 PHP_DocBlockGenerator< /code>可以为包含、全局变量、函数、参数、类、常量、属性和方法（以及其他事物）创建文件页面块和文档块。

Answer 3

php-tracer-weaver 可以检测代码并生成具有参数类型的文档块，通过推导运行时分析。

Answer 4

您可以使用 PHP 的 Code Sniffer 根据一组预定义的编码准则来测试您的代码。它还将检查丢失的文档块并生成可用于识别文件的报告。

Answer 5

phpDocumentor 的 1.4.x 版本具有 -ue 选项（--undocumentedelements）[1]，这将导致未记录的元素在其文档运行期间生成的 error.html 页面上列为警告。

此外，PEAR 的 PHP_DocBlockGenerator [2] 看起来可以为您生成缺失的文档块。

[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

Answer 6

我们在工作中使用 codeniffer 来实现此功能，并使用标准 PEAR 或 Zend 标准。它不允许您即时编辑文件，但肯定会给您一个列表，其中包含缺少哪种文档块的行和描述。

哈特哈，
Jc

Answer 7

不知道这是否有帮助，但如果 Codesniffer 可以指出函数/方法，那么一个像样的 PHP IDE（我提供 PHPEd）可以轻松检查和构建每个函数的 PHPDoc 注释。

只需在每个函数上方输入 /** 并按 ENTER，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)  

不完全是一个自动化解决方案，但对于我这个懒惰的开发人员来说足够快了:)

Answer 8

您想真正自动化填写“javadoc”类型数据的问题吗？

可以配置 DMS 软件重新工程工具包来执行此操作。

它像编译器一样解析源文本，构建内部编译器结构，让您实现任意分析，对这些结构进行修改，然后重新生成（“prettyprint”）根据结构更改更改的源文本。它甚至保留了原始文本的注释和格式；您当然可以插入其他评论，它们就会出现，这似乎是您的主要目标。 DMS 为许多语言执行此操作，包括 PHP

您想要做的是解析每个 PHP 文件，找到每个类/方法，生成应该是该实体的“javadoc”注释（类和方法的区别，对吧？），然后检查编译器结构中是否实际存在相应的注释。如果没有，只需插入它们即可。 PrettyPrint 最终结果。
因为它可以访问表示代码的编译器结构，所以按照您的建议生成参数和返回信息应该不难。当然，它不能生成有关预期目的的注释；但它可以生成一个占位符供您稍后填写。

Answer 9

最近，我必须对文档块修复进行大量自动化，主要基于上面的正确答案以及一些特定于上下文的更改。这是一个 hack，但我会链接回此处，以防将来对其他人有用。本质上，它对 PHP Beautifier 中的注释块标记进行基本解析。

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