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

2018-06-15 22:11:37

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

}

谢谢

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

我认为Doxygen和其他文档工具之间有一套共同的命令，但对于良好的文档记录来说它们太少了。您需要特别指出从特定工具中获得最佳效果。我喜欢Doxygen，因为它是开源并且高度可配置的。但这只是我的看法。

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

链接地址: http://www.djcxy.com/p/45135.html