Documentation 标记"；示例用法“；在代码文档中

在代码文档中放置示例用法的最佳实践是什么？有没有标准化的方法？使用@usage或@notes？文档生成器是否倾向于支持这一点

我知道这个问题应该取决于文档生成器。然而，我试图在了解每个生成器的特性之前，养成在文档生成中使用注释样式的习惯；似乎相似之处多于差异

我曾尝试过doyGEN，经常使用AS3、JS、PHP、Obj-C、C++。 例如：

/**
 * My Function
 * @param object id  anObject 
 * @usage a code example here... 
 */
function foo(id) {

}

或

谢谢

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

我认为在Doxygen和其他文档工具之间有一组通用的命令，但是它们太少了，无法很好地进行文档记录。您需要具体化以从特定工具中获得最佳效果。 我喜欢Doxygen，因为它是开源的，高度可配置的。但这只是我的看法

---

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

非常感谢–这让我走上了正确的道路。很遗憾@example不能包含内联代码示例。

/**
 * My Function
 * @param object id  anObject 
 * @notes a code example here, maybe?
 */
function foo(id) {

}