146 lines
7.1 KiB
Markdown
146 lines
7.1 KiB
Markdown
# 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`, `@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 :
|
|
|
|
```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`, `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.
|
|
|
|
---
|