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

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.

Étiquettes de version
« 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é)

Exemple III.5 Étiquettes générales
/**
 * 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.

Exemple III.6 Annotations
/**
 * 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.

Exemple III.7 Bloc de commentaires pour les fonctions
/**
 * 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.
 */
Étiquettes de fonction
« 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

Exemple III.8 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.

Exemple III.9 Bloc de commentaires pour les signaux
/**
 * 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

Exemple III.10 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.VII. Bloc de commentaire pour les énumérations

Exemple III.11 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.