v0.2.12

chapters/043-documentation-et-tests-de-conformite.md

@@ -0,0 +1,145 @@
+# 43. Documentation et tests de conformité
+
+## 43.1 Bible multifichier — V1 REQUIS — FIGÉ EN PRINCIPE
+
+La Bible doit être suffisamment complète pour implémenter V1.
+
+Les sections futures ne doivent pas masquer les trous normatifs V1.
+
+À partir de `0.2.12`, la distribution documentaire de référence devient multifichier. Une archive complète contient au minimum :
+
+```text
+README
+sommaire
+un fichier Markdown par chapitre
+un fichier compagnon examples + DO/DON'T par chapitre
+annexes référencées
+manifest de distribution
+```
+
+Le découpage physique ne change pas la portée normative d'une règle.
+
+## 43.2 Archives complètes et deltas SemVer — V1 REQUIS — FIGÉ EN PRINCIPE
+
+Une version de baseline est distribuée sous forme d'archive complète `full`.
+
+Les versions suivantes peuvent être distribuées sous forme de `delta` contenant uniquement les fichiers ajoutés, modifiés ou supprimés par rapport à une version de base explicitement déclarée.
+
+Le manifest d'un delta doit notamment identifier :
+
+```text
+version cible
+version de base
+fichiers ajoutés
+fichiers modifiés
+fichiers supprimés
+hashes des fichiers livrés
+```
+
+Un delta ne doit pas contenir des fichiers inchangés uniquement pour reconstruire artificiellement une archive complète.
+
+Une archive complète peut être régénérée périodiquement ou lors d'un changement structurel majeur.
+
+## 43.3 Examples / DO-DON'T — V1 REQUIS — DIRECTION FIGÉE
+
+Chaque chapitre possède un fichier compagnon destiné à transformer progressivement les règles en :
+
+```text
+DO
+DON'T
+WHY
+compiler error
+edge cases
+```
+
+Durant la phase `0.x`, la couverture de ces fichiers peut rester incomplète lorsque le chapitre lui-même contient encore les exemples historiques nécessaires à la compréhension. Avant la stabilisation V1, les exemples normatifs doivent être consolidés et une partie doit devenir des tests de conformité de la toolchain.
+
+## 43.4 Commentaires ordinaires — V1 REQUIS — FIGÉ
+
+Commentaires non documentaires :
+
+```text
+// commentaire de ligne
+/* commentaire de bloc */
+```
+
+Les commentaires de bloc sont imbriquables. Les commentaires ordinaires peuvent apparaître dans l'implémentation, y compris dans les corps exécutables. Leur contenu peut être Unicode.
+
+## 43.5 Saseldoc source — V1 REQUIS — FIGÉ
+
+Les commentaires documentaires sont :
+
+```text
+/// documentation de ligne
+/** documentation de bloc */
+```
+
+Ils ont la même sémantique documentaire avec deux ergonomies d'écriture différentes. Saselang ne reprend pas la redondance Javadoc/PHPDoc consistant à dupliquer systématiquement la signature via `@param`, `@return` ou `@throws` ; `saseldoc` dérive ces informations du programme.
+
+Une Saseldoc est autorisée uniquement lorsqu'elle est immédiatement attachée à une déclaration documentable. Elle n'est jamais un commentaire libre à l'intérieur d'un corps exécutable.
+
+Déclarations documentables selon leur existence syntaxique : types nominaux, fonctions, méthodes, `clsmethod`, `operator`, `construct`, `destruct`, fields, variables/constants top-level ou membres, variants d'enum et autres éléments structurels explicitement retenus par leur grammaire.
+
+Sont notamment interdits comme cible Saseldoc : variables/constantes locales, statements, expressions, blocs, branches `if`/`match`, paramètres pris isolément et contenu arbitraire d'une callable.
+
+Une Saseldoc orpheline ou non attachée à une déclaration documentable est une erreur.
+
+Les éléments non publics peuvent être documentés dans le source. Ils sont filtrés selon les paramètres de visibilité de `saseldoc` et doivent apparaître avec une indication structurelle/visuelle non ambiguë de leur visibilité dans les sorties qui les incluent.
+
+Le `construct` suit sa visibilité Saselang réelle pour la documentation. `destruct`, qui ne porte pas de modificateur de visibilité utilisateur, est classé comme **private** pour la génération documentaire et n'apparaît donc pas dans une documentation publique.
+
+Une génération publique ne doit pas afficher les membres privés comme un simple bloc annexe : ils sont absents si leur visibilité n'est pas incluse.
+
+## 43.6 Marqueurs documentaires persistants — V1 REQUIS — FIGÉ EN PRINCIPE
+
+Les marqueurs persistants appartiennent au format documentaire compris par `saseldoc`, pas à la grammaire ni à la sémantique du code Saselang.
+
+Réservation initiale :
+
+```text
+@file-path
+@package
+@author
+@created
+@updated
+@file-version
+```
+
+Leur rôle général est :
+
+```text
+@file-path     chemin documentaire attendu, normalement relatif à la racine du package
+@package       identité/coordonnée du package concerné
+@author        auteur/contributeur associé
+@created       date de création documentaire
+@updated       date ou timestamp de dernière mise à jour documentaire
+@file-version  version propre au fichier, distincte de la version package
+```
+
+Les variables éventuelles de template ou de génération telles que `@current-timestamp`, `@current-date`, `@current-author`, `@current-file-path` ou valeurs tirées d'un manifest ne font pas partie de Saselang ni du contrat obligatoire de `saseldoc`. Elles peuvent être interprétées/remplacées par un IDE, un générateur de template ou un outil tiers.
+
+Un marqueur `@...` inconnu dans un commentaire documentaire ne doit pas faire échouer `saseldoc` : il reste contenu documentaire opaque/littéral si aucun outil externe ne l'a remplacé.
+
+`@file-path` est documentaire ; le compilateur reste autoritaire sur le chemin physique, le `source_root`, le namespace et le nom déclaré. `saseldoc` peut signaler une incohérence documentaire mais le marqueur ne redéfinit jamais l'identité du symbole.
+
+## 43.7 `saseldoc` — V1 REQUIS — FIGÉ EN PRINCIPE
+
+`saseldoc` est l'unique générateur officiel. Il peut produire plusieurs vues et formats au moyen de paramètres, notamment documentation publique ou interne, format de sortie et destination.
+
+La visibilité n'est pas réduite artificiellement à un ordre total lorsque les domaines `protected`, `module` et `package` ne sont pas sémantiquement comparables. L'interface de filtrage doit pouvoir exprimer les ensembles de visibilité nécessaires sans falsifier le modèle d'accès du langage.
+
+Les signatures, types de paramètres, generics, visibilité, `Result`, `throws`, héritage et interfaces sont dérivés du modèle sémantique plutôt que redéclarés manuellement dans la Saseldoc.
+
+Les formats exacts V1 restent à finaliser avec la CLI, mais un format de sortie n'implique jamais un outil séparé.
+
+## 43.8 Shebang `.saselrun` — V1 REQUIS — FIGÉ EN PRINCIPE
+
+Une ligne `#!...` peut être reconnue uniquement comme première ligne physique de `main.saselrun`. Elle est ignorée par la grammaire Saselang et sert de métadonnée de lancement pour l'environnement extérieur.
+
+`#!` n'introduit pas un système d'attributs de style Rust. La commande de shebang recommandée sera définie lorsque la CLI finale sera figée.
+
+## 43.9 Sasemark — V1 RÉSERVÉ / FUTUR
+
+Format documentaire rigide dérivé de Markdown envisagé pour les spécifications/outils, mais distinct de la grammaire du langage et pouvant être spécifié séparément.
+
+---