Question

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

Answer 1

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.