Documentation des sections
Chaque section de la documentation contient des informations sur une classe ou un module. Pour introduire le composant, il est possible d'écrire un bloc de section. La description courte est également utilisée dans la table des matières. Tous les @champs sont facultatifs.
/** * SECTION:meepapp * @short_description: the application class * @title: Meep application * @section_id: * @see_also: #MeepSettings * @stability: Stable * @include: meep/app.h * @image: application.png * * The application class handles ... */
- SECTION:<nom>
-
Le nom relie la section de la documentation à la partie respective dans le fichier <package>-sections.txt. Le nom fourni ici doit correspondre à la balise <FILE> du fichier <package>-sections.txt.
- @short_description
-
Une description de la section en une seule ligne, elle apparaîtra derrière les liens dans la table des matières et au début de la page de la section.
- @title
-
Par défaut, la section titre est celle de la déclaration SECTION: <nom>. Elle peut être modifiée grâce au champ @title.
- @section_id
-
Remplace l'utilisation du titre comme identificateur de section. Pour GObjects, <title> est utilisé à la place de section_id et pour les autres sections, c'est <MODULE>-<title>.
- @see_also
-
Une liste de symboles qui ont un lien avec cette section.
- @stability
-
Une description informelle du niveau de stabilité de cet API. Il est recommandé d'utiliser l'un de ces termes :
- « Stable » - L'intention d'une interface stable est de permettre à des parties tierces de développer des applications pour ces interfaces, de les distribuer et d'avoir l'assurance qu'elles fonctionneront avec toutes les versions mineures du produit (après celle où l'interface a été introduite et pour le même numéro de version majeur). De plus, à chaque version majeure, les modifications incompatibles doivent être rares et être sérieusement justifiées.
- « Unstable » - Les interfaces instables sont expérimentales ou en transition. Elles sont généralement utilisées pour que les développeurs extérieurs aient un accès précoce aux technologies nouvelles ou en évolution rapide, ou de fournir une solution temporaire à un problème pour lequel une solution plus générale est prévue. Aucune exigence n'est demandée à propos de la compatibilité binaire ou de celle des sources, d'une version mineure à l'autre.
- « Private » - C'est une interface qui peut être utilisée dans le noyau GNOME lui-même, mais qui n'est pas documentée pour les utilisateurs finaux. Ce type de fonctions ne doit être utilisé que dans des cas spécifiques et documentés.
- « Internal » - C'est une interface qui est interne à un module et qui ne nécessite pas de documentation pour l'utilisateur final. Les fonctions non documentées sont considérées comme internes.
- @include
-
Les fichiers #include à afficher dans le résumé de la section (liste d'éléments séparés par des virgules), elle outrepasse la valeur globale du fichier de section ou de la ligne de commande. Cet élément est facultatif.
- @image
-
L'image à afficher en haut de la page de référence pour cette section. C'est très souvent une espèce de diagramme pour illustrer l'apparence visuelle d'une classe ou un diagramme de ses relations avec d'autres classes. Cet élément est facultatif.
Pour éviter des recompilations inutiles après des modifications de la documentation, placez la documentation de section dans les fichiers sources C, lorsque cela est possible.