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.
- Use #Struct.field to refer to a field inside a structure and #GObjectClass.foo_bar() to refer to a vmethod.
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 can do more than just links. One can also have lists, examples, headings, and images. As of version 1.20, the preferred way is to use a subset of the basic text formatting syntax called Markdown. On older GTK-Doc versions any documentation that includes Markdown will be rendered as is. For example, list items will appear as lines starting with a dash.
While markdown is now preferred one can mix both. One limitation here is that one can use docbook xml within markdown, but markdown within docbook xml is not supported.
In older GTK-Doc releases, if you need support for additional formatting, you would need to enable the usage of docbook XML tags inside doc-comments by putting --xml-mode (or --sgml-mode) in the variable MKDB_OPTIONS inside Makefile.am.
/** * identifier: * * documentation paragraph ... * * # Sub Heading # * * ## Second Sub Heading * * # Sub Heading With a Link Anchor # {#heading-two} * * more documentation: * * - list item 1 * * Paragraph inside a list item. * * - list item 2 * * 1. numbered list item * * 2. another numbered list item * * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/) * *  * * [A link to the heading anchor above][heading-two] * * A C-language example: * |[<!-- language="C" --> * GtkWidget *label = gtk_label_new ("Gorgeous!"); * ]| */
More examples of what markdown tags are supported can be found in the GTK+ Documentation Markdown Syntax Reference.
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.