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

Question

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

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

我已经尝试过Doxygen＆amp; amp;经常使用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，以允许解析使用其他文档工具定义的文档注释。