docs(doxygen): 14 → 6 avertissements, et correction de la note sur le graphe

Première génération réelle avec Graphviz (doxygen 1.9.8, la version de référence) : 14
avertissements, dont 8 introduits par moi cette session — \return et \param manquants sur
la charge utile sg-ready, claimedThingIds(), validateSet() et claimedRelays(). Corrigés.

Les 6 restants sont exactement relayrouter.h et energyarbitrator.h, les deux fichiers
différés jusqu'après l'étape 3 puisqu'ils vont être restructurés. Le résidu est donc
entièrement connu et daté.

CORRECTION — la note que j'avais écrite en tête du Doxyfile était fausse. Elle annonçait
que l'arête « EnergyArbitrator : public SmartChargingManager » n'apparaîtrait pas. Elle
apparaît : doxygen rend une classe de base non résolue en boîte simple. Ce qui manque est
derrière — la boîte est un cul-de-sac, sans membres, sans ancêtres, non cliquable (aucun
href dans le SVG). La conclusion ne change pas, ne pas élargir INPUT ; la description, si.

101 graphes SVG produits, 3,2 Mo de HTML, 1,8 Mo de XML.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -536,8 +536,9 @@ supérieures n'affecte pas les couches inférieures. Voir `docs/SAFETY.md` pour
      Qt et non un appel. Un graphe d'appel montrerait `update()` en point d'entrée
      orphelin et raterait le mécanisme principal de la couche L4.
    - Le graphe d'héritage est **tronqué par construction** : `SmartChargingManager` est
-     hors `INPUT`. Ne pas élargir le périmètre pour « réparer » — cela ferait entrer tout
-     l'amont dans la mesure.
+     hors `INPUT`. L'arête est dessinée, mais la boîte est un cul-de-sac — sans membres,
+     sans ancêtres, non cliquable. Ne pas élargir le périmètre pour « réparer » : cela
+     ferait entrer tout l'amont dans la mesure.
 
 ## ROADMAP — configuration des priorités par l'utilisateur (post-beta)
 

Doxyfile

@@ -11,12 +11,16 @@
 # sont peu nombreux, déjà marqués, et documentés à la main — cf. la définition
 # de fait dans AGENTS.md.
 #
-# ATTENTION — le graphe d'héritage sera TRONQUÉ, et c'est voulu.
+# ATTENTION — le graphe d'héritage est TRONQUÉ, et c'est voulu.
 # « class EnergyArbitrator : public SmartChargingManager » est l'arête la plus
-# intéressante du dépôt, et elle n'apparaîtra pas : la classe de base vit dans
-# energyplugin/, hors INPUT, donc doxygen ne la résout pas. Élargir INPUT pour
-# « réparer » le graphe ferait entrer tout le code amont dans la mesure et
-# ferait exploser le compte d'avertissements — exactement ce que le périmètre
+# intéressante du dépôt. Vérifié sur la sortie réelle (2026-08-11) : l'arête est
+# bien DESSINÉE — doxygen rend une classe de base non résolue en boîte simple.
+# Ce qui manque, c'est tout ce qu'il y a derrière : la boîte est un cul-de-sac,
+# sans membres, sans ancêtres, et non cliquable (aucun href dans le SVG). Le
+# graphe dit « ça hérite de là » sans pouvoir dire de quoi il hérite.
+# La cause est le périmètre : la classe de base vit dans energyplugin/, hors
+# INPUT. Élargir INPUT pour « réparer » ferait entrer tout le code amont dans la
+# mesure et exploser le compte d'avertissements — exactement ce que le périmètre
 # ci-dessus évite. Le graphe est incomplet par choix, pas par oubli.
 #
 # ATTENTION — le nombre d'avertissements dépend des générateurs de sortie

energyplugin/etm/adapters/sgreadyadapter.h

@@ -124,6 +124,8 @@ public:
      *  Sert à détecter qu'une PAC de configuration (LM-300) et une PAC enregistrée en dur
      *  commandent le même matériel — situation où deux adaptateurs se disputeraient les mêmes
      *  contacts et où le budget compterait la charge deux fois.
+     *
+     *  \return Union des relais de tous les états, sans doublon.
      */
     QSet<QString> claimedRelays() const { return allRelays(); }
 

energyplugin/etm/config/loadconfigstore.h

@@ -58,6 +58,10 @@ public:
      *  construit aucun adaptateur et ne commande rien ; l'interdire empêcherait de
      *  préparer une configuration de remplacement. La bascule \c enabled repasse par
      *  \c setConfigs(), donc par cette vérification.
+     *
+     *  \param configs Ensemble complet à confronter (les charges désactivées sont ignorées).
+     *  \param[out] error Motif de refus, en français, exploitable tel quel.
+     *  \return true si l'ensemble est cohérent ; false au PREMIER conflit rencontré.
      */
     static bool validateSet(const LoadConfigs &configs, QString *error = nullptr);
 

energyplugin/etm/types/loadconfig.h

@@ -77,6 +77,7 @@ struct LoadConfigSgReadyState
     QStringList relays;                //!< ThingIds \c power à FERMER pour cet état (les autres ouverts).
     double      estimatedPowerW = 0;   //!< Puissance ESTIMÉE (W) de cet état — jamais un engagement.
 
+    //! \return Forme sérialisée de cet état (clés \c state, \c relays, \c estimatedPowerW).
     QVariantMap toMap() const;
     //! \brief Construit depuis la forme sérialisée. \param map Map d'un état.
     //! \return État ; champs absents = valeurs par défaut, la validation est ailleurs.
@@ -93,13 +94,15 @@ struct LoadConfigSgReadyState
  */
 struct LoadConfigSgReady
 {
-    QList<LoadConfigSgReadyState> states;
+    QList<LoadConfigSgReadyState> states;  //!< Encodages déclarés, un par état SG-Ready.
     int minStateHoldS = 0;             //!< Maintien minimal d'état (s) — anti court-cycling.
 
+    //! \return Forme sérialisée (clés \c states, \c minStateHoldS).
     QVariantMap toMap() const;
     //! \brief Construit depuis la forme sérialisée. \param map Map \c sgReady.
     //! \return Charge utile NON validée — cf. \c LoadConfig::isValid().
     static LoadConfigSgReady fromMap(const QVariantMap &map);
+    //! \param s Numéro d'état SG-Ready (1 à 4).
     //! \return Vrai si l'état \p s est déclaré avec un encodage.
     bool hasState(int s) const;
 };
@@ -219,6 +222,9 @@ public:
      *
      *  Les identifiants sont normalisés via \c QUuid : la configuration mélange les formes
      *  avec et sans accolades, une comparaison textuelle laisserait passer le conflit.
+     *
+     *  \return ThingIds revendiqués, sous la forme \c {uuid} ; vide si le mécanisme n'en
+     *    nomme aucun.
      */
     QSet<QString> claimedThingIds() const;