Marking "example usage" in code documentation

Posted by Ross on Stack Overflow See other posts from Stack Overflow or by Ross
Published on 2010-03-09T11:32:16Z Indexed on 2010/03/09 11:36 UTC
Read the original article Hit count: 176

What the best practice of placing example usage in code documentation? Is there a standardised way? With an @usage or @notes?

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) {

}

I know this question should dependent on the documentation generator, but any heads up appreciated...

I'm trying to get into the habit of using proper style. When time allow I'll get more into the generators. (I've experimented with Doxygen.) I often use AS3, JS, Obj-C, C++.

Thanks

© Stack Overflow or respective owner

Related posts about documentation

Related posts about documentation-generation