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. Bloc de commentaires pour les fonctions
- III.III.III. Bloc de commentaires pour les propriétés
- III.III.IV. Bloc de commentaires pour les signaux
- III.III.V. Bloc de commentaire pour les structures
- III.III.VI. 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.
(FIXME : informations de stabilité)
/** * 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. 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.
Jetez un coup d'œil aux étiquettes d'annotation de l'introspection gobject : http://live.gnome.org/GObjectIntrospection/Annotations
/** * 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.III. 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.IV. 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.V. Bloc de commentaire pour les structures
/** * FooWidget: * @bar: some #gboolean * * This is the best widget, ever. */ typedef struct _FooWidget { /*< private >*/ GtkWidget parent; /*< public >*/ gboolean bar; } FooWidget;
Utilisez /*< private >*/ avant les champs de structures privées que vous voulez cacher. Utilisez /*< public >*/ dans le cas contraire.
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.VI. 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.