# 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. ---