记录cakephp项目

Question

我现在正在研究几个CakePhp项目，我想知道如何记录它们。我在轨道上使用红宝石，在框架的帮助下轻松记录文档。

CakePhp中有这样的东西吗？我正在查看框架的文档，但我找不到任何相关内容。如果它不是框架的一部分，那么记录我的项目的正确方法是什么？

Answer 1

您应该尝试使用Api Generator plugin（introduced here）来支持官方CakePHP API。

它使用Reflection class（在PHP 5.2及更高版本中提供）动态内省您的代码docblock comments，这意味着您无需为每次更改重新生成文档。

还有一些额外的功能，例如代码的搜索索引，calculating documentation coverage，以及允许在docblock注释中使用Markdown在文档中生成HTML。

您始终可以使用适用于任何PHP代码库的通用解决方案，例如phpDocumentor或doxygen。

您需要使用appropriate tags将docblock添加到代码中，以使这些解决方案正常工作（某些IDE可以为您生成这些解决方案）。 core CakePHP code（和associated documentation）可以作为所需内容的一个很好的例子。

我注意到CakePHP团队在记录代码时使用了一些微妙的标准：

1. 即使在课堂内，也不要缩进docblock注释。这允许您通过docblock滚动扫描代码，并允许您输入每行的完整水平宽度（通常约100个字符）。
2. 完整句号（或句点）完成每个句子，因为这是一个很好的信号，让您知道文档的每个部分是否完整且经过深思熟虑。