7.1 KiB
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 :
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 :
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 :
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 :
// 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 :
/// 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, @throws ou @faults ; 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 :
@file-path
@package
@author
@created
@updated
@file-version
Leur rôle général est :
@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, faults, 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.