Marquage « Exemple d'utilisation » dans la documentation de code

Question

Quelle est la meilleure pratique consistant à placer un exemple d'utilisation dans la documentation de code? Y at-il une façon normalisée? Avec un @usage ou @notes? Est-ce que les générateurs de documents ont tendance à soutenir cela?

Je sais que cette question devrait dépendre du générateur de documentation. Cependant, je suis en train de prendre l'habitude d'utiliser un style de commentaires pour la génération de doc avant d'entrer dans les particularités de chaque générateur; semble qu'il ya plus que de différences similarités.

Je l'ai expérimenté avec Doxygen et 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 configurer les chemins source exemple.

Je pense qu'il ya un ensemble de commandes entre Doxygen et d'autres outils de documentation, mais ils sont trop peu nombreux pour une bonne documentation. Vous devez specilize pour obtenir le meilleur d'un outil spécifique. J'aime Doxygen, car il est opensource et hautement configurable. Mais il est seulement 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.