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)
The 'documentation' block is also different for each symbol type. Symbol types that get parameters such as functions or macros have the parameter description first followed by a blank line (just a '*'). Afterwards follows the detailed description. All lines (outside program listings and CDATA sections) just containing a ' *' (blank-asterisk) are converted to paragraph breaks. If you don't want a paragraph break, change that into ' * ' (blank-asterisk-blank-blank). This is useful in preformatted text (code listings).
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.
- Use #Object::signal to refer to a GObject signal.
- Use #Object:property to refer to a GObject property.
- 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.