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

Question

对于我的第一个开源项目 ( shameless plug: 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
 */