67f7059dcc
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>
82 lines
3.0 KiB
Bash
Executable File
82 lines
3.0 KiB
Bash
Executable File
#!/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
|