对于我的第一个开源项目(无耻插件:mtChart),我目前有两种不同类型的文档:
- Doxygen 从代码中的 phpdoc-comments 生成的 HTML 文件
- Google Code 上的 wiki 页面(或者简单地说:附加文本文件)
Doxygen 文件真的很棒,但我错过了添加“高级”文档的可能性:教程、示例、系统概述、路线图等。
如何以自动方式将这两者结合起来,以便我可以以某种方式自动更新代码文档,包括其余文本?
(如有必要,我愿意离开 Doxygen。)
对于我的第一个开源项目(无耻插件:mtChart),我目前有两种不同类型的文档:
Doxygen 文件真的很棒,但我错过了添加“高级”文档的可能性:教程、示例、系统概述、路线图等。
如何以自动方式将这两者结合起来,以便我可以以某种方式自动更新代码文档,包括其余文本?
(如有必要,我愿意离开 Doxygen。)
如果您使用 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
*/