Les commentaires de documentation de FLIN utilisent le préfixe ///. Ils s'attachent à la déclaration qui les suit immédiatement et sont des éléments de première classe de l'AST, capturés pendant le parsing, préservés pendant le formatage, et disponibles pour la génération automatique de documentation.
La distinction entre // et /// est faite au niveau du lexer. Les commentaires réguliers sont des notes pour le développeur actuel ; les commentaires de documentation sont un contrat avec tous les futurs développeurs. Les commentaires doc s'attachent à sept types de déclarations : fonctions, structs, entités, enums, types, blocs impl et champs.
L'implémentation a touché sept fichiers : le lexer (nouveau type de token DocComment), le scanner (détection de ///), l'AST (champ doc_comment: Option<String> sur tous les nœuds de déclaration), le parser (collecte et attachement), le générateur de code (mise à jour des patterns), le vérificateur de types (mise à jour des patterns), et le formateur (sortie avec préfixe ///).
Les commentaires de documentation sont une petite fonctionnalité avec un impact démesuré. Ils coûtent presque rien à implémenter mais permettent tout un écosystème d'outillage de documentation.
Ceci est la partie 175 de la série « Comment nous avons construit FLIN », documentant comment un CEO à Abidjan et un CTO IA ont conçu et construit un langage de programmation à partir de zéro.
Navigation de la série : - [174] Tests, benchmarks et fuzzing - [175] Commentaires de documentation dans FLIN (vous êtes ici) - [176] Démo embarquée et templates