如何为 PHP 项目创建自动代码文档？答案

【问题标题】：How do I create an automatic code documentation for a PHP project?如何为 PHP 项目创建自动代码文档？
【发布时间】：2014-02-21 08:45:07
【问题描述】：

我有一个使用 CakePHP 的大项目。现在我想为其他新同事创建一个文档。

一个想法是使用现有的 PHPdoc cmets 和代码中的其他 cmets 来创建一个自动文档。

如何管理这么大的项目以及如何创建可浏览的 HTML 文档？
如何自动添加缺少的 cmets？
（我使用 Eclipse 进行编码，但如果在另一个编辑器中更容易，我不会介意。）
有很多这样声明的函数：

# some explanation not in phpDoc
function whatever() {
....
}

如果我可以使用外部编辑器仅编辑 phpdoc cmets 并且它们会自动插入到源代码中的正确位置，那将是最佳选择。

【问题讨论】：

您是否专门寻找 phpDocumentor [phpdoc.org] 的 替代方法？
PHP_Beautifier 工具 mentioned here 听起来它可以做我想做的事，但这本身就是很多编程工作。我正在寻找已经完成的东西

标签： php cakephp phpdoc

【解决方案1】：

我不确定这能满足您的要求。

但 NetBeans IDE 会在文档方面为您提供帮助。

有关文档指南，您可以参考以下网站：

Here is a guide for documentation

如果你能找到更好的，请提出建议。

【讨论】：

【解决方案2】：

您可以使用ApiGenerator 插件。它是一个 Cake 插件，使用与 PhpDocumentor 相同的语法，生成文档只需要运行一个 shell 命令。

https://github.com/cakephp/api_generator

【讨论】：

【解决方案3】：

我认为您不需要自动生成评论。您真的想要一种简单的方法来记录您拥有的代码。自动文档的问题在于制作文档的程序不能比已经记录的源代码了解更多。它无法推断出如何使用代码，也无法说明为什么它的组织方式是这样的。

您最好的方法是命名方法和参数，以便它们对代码的其他用户有意义。简单明了的名字是最好的。还要确保尽可能输入参数和返回类型。知道一个方法需要一个浮点数而不是字符串，并返回一个 int 而不是 bool，这真的很有帮助。

还要避免添加像

这样无用的 cmets

@param int $number

您在方法中指定类型和变量名称的位置。这是一个完全没用的评论。如果可以，请添加有关如何使用参数的说明。如果很明显，请一起删除评论。

关于文档的其中一件事是了解最终用户对它的看法。出于这个原因，我实际上写了PHPFUI/InstaDoc。使用 InstaDoc，您不必坐下来重新扫描整个项目。 InstaDoc 使用 PHP 反射类来实时呈现文档。因此，如果您正在编写代码，只需访问 InstaDoc 的本地副本，以查看您的课程将如何记录自己。如果您发现有问题，请修复并刷新 InstaDoc 页面。繁荣！您的最新更改现已生效。

InstaDoc 还将为高容量网站生成静态页面。如果您发现 InstaDoc 有问题，请提交问题或 PR，我很乐意考虑。

【讨论】：