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
-
An informal description of the stability level this API has. We recommend the use of one of these terms:
- Stable - The intention of a Stable interface is to enable arbitrary third parties to develop applications to these interfaces, release them, and have confidence that they will run on all minor releases of the product (after the one in which the interface was introduced, and within the same major release). Even at a major release, incompatible changes are expected to be rare, and to have strong justifications.
- Unstable - Unstable interfaces are experimental or transitional. They are typically used to give outside developers early access to new or rapidly changing technology, or to provide an interim solution to a problem where a more general solution is anticipated. No claims are made about either source or binary compatibility from one minor release to the next.
- Private - An interface that can be used within the GNOME stack itself, but that is not documented for end-users. Such functions should only be used in specified and documented ways.
- Internal - An interface that is internal to a module and does not require end-user documentation. Functions that are undocumented are assumed to be Internal.
- @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.