Documentation des symboles
Chaque symbole (fonction, macro, structure, énumération, signal et propriété) est documenté dans un bloc séparé. Il est mieux de placer le bloc près de la définition de son symbole pour faciliter sa synchronisation. Par conséquent, les fonctions sont habituellement documentées dans les fichiers sources C et les macros et les structures et les énumérations le sont dans le fichier d'en-tête.
- III.III.I. Étiquettes générales
- III.III.II. Annotations
- III.III.III. Bloc de commentaires pour les fonctions
- III.III.IV. Bloc de commentaires pour les propriétés
- III.III.V. Bloc de commentaires pour les signaux
- III.III.VI. Bloc de commentaire pour les structures
- III.III.VII. Bloc de commentaire pour les énumérations
III.III.I. Étiquettes générales
Vous pouvez ajouter des informations de version à tous les éléments de documentation pour indiquer quand l'API a été introduite ou quand elle est devenue obsolète.
- « Since »:
-
Texte indiquant depuis quelle version du code cette API est disponible.
- « Deprecated » :
-
Texte indiquant que cette fonction ne doit plus être utilisée. La description doit rediriger le lecteur vers la nouvelle API.
You can also add stability information to all documentation elements to indicate whether API stability is guaranteed for them for all future minor releases of the project.
The default stability level for all documentation elements can be set by passing the --default-stability argument to gtkdoc-mkdb with one of the values below.
- Stability: Stable
-
Mark the element as stable. This is for public APIs which are guaranteed to remain stable for all future minor releases of the project.
- Stability: Unstable
-
Mark the element as unstable. This is for public APIs which are released as a preview before being stabilised.
- Stability: Private
-
Mark the element as private. This is for interfaces which can be used by tightly coupled modules, but not by arbitrary third parties.
/** * foo_get_bar: * @foo: some foo * * Retrieves @foo's bar. * * Returns: @foo's bar * * Since: 2.6 * Deprecated: 2.12: Use foo_baz_get_bar() instead. */ Bar * foo_get_bar(Foo *foo) { ...
III.III.II. Annotations
Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list of the supported tags can be found on the wiki.
/** * foo_get_bar: (annotation) * @foo: (annotation): some foo * * Retrieves @foo's bar. * * Returns: (annotation): @foo's bar */ ... /** * foo_set_bar_using_the_frobnicator: (annotation) (another annotation) * (and another annotation) * @foo: (annotation) (another annotation): some foo * * Sets bar on @foo. */
III.III.III. Bloc de commentaires pour les fonctions
N'oubliez pas :
- d'indiquer si les objets, listes, chaînes, etc. retournés doivent être freed/unfreed/released,
- d'indiquer si les paramètres peuvent être NULL et ce qui se passe dans ce cas,
- de mentionner les pré-conditions et post-conditions intéressantes si nécessaire.
GTK-Doc considère que tous les symboles (macros, fonctions) commençant par « _ » sont privés. Ils sont traités comme des fonctions statiques.
/** * function_name: * @par1: description of parameter 1. These can extend over more than * one line. * @par2: description of parameter 2 * @...: a %NULL-terminated list of bars * * The function description goes here. You can use @par1 to refer to parameters * so that they are highlighted in the output. You can also use %constant * for constants, function_name2() for functions and #GtkWidget for links to * other declarations (which may be documented elsewhere). * * Returns: an integer. * * Since: 2.2 * Deprecated: 2.18: Use other_function() instead. */
- « Returns » :
-
Paragraphe décrivant le résultat retourné.
- @...:
-
Au cas où la fonction possède des arguments variables, vous devriez utiliser cette étiquette (@Varargs : peut également être utilisé pour des raisons historiques).
III.III.IV. Bloc de commentaires pour les propriétés
/** * SomeWidget:some-property: * * Here you can document a property. */ g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
III.III.V. Bloc de commentaires pour les signaux
N'oubliez pas :
- d'indiquer quand le signal est émis et s'il est émis avant ou après d'autres signaux,
- d'indiquer ce qu'une application peut faire dans le gestionnaire du signal.
/** * FooWidget::foobarized: * @widget: the widget that received the signal * @foo: some foo * @bar: some bar * * The ::foobarized signal is emitted each time someone tries to foobarize @widget. */ foo_signals[FOOBARIZE] = g_signal_new ("foobarize", ...
III.III.VI. Bloc de commentaire pour les structures
/** * FooWidget: * @bar: some #gboolean * * This is the best widget, ever. */ typedef struct _FooWidget { GtkWidget parent_instance; gboolean bar; } FooWidget;
Utilisez /*< private >*/ avant les champs de structures privées que vous voulez cacher. Utilisez /*< public >*/ dans le cas contraire.
If the first field is "g_iface", "parent_instance" or "parent_class" it will be considered private automatically and doesn't need to be mentioned in the comment block.
Les blocs de commentaire pour les structures peuvent aussi être utilisés avec GObjects et GObjectClasses. Il est normalement recommandé d'ajouter un bloc de commentaire pour une classe, si elle contient des vmethods (car c'est la manière de les documenter). Pour GObject, il est possible d'utiliser la documentation de section correspondante ; la présence d'un bloc séparé pour la structure de l'instance serait utile si l'instance possède des champs publics. Le désavantage ici étant que cela crée deux entrées d'index pour le même nom (la structure et la section).
III.III.VII. Bloc de commentaire pour les énumérations
/** * Something: * @SOMETHING_FOO: something foo * @SOMETHING_BAR: something bar * * Enum values used for the thing, to specify the thing. */ typedef enum { SOMETHING_FOO, SOMETHING_BAR, /*< private >*/ SOMETHING_COUNT } Something;
Utilisez /*< private >*/ avant les valeurs d'énumérations privées que vous voulez cacher. Utilisez /*< public >*/ dans le cas contraire.