documentation - 如何维护高级文档以及 phpdoc 生成的文档？

Question

对于我的第一个开源项目（无耻插件：mtChart），我目前有两种不同类型的文档：

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

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

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

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

Answer 1

如果您使用 phpdoc 样式，您显然知道您可以在其中做示例、教程等，并在必要时提供指向外部内容（如路线图）的链接。它并不理想，但绝对有效，并为您提供一致且有用的文档。只需在您的评论中使用一些格式以获得易于阅读的文本并@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
 */