我有几个已完成的较旧的 PHP 项目，其中包含很多我想以 javadoc/phpDocumentor 样式记录的内容。
虽然手动处理每个文件并被迫与文档一起进行代码审查将是最好的事情，但我只是出于时间限制，对帮助我尽可能自动化任务的工具感兴趣。
我正在考虑的工具理想地具有以下功能：
解析 PHP 项目树并告诉我哪里有未记录的文件、类和函数/方法（即缺少适当的 docblock 注释的元素）
提供一种方法，通过创建空结构并在理想情况下在编辑器中打开文件（我不在乎内部或外部）中轻松添加缺少的文档块，以便我可以放入描述中。
选修的：
有问题的语言是 PHP，尽管我可以想象 C/Java 工具经过一些调整后可能能够处理 PHP 文件。
感谢您的大力投入！
我认为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 作为输出，使用一些自动化工具更容易解析——这可能是一些 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
但是，在这里，即使它作为报告工具很有用，在生成丢失的文档块时也没有那么有用......
现在，我不知道有什么工具可以为您预先生成丢失的文档块：我通常在我的持续集成机制中使用 PHP_Codesniffer 和/或 phpDocumentor，它会报告丢失的文档块，然后，每个开发人员都会添加缺少的内容，从他的 IDE...
...效果很好：通常每天丢失的文档块不超过几个，因此可以手动完成任务（并且 Eclipse PDT 提供了一个功能来为方法预生成文档块，当您编辑特定文件/方法）。
Appart 从那，我真的不知道任何全自动工具来生成 docblocks ......但我很确定我们可以设法创建一个有趣的工具，使用：
token_get_all解析 PHP 文件的源。
不过，经过一番搜索，我找到了这篇博文（它是法语的——也许这里的一些人能够理解）：Ajout automatique de Tags phpDoc à l'aide de PHP_Beautifier。
可能的标题翻译：“使用 PHP_Beautifier 自动添加 phpDoc 标签”
这个想法实际上还不错：
PHP_Beautifier在格式化一些格式不正确的 PHP 代码时，
该工具非常好用且功能强大PHP_Beautifier_Filter提供的过滤器列表我链接到的博客文章中使用的想法是：
T_CLASST_FUNCTIONT_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_BeautifierphpDoc我们刚刚下载的过滤器
脚本的代码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.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;
}
这是我们得到的结果——一旦我们的文件被 Beautified ：
<?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在方法中添加的 docblockdoSomething已经存在于我们的代码中：它没有被删除。@todo标签^^
现在，它当然并不完美：
protected $_myVar
但我很确定这个想法可以用作更有趣的事情的起点：
由于 PHPCS 已经被提及，我投入了反射 API 来检查丢失的 DocBlocks。下面链接的文章是关于如何解决问题的简短教程：
还有一个PEAR 包PHP_DocBlockGenerator可以为包含、全局变量、函数、参数、类、常量、属性和方法（以及其他东西）创建文件页面块和 DocBlocks。
php-tracer-weaver可以检测代码并生成具有参数类型的文档块，这些参数类型是通过运行时分析推断出来的。
您可以使用Code Sniffer for PHP 根据一组预定义的编码指南测试您的代码。它还将检查丢失的文档块并生成可用于识别文件的报告。
phpDocumentor 的 1.4.x 版本具有 -ue 选项 (--undocumentedelements) [1]，这将导致未记录的元素在其 doc 运行期间生成的 errors.html 页面上列为警告。
此外，PEAR 的 PHP_DocBlockGenerator [2] 看起来可以为您生成缺失的文档块。
我们在工作中使用代码嗅探器来实现此功能，使用标准 PEAR 或 Zend 标准。它不允许您即时编辑文件，但肯定会给您一个列表，其中包含缺少哪种 docblock 的行和描述。
HTH, Jc
您想真正自动化填写“javadoc”类型数据的问题吗？
DMS Software Reengineering Toolkit可以配置为执行此操作。
它像编译器一样解析源文本，构建内部编译器结构，让您实现任意分析，对这些结构进行修改，然后根据结构更改重新生成（“漂亮打印”）源文本。它甚至可以保留原始文本的注释和格式；您当然可以插入其他评论，它们会出现，这似乎是您的主要目标。DMS 为许多语言执行此操作，包括PHP
您想要做的是解析每个 PHP 文件，定位每个类/方法，生成应该是该实体的“javadoc”注释（类和方法的差异，对吗？），然后检查相应的注释是否实际存在于编译器结构。如果没有，只需插入它们。PrettyPrint 最终结果。因为它可以访问表示代码的编译器结构，所以按照您的建议，生成参数和返回信息应该不难。当然，它不能生成关于预期目的的评论；但它可能会生成一个占位符供您稍后填写。
不知道是否有任何帮助，但如果 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)
不完全是一个自动化的解决方案，但对于我作为一个懒惰的开发人员来说足够快:)
我最近不得不做大量的 docblock 修复自动化，主要是基于上面的正确答案 k 以及一些特定于上下文的更改。这是一个黑客，但我在这里链接，以防它在未来对其他人有用。本质上，它对 PHP Beautifier 中的注释块标记进行基本解析。