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

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，以允许解析使用其他文档工具定义的文档 cmets。