如何维护高级文档以及 phpdoc 生成的文档？答案

【问题标题】：How do I maintain high-level documentation along with phpdoc generated documentation?如何维护高级文档以及 phpdoc 生成的文档？
【发布时间】：2009-08-20 08:51:30
【问题描述】：

对于我的第一个开源项目 (shameless plug: mtChart)，我目前有两种不同类型的文档：

Doxygen 从代码中的 phpdoc-cmets 生成的 HTML 文件
Google 代码上的 wiki 页面（或者简单地说：附加文本文件）

Doxygen 文件确实很棒，但我错过了添加“高级”文档的可能性：教程、示例、系统概述、路线图等。

我如何以自动化的方式将这两者结合起来，以便我可以以某种方式自动更新代码文档，包括其余的文本？

（如有必要，我愿意离开 Doxygen。）

【问题讨论】：

您是在谈论如何生成关于如何在代码中使用注释中的类的教程？如果是这样，那听起来像是一个很酷且有趣的项目。你甚至可以推断出各种各样的事情。听起来很酷。
是和不是。我不想生成教程，我已经写了一些，并想以某种方式自动将它们与文档结合起来......
进入一致的文本集（HTML、txt、任何东西......）。就像我说的，Doxygen 或 phpDocumentor 可以生成完全足够的代码文档。我想知道我是否可以自动将任意文本添加到此文档中。

标签： documentation phpdoc

【解决方案1】：

如果您使用 phpdoc 样式，您显然知道您可以在其中执行示例、教程等，并在必要时提供指向外部内容（如路线图）的链接。它并不理想，但绝对有效，并为您提供一致且有用的文档。只需在您的 cmets 中使用一些格式以获取易于阅读的文本并使用 @see 获取链接。您也可以考虑使用内联标签，但我不确定您是否需要从一开始就这样做。

/**
 * @todo Need to move to the main framework
 *
 *        class: RegistrationPeer extends AbstractPeer
 *      package: Registration
 *   subpackage: Peer
 *
 *       method: findByUserId($userId)
 *   visibility: public
 *       static: yes
 *
 *         file: xxx
 *
 *        class: Registration extends AbstractModel
 *      package: Registration
 *   subpackage: Model
 *
 * Sample usage:
 * <code>
 * <?php
 *     $userId = $sessionManager->getRegUid();
 *     $registration = RegistrationPeer::findByUserId($userId);
 * ?>
 * </code>
 *
 * @see AbstractPeer
 * @see http://docs.google.com/Doc?docid=xxxx&hl=en
 *
 * @author xxx
 */

【讨论】：

感谢您的信息，我并不真正了解所有 phpdoc 的可能性。我想我会再次点击文档... :-)