添加和完善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 fileWARNING 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 MyClassWARNING 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 onedone

但是在这里，即使它作为报告工具很有用，但在生成丢失的文档块时也没有帮助…

现在，我不知道有什么工具可以为您预先生成缺少的文档块：我通常在持续集成机制中使用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.phpcscp 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$sourcepre = 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 pre$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 pre is in $sourceCode// We could also have used the setInputFile method,// instead of having the pre in a variable$oToken->setInputString($sourcepre);        $oToken->process();// And here we get the result, all clean !   echo $oToken->get();

请注意，我还必须在中放置两个小内容

phpDoc.filter.php

现在，如果我们运行该

beautifier-1.php

$ php ./beautifier-1.php

对于

MyClass.php

class MyClass {    public function __construct($myString, $myInt) {        //     }        public function doSomething(array $params = array()) {        // ...    }    protected $_myVar;}

这是我们得到的结果-文件被美化后：

<?phpclass MyClass {        public function __construct($myString, $myInt) {        //    }        public function doSomething(array $params = array()) {        // ...    }    protected $_myVar;}

我们可以注意到：

• 文件开头的许可证块
• 在

  MyClass

  课程上添加的文档块

• __construct

  方法中已添加的文档块
• 上的docblock

  doSomething

  已经存在于我们的代码中：尚未删除。
• 有一些

  @todo

  标签^^

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

• 它并没有记录我们可能想要的所有东西
  • 例如，在这里，它没有记录

    protected $_myVar

• 它不会增强现有的文档块
• 而且它不会在任何图形编辑器中打开文件
  • 但这会困难得多，我想…

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

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