documentation - 在代码文档中标记 "example usage"

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