Commentaires de documentation
Un commentaire multi-ligne qui commence avec un symbole « * » supplémentaire indique un bloc de documentation qui sera traité par les outils GTK-Doc.
/** * identifier: * documentation ... */
L'« identifier » (identifiant) est une ligne contenant le nom de l'élément avec lequel le commentaire est lié. La syntaxe diffère légèrement en fonction de l'élément. (À FAIRE : ajouter un tableau montrant les identifiants)
Le bloc « documentation » est aussi différent pour chaque type de symbole. Les type de symbole qui prennent des paramètres comme les fonctions ou les macros commencent par une description des paramètres suivie par une ligne blanche (juste un « * »). Ensuite, vient la description détaillée. Toutes les lignes (à l'exception des sections de code et des sections CDATA) contenant seulement un « * » (espace-astérisque) sont converties en saut de paragraphe. Si vous ne désirez pas de saut de paragraphe, modifiez-les en « * » (espace-astérisque-espace-espace).
En documentant le code, deux aspects doivent être abordés :
- Ce que c'est : le nom d'une classe ou d'une fonction peut parfois être trompeur pour les personnes habituées à d'autres environnements.
- Ce qu'il fait : indiquer les usages courants. À mettre en relation avec les autres API.
L'un des avantages de l'hypertexte par rapport au texte simple, c'est la possibilité d'avoir des liens dans les documents. Écrire correctement le balisage d'un lien peut être fastidieux. GTK-Doc fournit plusieurs raccourcis utiles pour vous aider.
- Utilisez fonction() pour vous référer à des fonctions ou des macros qui prennent des arguments.
- Utilisez @paramètre pour vous référer aux paramètres. Utilisez-le aussi pour les paramètres d'autres fonctions, en relation avec celle décrite.
- Utilisez %constante pour vous référer à une constante, par ex. : %MA_CONSTANTE.
- Utilisez #symbole pour vous référer à d'autres types de symbole. Par exemple des structures, énumérations ou macros qui ne prennent pas d'arguments.
- Utilisez #Objet::signal pour vous référer à un signal GObject.
- Utilisez #Objet::propriété pour vous référer à une propriété GObject.
- Utilisez #Structure.champ pour vous référer au champ d'une stucture.
Si vous avez besoin d'utiliser les caractères spéciaux « '<', '> », « () », « @ », « % » ou « # » dans votre documentation sans que GTK-Doc ne les interprète, vous pouvez utiliser les entités XML « < », « > », « ( », « ) », « @ », « % », « # » ou les échapper en les précédant d'un antislash « \ ».
DocBook peut faire plus que des liens. Il peut aussi générer des listes, des tableaux et des exemples. Pour activer l'utilisation des balises SGML/XML DocBook dans les commentaires de documentation, vous devez avoir une des options --xml-mode ou --sgml-mode dans la variable MKDB_OPTIONS du fichier Makefile.am.
À partir de GTK-Doc 1.18, il est possible d'utiliser un sous-ensemble de la syntaxe markdown. On peut l'utiliser pour les sous-titres et les listes à puces simples. Dans des versions plus anciennes de GTK-Doc, le contenu est affiché tel quel (les éléments d'une liste sont affichés sur une seule ligne, séparés par des tirets).
/** * identifier: * * documentation ... * * # Sub heading # * * more documentation: * - list item 1 * - list item 2 * * Even more docs. */
Comme indiqué plus tôt, GTK-Doc est fait pour documenter les API publiques. On ne peut donc pas écrire de la documentation pour les symboles statiques. Néanmoins, il est bon de commenter ces symboles aussi. Cela aide les autres à comprendre votre code. Par conséquent, nous recommandons de les documenter à l'aide de commentaires normaux (sans le second « * » à la première ligne). Si, plus tard, la fonction doit être rendue publique, il suffira juste d'ajouter un « * » dans le bloc de commentaires et d'ajouter le nom du symbole à la bonne place à l'intérieur du fichier des sections.