Édition du fichier section

Le fichier section est utilisé pour organiser la documentation générée par GTK-Doc. C'est ici qu'il faut indiquer quels symboles sont attachés à quels modules ou classes et contrôler la visibilité (« public » ou « private »).

Le fichier section est un fichier texte plat, avec une syntaxe type XML (utilisant des balises). Les lignes blanches sont ignorées et celles commençant par un « # » sont considérées comme des lignes de commentaires.

La balise <FILE> ... </FILE> est utilisée pour indiquer le nom du fichier, sans extension. Par exemple, utiliser <FILE>gnome-config</FILE> va entraîner la sortie des déclarations de section dans le fichier prototype tmpl/gnome-config.sgml, qui seront converties dans le fichier SGML/XML DocBook sgml/gnome-config.sgml ou le fichier XML DocBook xml/gnome-config.xml (le nom du fichier html est basé sur le nom du module et le titre de la section, ou, pour les gobjects, sur le nom de la classe gobjects converti en minuscule).

La balise <TITLE> ... </TITLE> est utilisée pour indiquer le titre de la section. C'est utile seulement avant la création initiale des prototypes, car ensuite le titre défini dans le prototype est prioritaire. Elle est également obsolète si des commentaires de SECTION sont utilisés dans les fichiers sources.

Vous pouvez regrouper les éléments dans la section en utilisant la balise <SUBSECTION>. Actuellement, une ligne blanche est ajoutée entre les sous-sections dans la section résumé. Vous pouvez également utiliser <SUBSECTION Standard> pour les déclarations GObject standards (par exemple, les fonctions comme g_object_get_type et les macros comme G_OBJECT(), G_IS_OBJECT(), etc.). Actuellement, elles ne sont pas intégrées dans la documentation. Vous pouvez utiliser <SUBSECTION Private> pour les déclarations privées qui ne seront pas affichées (c'est un moyen pratique d'éviter les messages d'avertissement sur les déclarations inutilisées). Si votre bibliothèque contient des types privés que vous ne souhaitez pas voir apparaître dans la hiérarchie des objets et dans la liste des interfaces implémentées ou nécessaires, ajoutez-les à une sous-section privée. Le choix de placer des GObject ou GObjectClass comme des structures dans une section standard ou publique dépend de la présence d'éléments publics (variables, vmethods).

Vous pouvez utiliser les balises <INCLUDE> ... </INCLUDE> pour indiquer les fichiers #include qui sont affichés dans les sections résumé. Elles contiennent une liste de fichiers #include, séparés par des virgules, sans les chevrons. Si vous les placez en dehors d'une section, elles s'appliquent à toutes les sections jusqu'à la fin du fichier. Si vous les placez dans une section, elles s'appliquent seulement à cette section.