replace obvious comments with non-obvious ones

Je suis en train de lire le code. Ce qui me frappe, c'est la place énorme que prend la doc "inutile" de ce style:

    /**
     * @brief Construct a new Solver object
     * 
     * @param filename[in] Name of the input file
     */
    Solver (std::string const& filename);      
    
    /**
     * @brief Destroy the Solver object
     */
    ~Solver ();

    /**
     * @brief Run the simulation
     */
    void run ();

    /**
     * @brief Finalize the simulation
     */
    void finalize ();

    /**
     * @brief Print the solver object information
     * 
     * @param out[in] Output stream
     * @param solver[in] Solver object
     * 
     * @return std::ostream& Output stream
     */
    friend std::ostream& operator<< (std::ostream& out, Solver const& solver);

qui pourrait devenir, sans aucune perte d'info

    Solver (std::string const& json_filename);   // <= note ici filename => json_filename (inputFileName serait bien aussi)
    ~Solver();        // tout le monde sait que c'est un desctructeur!!
    void run();       // on a compris! pas besoin de doc
    void finalize();  // pareil
    friend std::ostream& operator<<(std::ostream& out, Solver const& solver); // tout le monde connait ce type de fonction

Par contre, écrire au dessus de Solver

/// This class is the main class corresponding to a single SPH simulation. 
/// It is created once in the "main" function and it is run with the "run" command. 
/// Exceptions should be catched by the calling function.
/// The SOlver contains a Monitor and a Tracker in order to... (???)

Commenter aussi les variables:

    json        input;     // <= renomme ça inputJSON p expl; c'est plus explicite
    std::string inputFileName;
    std::string outputFileName;
    Timer*      timer;
    Tracker*    tracker;   ///< the tracker is used to ... (?)
    Monitor*    monitor;   ///< the monitor is used to ... (?)

En fait, en lisant ce fichier, j'ai trouvé aucune explication sur les questions que je me pose:

• c'est quoi un tracker ?
• c'est quoi un monitor ?

La doc de la classe Tracker est vide. Donc ma question reste ouverte.

Aucune doc liée à ses attributs

Par contre, dans ce fichier, je ne vois que de la doc que j'aurais pu écrire juste en dévinant ce que fait la fonction et en lisant son nom et le nom de ses paramètres:

    /**
     * @brief Compute the norm of the flow vector of each particle
     * 
     * @return std::vector<double> Norm of the flow vector of each particle
     */
    std::vector<double> get_flow_norm ();

ou encore

    /**
     * @brief Export the data
     * 
     * @param output[in] Name of the output file (which will be appended with the resolution step and the extension)
     * @param nStep[in] Resolution step
     * @param time[in] Current time of the simulation
     */
    void export_data (std::string output, int nStep, double time);

Bref, repasse sur tout le code, supprime la doc "évidente" et ajoute de la vraie doc.

Tu as clairement voulu faire du remplissage, mais ça n'apporte rien. Au contraire, ça diminue la lisibilité du code parce qu'on ne voit finalement que très peu d'info utile à l'écran.

Pose toi les questions:

• C'est quoi un tracker? c'est quoi un monitor? c'est quoi un Dynamics?
• Comment les objets sont-ils interconnectés? Pourquoi ces choix?
• Quel est le principe de fonctionnement de la classe? de la méthode?
• C'est quoi cette variable dont le nom n'est peut etre pas clair?

Exemple de bloc à commenter:

    int                    nDimensions             = 0;     ///< (ajoute du texte ici)
    size_t                 nParticles              = 0;     ///< (et essaye de dire des choses pas triviales)
    int                    maxNeighbors            = 0;
    double                 coupling                = 0.0;
    bool                   adaptiveSmoothing       = false;
    bool                   convergedAll            = true;
    int                    iterMax                 = 10;
    bool                   csvExport               = false;
    std::vector<double>    support                 = {};    ///< c'est quoi???
    std::vector<double>    state                   = {};    ///< et ca, c'est quoi? à quoi correspond state[i]? quelle est la taille de state?
    std::vector<double>    statePrevious           = {};    ///< etc...
    std::vector<int>       nNeighbors              = {};
    std::vector<size_t>    neighbors               = {};
    std::vector<int>       probeNumber             = {};
    std::vector<double>    exceedance              = {};
    std::vector<double>    vars                    = {};
    std::vector<bool>      converged               = {};
    std::vector<size_t>    outcastParticles        = {};
    double                 volumeAmplification     = 0.0;
    bool                   discardNotConverged     = false;

Fais la même chose pour Grid, Monitor, Dynamics...