php - 记录 cakephp 项目

Question

这几天我正在处理几个 CakePhp 项目，我想知道我应该如何记录它们。我习惯使用 ruby​​ on rails，在框架的帮助下，文档制作变得很容易。

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

Answer 1

你应该试试 Api Generator plugin ( introduced here ) 用于给官方供电 CakePHP API .

它使用 Reflection class (在 PHP 5.2 及更高版本中可用)动态内省(introspection)代码的 docblock comments这意味着您不必为所做的每项更改重新生成文档。

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

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

您需要使用 appropriate tags 将文档 block 添加到您的代码中使这些解决方案中的任何一个都起作用(某些 IDE 可以为您生成这些解决方案)。 core CakePHP code (和 associated documentation )可以用作说明要求的一个很好的例子。

我注意到 CakePHP 团队在编写代码文档时使用了一些微妙的标准:

1. 切勿缩进文档 block 注释，即使是在类中也是如此。这允许您滚动浏览文档 block 的代码扫描，还允许您输入每行的完整水平宽度(通常大约 100 个字符)。
2. 用句号(或句点)结束每个句子，因为这是一个很好的信号，让您知道文档的每个部分是否完整且经过深思熟虑。