commit 12859673474ca2edffddebd410cfda4fccd091f5
parent fdc9e02dd25a1e4eb4b054bb899a50038c2d446b
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Tue, 23 Jun 2026 14:49:19 +0200
Ajoute la section sur les commentaires
Diffstat:
| M | doc/fr/star-c.7 | | | 70 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 70 insertions(+), 0 deletions(-)
diff --git a/doc/fr/star-c.7 b/doc/fr/star-c.7
@@ -359,6 +359,76 @@ en fin de fichier.
.Pp
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh LES COMMENTAIRES
+Utiliser des commentaires dès lors que la seule expressivité serrée du
+code ne permet pas d'exprimer l'entièreté du discours que les sources
+doivent rendre compte, ou la logique qu'il met effectivement en oeuvre.
+.Pp
+Si un commentaire occupe plusieurs lignes, ajouter un caractère
+.Ql *
+en début de ligne, aligné avec le caractère
+.Ql *
+de la ligne qui précède :
+.Bd -literal -offset Ds
+/* Valeurs de hachage initiales, à savoir les 32 premiers bits
+ * de la partie fractionnaire des racines carrées des 4 premiers
+ * nombres premiers (2, 3, 5 et 7) */
+state[0] = 0x6a09e667;
+state[1] = 0xbb67ae85;
+state[2] = 0x3c6ef372;
+state[3] = 0xa54ff53a;
+.Ed
+.Pp
+Les commentaires servent aussi à structurer la lecture du code source.
+Que ce soit à l'échelle des instructions, par un commentaire
+.Dq chapeau
+qui résume la séquence de code qui suit :
+.Bd -literal -offset Ds
+/* Enregistrer le résultat */
+((uint32_t*)hash)[0] = big_endian_32(state[0]);
+((uint32_t*)hash)[1] = big_endian_32(state[1]);
+((uint32_t*)hash)[2] = big_endian_32(state[2]);
+((uint32_t*)hash)[3] = big_endian_32(state[3]);
+.Ed
+.Pp
+ou à l'échelle du fichier, où les commentaires servent alors de
+séparateur entre ses différentes sections
+.Pq voir LA STRUCTURE D'UN FICHIER SOURCE .
+Dans ce cas, encadrer le commentaire par deux ligne de caractères
+.Ql *
+qui débute ou se termine par le caractère
+.Ql /
+si, respectivement, la ligne précède ou suit l'intitulé de la section :
+.Bd -literal -offset Ds
+/***********************************************************
+ * Définition des fonctions utilitaires
+ **********************************************************/
+static void
+process_chunk(uint32_t state[4], const char chunk[64])
+{
+ ...
+}
+.Ed
+.Pp
+À noter que dans l'exemple qui précède, la taille des lignes
+d'encadrement est limitée par des contraintes d'édition de la présente
+page de manuel.
+Dans un fichier source, étendre ces lignes pour qu'elles occupent la
+longueur maximale recommandée pour une ligne, à savoir 80 caractères.
+.Pp
+Pour expliciter le contexte général d'un fichier, en terme d'utilisation
+ou d'architecture logicielle, insérer un commentaire en en-tête du
+fichier en laissant les caractères d'ouverture ou de fermeture de
+commentaires sur une ligne séparée :
+.Bd -literal -offset Ds
+/*
+ * Interface de programmation des tableaux extensibles.
+ * Cette structure de données peut être utilisée avec des
+ * types de données qui ne nécessitent pas de processus
+ * d'initialisation ou de libération et qui peuvent être
+ * copiés bit à bit
+ */
+.Ed
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh LES FICHIERS D'EN-TÊTE
.Sh LA VISIBILITÉ DES SYMBOLES
.Sh LES BLOCS
