Ubuntu-fr

tiky

Doxygen et bloc de code

Bonsoir,

J'utilise doxygen pour documenter automatiquement mon code et je cherche une solution pour documenter un bloc de code autre qu'une fonction, méthode ou classe. En fait je voudrais pouvoir inclure des commentaires sur certains passages difficiles du code. L'idée étant d'avoir le dît passage affiché dans le documentation. Par exemple si j'ai une boucle for contenant un algorithme dans une méthode d'une classe, je voudrais ajouter dans le description détaillée de cette méthode un paragraphe avec le morceau de code.

... ma_méthode( ... )
{
   ....
   /** Description du passage difficile
   * @code
   */
   code difficile
   /** @endcode
   */
   ....
}

Cette méthode fonctionne presque, seulement j'ai */ qui est inclus dans le code. Je ne veux pas faire un copier-coller du code car en cas de modification de celui-ci, il faut maintenir à jour le commentaire, vraiment pas pratique.

Je documente mon code pour que d'éventuels autres développeurs puissent venir m'aider et qu'ils puissent comprendre facilement la logique de l'application grâce à cette documentation.

Merci de votre aide.

---

Conseil d'expert: il vous faut un dentifrice adapté...

Link31

Re : Doxygen et bloc de code

Une fonction a une seule... fonction. Si ta fonction fait une opération compliquée, alors tu dois documenter ta fonction. Si elle fait 3 opérations dont une opération compliquée, alors il faut la séparer en 3 fonctions et documenter celle qui est compliquée.

Si tu insistes pour documenter quelques lignes de code, alors Doxygen n'est pas fait pour ça. Doxygen sert à documenter une API. Normalement, seules les fonctions publiques et protégées sont documentées de cette façon, alors ne parlons pas d'un bout de code...
Et la documentation d'une API est censée décrire ce que font les fonctions, pas comment elles le font.

Pour ton bout de code, fais comme tout le monde : place un simple commentaire (non-doxygen) au début du bloc, à destination des gens qui seront amenés à travailler sur ton code.

Dernière modification par Link31 (Le 23/09/2008, à 19:58)

tiky

Re : Doxygen et bloc de code

Une fonction a une seule... fonction. Si ta fonction fait une opération compliquée, alors tu dois documenter ta fonction. Si elle fait 3 opérations dont une opération compliquée, alors il faut la séparer en 3 fonctions et documenter celle qui est compliquée.

Si tu insistes pour documenter quelques lignes de code, alors Doxygen n'est pas fait pour ça. Doxygen sert à documenter une API. Normalement, seules les fonctions publiques et protégées sont documentées de cette façon, alors ne parlons pas d'un bout de code...
Et la documentation d'une API est censée décrire ce que font les fonctions, pas comment elles le font.

Pour ton bout de code, fais comme tout le monde : place un simple commentaire (non-doxygen) au début du bloc, à destination des gens qui seront amenés à travailler sur ton code.

Je sais tout ça, d'ailleurs ma fonction ne fait rien d'autre. Sinon doxygen ne sert pas que pour les API et mon commentaire explique ce que fait le morceau de code et pas comment il le fait. En fait je voulais juste inclure le code directement dans la page de doc pour que ce soit plus rapide à lire.

---

Conseil d'expert: il vous faut un dentifrice adapté...