在代码文档中标记"示例用法"

Question

在代码文档中放置示例用法的最佳做法是什么？有标准化的方式吗？使用@usage还是@notes？文档生成器是否倾向于支持这一点？

我知道这个问题应该取决于文档生成器.但是,我试图在进入每个生成器的特性之前习惯使用评论风格进行文档生成; 似乎有更多的相似之处而不是差异.

我已经尝试过Doxygen,经常使用AS3,JS,PHP,Obj-C,C++.

例如:

/**
 * My Function
 * @param object id  anObject 
 * @usage a code example here... 
 */
function foo(id) {

}

要么

/**
 * My Function
 * @param object id  anObject 
 * @notes a code example here, maybe?
 */
function foo(id) {

}

谢谢

Answer 1

Doxygen 有一个命令@example，并且有很多用于配置示例源路径的选项。

我认为 Doxygen 和其他文档工具之间有一组通用的命令，但对于良好的文档来说它们太少了。您需要专门化才能充分利用特定工具。我喜欢 Doxygen，因为它是开源的并且高度可配置。但这只是我的看法。

也许您可以使用@xrefitem别名配置 doxygen，以允许解析使用其他文档工具定义的文档注释。