Question

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

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

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

解析PHP项目树并告诉我哪里有未记录的文件，类和函数/方法（即元素缺少相应的docblock注释）
提供一种方法，通过创建空结构轻松添加缺少的文档块，最好在编辑器中打开文件（内部或外部我不关心）所以我可以加入说明。

可选：

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

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

感谢您的宝贵意见！

Answer 1

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

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

还有一个PEAR Package PHP_DocBlockGenerator可以创建文件页面块和DocBlocks for includes，全局变量，函数，参数，类，常量，属性和方法（以及其他东西）。

Answer 2

php-tracer-weaver可以使用参数类型检测代码并生成docblock，并通过运行时分析进行推导。

Answer 3

您可以使用PHP Code Sniffer根据预定义的编码指南测试代码。它还会检查缺少的文档块，并生成可用于标识文件的报告。

Answer 4

phpDocumentor的1.4.x版本具有-ue选项（ - uncocumentedelements）[1]，这将导致未记录的元素在其文档运行期间生成的errors.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 5

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

HTH， JC

Answer 6

您想实际自动填写“javadoc”类型数据的问题吗？

DMS Software Reengineering Toolkit可以配置为执行此操作。

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

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

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

我最近不得不做大量的docblock修复自动化，主要基于上面的正确答案，并进行了一些特定于上下文的修改。这是一个黑客攻击，但我将链接回来，以防将来对其他任何人都有用。本质上，它在PHP Beautifier中对注释块标记进行基本解析。

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

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

9 个答案: