docs(doxygen): Graphviz activé + cible de génération reproductible
HAVE_DOT = YES, mais CALL_GRAPH et CALLER_GRAPH restent à NO, et pas pour une question de coût : le moteur est signal-driven. powerBalanceChanged → verifyOverloadProtection() est une connexion Qt, invisible à l'analyse statique ; un graphe d'appel montrerait update() comme un point d'entrée orphelin et raterait le mécanisme principal de la couche L4. Un schéma faux vaut moins que pas de schéma. Ce que dot apporte réellement : héritage, collaboration, inclusions. SVG, lisible à toute échelle et diffable, avec DOT_GRAPH_MAX_NODES = 60 pour éviter les pavés illisibles. tools/gen-doc.sh : une seule commande, le Doxyfile épinglé. C'est la leçon du piège des générateurs — 163 avertissements sans sortie contre 113 avec HTML+XML sur le même arbre. Un chiffre de référence ne vaut que rattaché à une configuration exacte, et une commande unique empêche qu'on régénère « à sa façon ». Le script signale aussi une version de doxygen différente de la référence 1.9.8. Avertissement ajouté en tête du Doxyfile, à côté de celui sur les générateurs : le graphe d'héritage sera tronqué. EnergyArbitrator : public SmartChargingManager, mais l'amont est hors INPUT. C'est voulu — élargir INPUT ferait exploser le compte d'avertissements. Sans cette note, quelqu'un le « réparera ». graphviz est documenté comme dépendance de la cible doc, pas du build : build-cross-arm64 compile, il ne dessine pas. Hors de ce lot, comme convenu : \defgroup, carte \dot cliquable, WARN_AS_ERROR = YES, hébergement. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Patrick Schurig
parent
d9c16d34ea
commit
67f7059dcc
15
AGENTS.md
15
AGENTS.md
@ -523,6 +523,21 @@ supérieures n'affecte pas les couches inférieures. Voir `docs/SAFETY.md` pour
|
||||
`Doxyfile` (frontière = un répertoire) et se documentent à la main. Leur inventaire
|
||||
est tenu dans `energyplugin/smartchargingmanager.h`, au marqueur `[ETM] BEGIN` —
|
||||
toute nouvelle marque `[ETM]` dans un en-tête amont s'y ajoute.
|
||||
6. **Génération de la doc : `./tools/gen-doc.sh`, et rien d'autre.** Une commande
|
||||
unique, le `Doxyfile` du dépôt, épinglé. Un compte d'avertissements ne vaut que
|
||||
rattaché à une configuration exacte — 163 sans générateur de sortie contre 113 avec
|
||||
HTML+XML sur le même arbre — donc un chiffre produit « à sa façon » ne se compare à
|
||||
rien. Le script signale aussi une version de doxygen différente de la référence.
|
||||
- **Dépendances : `doxygen` et `graphviz`, de la CIBLE DOC uniquement.** Le paquet se
|
||||
construit sans elles ; le conteneur `build-cross-arm64` n'a rien à faire de
|
||||
Graphviz. Ne pas les ajouter aux `Build-Depends`.
|
||||
- `CALL_GRAPH`/`CALLER_GRAPH` restent à `NO` **délibérément** : le moteur est
|
||||
signal-driven, `powerBalanceChanged → verifyOverloadProtection()` est une connexion
|
||||
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.
|
||||
|
||||
## ROADMAP — configuration des priorités par l'utilisateur (post-beta)
|
||||
|
||||
|
||||
42
Doxyfile
42
Doxyfile
@ -11,6 +11,14 @@
|
||||
# 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.
|
||||
# « 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
|
||||
# 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
|
||||
# activés. Sans aucun générateur, doxygen 1.9.8 émet des « not documented » sur
|
||||
# des membres qui SONT documentés (constaté : 163 sans sortie, 113 avec
|
||||
@ -82,4 +90,36 @@ MARKDOWN_SUPPORT = YES
|
||||
OPTIMIZE_OUTPUT_FOR_C = NO
|
||||
HIDE_UNDOC_MEMBERS = NO
|
||||
HIDE_UNDOC_CLASSES = NO
|
||||
HAVE_DOT = NO
|
||||
|
||||
# --- Graphes (Graphviz) ----------------------------------------------------
|
||||
# graphviz est une dépendance de la CIBLE DOC, pas du build du paquet : rien à
|
||||
# installer dans le conteneur build-cross-arm64, qui n'a que faire de dot.
|
||||
# Debian/Ubuntu : apt install graphviz
|
||||
HAVE_DOT = YES
|
||||
|
||||
# CALL_GRAPH / CALLER_GRAPH restent à NO, et ce n'est pas une question de coût.
|
||||
# Le moteur est SIGNAL-DRIVEN : powerBalanceChanged → verifyOverloadProtection()
|
||||
# n'est pas un appel mais une connexion Qt, invisible à l'analyse statique. Un
|
||||
# graphe d'appel montrerait update() comme un point d'entrée orphelin et
|
||||
# raterait le mécanisme principal de la couche L4. Un schéma faux vaut moins
|
||||
# que pas de schéma.
|
||||
CALL_GRAPH = NO
|
||||
CALLER_GRAPH = NO
|
||||
|
||||
# Ce que dot apporte réellement ici : héritage, collaboration, inclusions.
|
||||
CLASS_GRAPH = YES
|
||||
COLLABORATION_GRAPH = YES
|
||||
INCLUDE_GRAPH = YES
|
||||
INCLUDED_BY_GRAPH = NO
|
||||
DIRECTORY_GRAPH = YES
|
||||
TEMPLATE_RELATIONS = NO
|
||||
|
||||
# SVG : lisible à toute échelle et diffable, contrairement au PNG.
|
||||
DOT_IMAGE_FORMAT = svg
|
||||
INTERACTIVE_SVG = YES
|
||||
|
||||
# Au-delà, doxygen tronque plutôt que de produire un pavé illisible — un graphe
|
||||
# qu'on ne peut pas lire ne documente rien.
|
||||
DOT_GRAPH_MAX_NODES = 60
|
||||
MAX_DOT_GRAPH_DEPTH = 3
|
||||
DOT_CLEANUP = YES
|
||||
|
||||
81
tools/gen-doc.sh
Executable file
81
tools/gen-doc.sh
Executable file
@ -0,0 +1,81 @@
|
||||
#!/bin/bash
|
||||
# SPDX-License-Identifier: GPL-3.0-or-later
|
||||
# Copyright (C) 2025 - 2026, Patrick Schurig / ETM PowerSync
|
||||
#
|
||||
# Génération reproductible de la documentation — UNE seule commande, le Doxyfile
|
||||
# du dépôt, épinglé.
|
||||
#
|
||||
# ./tools/gen-doc.sh
|
||||
#
|
||||
# Pourquoi une commande unique plutôt qu'un « doxygen » lancé à la main : le
|
||||
# nombre d'avertissements NE VEUT RIEN DIRE hors de sa configuration exacte. Le
|
||||
# piège a déjà été rencontré — 163 avertissements sans générateur de sortie
|
||||
# contre 113 avec HTML+XML, sur le même arbre. Un chiffre de référence ne se
|
||||
# compare qu'à un chiffre produit de la même façon ; ce script est cette façon.
|
||||
#
|
||||
# DÉPENDANCES — de la CIBLE DOC uniquement, jamais du build du paquet :
|
||||
# apt install doxygen graphviz
|
||||
# Le conteneur build-cross-arm64 n'a rien à faire de Graphviz : il compile, il
|
||||
# ne dessine pas.
|
||||
|
||||
set -u
|
||||
|
||||
RACINE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
DOXYFILE="$RACINE/Doxyfile"
|
||||
SORTIE="$RACINE/doc-generated"
|
||||
VERSION_ATTENDUE="1.9.8"
|
||||
|
||||
cd "$RACINE" || exit 1
|
||||
|
||||
manquant=0
|
||||
for outil in doxygen dot; do
|
||||
if ! command -v "$outil" >/dev/null 2>&1; then
|
||||
echo "MANQUANT : $outil" >&2
|
||||
manquant=1
|
||||
fi
|
||||
done
|
||||
if [ "$manquant" -ne 0 ]; then
|
||||
echo "" >&2
|
||||
echo "Dépendances de la cible doc : apt install doxygen graphviz" >&2
|
||||
exit 127
|
||||
fi
|
||||
|
||||
VERSION_REELLE="$(doxygen --version | cut -d' ' -f1)"
|
||||
if [ "$VERSION_REELLE" != "$VERSION_ATTENDUE" ]; then
|
||||
# Avertissement et non erreur : la génération reste utile, mais le compte
|
||||
# d'avertissements n'est plus comparable au chiffre de référence.
|
||||
echo "ATTENTION : doxygen $VERSION_REELLE, référence établie sous $VERSION_ATTENDUE." >&2
|
||||
echo " Les graphes restent valables ; le COMPTE d'avertissements," >&2
|
||||
echo " lui, n'est pas comparable d'une version à l'autre." >&2
|
||||
fi
|
||||
|
||||
rm -rf "$SORTIE"
|
||||
JOURNAL="$(mktemp)"
|
||||
trap 'rm -f "$JOURNAL"' EXIT
|
||||
|
||||
doxygen "$DOXYFILE" 2>"$JOURNAL"
|
||||
code=$?
|
||||
|
||||
# Le Doxyfile écrit déjà ses avertissements dans WARN_LOGFILE ; on compte ici ce
|
||||
# qui est réellement remonté, quelle que soit la destination.
|
||||
LOGFILE="$(sed -n 's/^WARN_LOGFILE *= *//p' "$DOXYFILE" | tr -d ' ')"
|
||||
if [ -n "$LOGFILE" ] && [ -f "$RACINE/$LOGFILE" ]; then
|
||||
JOURNAL_EFFECTIF="$RACINE/$LOGFILE"
|
||||
else
|
||||
JOURNAL_EFFECTIF="$JOURNAL"
|
||||
fi
|
||||
AVERTISSEMENTS="$(grep -c -i "warning" "$JOURNAL_EFFECTIF" 2>/dev/null || echo 0)"
|
||||
|
||||
echo ""
|
||||
echo " doxygen $VERSION_REELLE (référence $VERSION_ATTENDUE)"
|
||||
echo " graphviz $(dot -V 2>&1 | sed 's/^dot - graphviz version //; s/ .*//')"
|
||||
echo " configuration $DOXYFILE"
|
||||
echo " sortie $SORTIE (html/ + xml/)"
|
||||
echo " avertissements $AVERTISSEMENTS"
|
||||
echo ""
|
||||
echo " Rappel : ce compte n'est comparable qu'à un compte produit par CE script."
|
||||
echo " Rappel : le graphe d'héritage est tronqué par construction — la classe de"
|
||||
echo " base amont SmartChargingManager est hors INPUT. Voir l'en-tête du"
|
||||
echo " Doxyfile ; ne pas « réparer » en élargissant le périmètre."
|
||||
|
||||
exit $code
|
||||
Loading…
x
Reference in New Issue
Block a user