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.

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 Tags
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.

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 {
  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

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.