Quelques conseils pour documenter correctement son code…

Documentation des fichiers du projet

Chaque fichier doit avoir sa documentation au début de celui-ci

Exemple

/**
 * @file Nom du fichier
 * @brief Résumé du rôle du module/classe
 * @brief On peut continuer le résumé sur plusieurs lignes
 * @author Auteur du fichier
 * @version v1.0
 * @class Nom de la classe (si POO)
 * @date 01/01/1900
 */

Documentation des fonctions ou méthodes

• La documentation doit être écrite dans les fichiers .h
• Chaque fonction/méthode doit avoir sa documentation avant son prototype

Cas général

/**
 * @fn  type nomFonction(type parametre1, type parametre2);
 * @brief Résumé de la fonction
 * @param type parametre1 : Le rôle du paramètre 1
 * @param type parametre2 : Le rôle du paramètre 2
 * @return type : le rôle de la valeur de retour
 */
    
type nomFonction(type parametre1, type parametre2);

Exemple : fonction int main()

/**
 * @fn  int main()
 * @brief fonction principale du prg
 * @brief Le rôle est à expliquer en fonction du programme
 * @return int : 0 si tout va bien, 
 * @return int : -1 en cas d'erreur
 */
    
string findClientName(int idClient);

Exemple : méthode string findClientName(int idClient);

/**
 * @fn  string findClientName(int idClient);
 * @brief trouve le nom du client en fonction de son id
 * @param int idClient : l'id du client à rechercher
 * @return string : nom du client
 */
    
string findClientName(int idClient);

Attribut des classes

• Chaque attribut doit être documenté ainsi

Cas général

type nom; //!< rôle de l'attribut

Exemple

QSqlDatabase _dbParking; //!< base de données

Balises supplémentaires

@code

Cette balise permet d’insérer un exemple de code dans la documentation

/**
 * @code
 * #include <iostream>
 *
 * int main()
 *{
 * //Your code
 *
 *  return 0;
 *}
 * @endcode
**/

Doxyfile

On peut ensuite générer la documentation grâce à doxygen

Si doxygen n’est pas installé sur le PC, exécuter la commande suivante

apt install doxygen graphviz doxygen-gui

Ensuite, on peut générer la documentation

• Soit, en suivant le doxywizard dans le dossier du projet

    doxywizard
  

• Soit en lançant directement la commande (il faut alors avoir un doxyfile)

    doxygen Doxyfile
  

Exemple de Doxyfile

Le fichier Doxyfile contient la configuration adaptée à votre projet pour générer la documentation.
Dans les projets modèles fournis aux étudiants, le fichier Doxyfile est déjà inclus dans les fichiers du projet.

Si ce n’est pas le cas, voici ci-dessous deux exemples de Doxyfile pour 2 langages courant.

Exemple de doxyfile C

Exemple de doxyfile cpp

Générer automatiquement la documentation avec le pipeline Gitlab CI/CD

• Ajouter le stage ci-dessous à votre fichier .gitlab-ci.yml

#image: debian:bookworm-slim //Si pas d'image dans le pipeline

stages:
  - deploy

pages:
    stage: deploy
    before_script:
      - apt-get update && apt-get install -y doxygen graphviz
    script:
        - doxygen Doxyfile
        - mv html/ public/
    artifacts:
        paths:
        - public

• La documentation générée est disponible dans “Pages” (Menu Deploy -> Pages)

• Vous pouvez modifier votre fichier readme.md pour inclure un lien vers votre documentation

• Exemple

  [Documentation du projet](https://lienversdoc)