Marking "example usage" in code documentation
What is the best practice of placing example usage in code documentation? Is there a standardised way? With an @usage or @notes? Do document generators tend to support this?
I know this question should depend on the documentation generator. However, I'm trying to get a habit of using a commenting style for doc generation before getting into the idiosyncrasies of each generator; seems there are more similarites than differences.
I've experimented with Doxygen & often use AS3, JS, PHP, Obj-C, C++.
For example:
/**
* My Function
* @param object id anObject
* @usage a code example here...
*/
function foo(id) {
}
or
/**
* My Function
* @param object id anObject
* @notes a code example here, maybe?
*/
function foo(id) {
}
Thanks
Doxygen has a command @example, and there are a lot of options for configuring example source paths.
I think there are a common set of commands between Doxygen and other documentation tools, but they are too few for good documenting. You need to specilize to get the best from a specific tool. I like Doxygen, since it is opensource and highly configurable. But it is only my opinion about it.
Maybe you could configure doxygen with @xrefitem aliases to allow parsing documentation comments defined with other documentation tools.
链接地址: http://www.djcxy.com/p/45136.html下一篇: 在代码文档中标记“示例用法”