Question

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

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

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
 */

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

1 个答案: