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

Question

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

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

1. 如何管理这么大的项目？如何创建可浏览的HTML文档？

2. 如何自动添加缺失的评论？
   （我使用Eclipse进行编码，但如果在其他编辑器中更容易，我不介意。）
   有很多函数声明如下：

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

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

Answer 1

我不确定这将满足您的要求多少。

但NetBeans IDE将为您提供文档帮助。

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

Here is a guide for documentation

请建议您是否能找到更好的。

Answer 2

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

https://github.com/cakephp/api_generator

Answer 3

我认为您不希望自动生成评论。您确实想要一种简单的方法来记录您的代码。自动文档编制的问题在于，使文档编写的程序对源代码的了解不多。它无法推断出如何使用代码，也无法建议为什么按原样组织代码。

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

还要避免添加

等无用的注释

@param int $ number

在方法中指定类型和变量名称的位置。这是完全没有用的评论。如果可以的话，添加有关如何使用参数的描述。如果很明显，只需将所有注释都删除即可。

关于文档的事情之一就是要了解最终用户的外观。实际上，出于这个原因，我实际上写了PHPFUI/InstaDoc。使用InstaDoc，您不必坐下来重新扫描整个项目。 InstaDoc使用PHP反射类实时呈现文档。因此，如果您正在处理代码，只需查找InstaDoc的本地副本即可查看您的类将如何记录自身。如果您发现有问题，请进行修复并刷新InstaDoc页面。繁荣！您的最新更改现已生效。

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