記錄cakephp項目

Question

這幾天我正在研究CakePhp項目，我想知道如何記錄它們。我在軌道上使用ruby，在框架的幫助下使文檔變得容易。

在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。

您需要將docblocks添加到appropriate tags的代碼中才能使用這些解決方案（某些IDE可以爲您生成這些解決方案）。 core CakePHP code（和associated documentation）可以作爲一個很好的例子。

一些微妙的標準記錄代碼時，我已經注意到了CakePHP的團隊使用：

1. 決不縮進的docblock評論，甚至是一個類的內部。這使您可以通過docblock滾動代碼掃描，並且還允許您輸入每行的完整水平寬度（通常約爲100個字符）。
2. 用句號（或句點）完成每個句子，因爲這是一個很好的信號，讓您知道文檔的每個部分是否完整且經過深思熟慮。