Marquage de "l'utilisation d'exemple" dans la documentation de code

Question

Quelle est la meilleure pratique de placer l'utilisation d'exemple dans la documentation de code? Y a-t-il une manière standardisée? Avec un @usage ou @notes? Les générateurs de documents ont-ils tendance à soutenir cela?

Je sais que cette question devrait dépendre du générateur de documentation. Cependant, j'essaie d'avoir l'habitude d'utiliser un style de commentaire pour la génération de doc avant d'entrer dans les idiosyncrasies de chaque générateur; Il semble qu'il y ait plus de similitudes que de différences.

J'ai expérimenté avec Doxygen & souvent utiliser AS3, JS, PHP, Obj-C, C++.

Par exemple:

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

} 

ou

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

} 

Merci

Answer 1

Doxygen a une commande @example, et il y a beaucoup d'options pour la configuration des chemins de source d'exemple.

Je pense qu'il existe un ensemble commun de commandes entre Doxygen et d'autres outils de documentation, mais ils sont trop rares pour une bonne documentation. Vous devez vous spécialiser pour tirer le meilleur parti d'un outil spécifique. J'aime Doxygen, car il est opensource et hautement configurable. Mais ce n'est que mon opinion à ce sujet.

Peut-être que vous pouvez configurer doxygen avec @xrefitem alias pour permettre l'analyse des commentaires de documentation définis avec d'autres outils de documentation.