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

Question

7

什么是在代码文档中放置示例用法的最佳实践？是否有标准化的方式？使用 @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) {

}

谢谢

- Ross

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Luca · Accepted Answer

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

我认为Doxygen和其他文档工具之间有一组常见的命令，但是它们对于好的文档来说太少了。你需要专门化才能从特定的工具中获得最佳效果。我喜欢Doxygen，因为它是开源的，并且高度可配置。但这只是我对它的看法。

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