Marcando "uso de ejemplo" en la documentación del código

Question

¿Cuál es la mejor práctica de colocar el uso de ejemplos en la documentación del código? ¿Hay una forma estandarizada? ¿Con @usage o @notes? ¿Los generadores de documentos tienden a apoyar esto?

Sé que esta pregunta debería depender del generador de documentación. Sin embargo, estoy tratando de adquirir el hábito de usar un estilo de comentario para la generación de documentos antes de entrar en la idiosincrasia de cada generador; parece que hay más similitudes que diferencias.

He experimentado con Doxygen & a menudo uso AS3, JS, PHP, Obj-C, C++.

Por ejemplo:

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

} 

o

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

} 

Gracias

Answer 1

Doxygen tiene un comando @example, y hay un montón de opciones para configurar rutas de ejemplo de código.

Creo que hay un conjunto común de comandos entre Doxygen y otras herramientas de documentación, pero son muy pocos para una buena documentación. Debe especializar para obtener lo mejor de una herramienta específica. Me gusta Doxygen, ya que es de código abierto y altamente configurable. Pero es solo mi opinión al respecto.

Quizás podría configurar doxygen con @xrefitem alias para permitir el análisis de los comentarios de documentación definidos con otras herramientas de documentación.