Documentation Syntax

Basic Structure

GTK+ API Documentation is stored in C-style comment blocks that are formatted in a specific way. Each Documenation Block starts with a /** on its own line end ends with */, again on its own line. A Documentation Block should usually be located near the initial definition of the symbol.

The following types of symbols are supported:

• Function
• Property
• Signal
• Enumeration
• Structure
• Macros

The basic format looks like this:

   1  /**
   2   * identifier_name: (annotations)
   3   * @parameter_name: (annotations): description
   4   *
   5   * symbol description
   6   *
   7   * tag_name: (annotations): description
   8   */

A documentation block consists of a few parts. And each part consists of one or more fields, separated by a : character.

Each part has to start on its own line. Fields cannot span multiple lines except the various description fields.

The order is important. For example, putting a tag part before the symbol description part is invalid and will result in the symbol description to be mistaken for the tag description.

In the example above, we have:

• the start of a Documentation Block on line 1
• the Identifier Part on line 2
• a Parameter Part on line 3
• the Symbol Description on line 5
• a Tag Part on line 7
• the end of the Documenation Block on line 8

Identifier Part

   1  /**
   2   * identifier_name: (annotations)
   3   * ...
   4   */

The Identifier Part is required to identify the symbol. It must be on the line immediately following the start of the Documentation Block (/**).

This part consists of:

• a required identifier_name field

  • different kinds of symbols that can be documented and annotated are described in the

    GTK-Doc manual.

• an optional annotations field

Parameter Part

   1  /**
   2   * ...
   3   * @parameter_name: (annotations): description
   4   * ...
   5   */

The Parameter Part is optional. This means that there can be 0 or more parameters, depending on the symbol you are documenting.

This part consists of:

• a required parameter_name which starts with a @ character

  • this name should correspond with the parameter name of you function's signature.

• an optional annotations field

• a required description field (can be "empty")
  • can contain a single paragraph (multiple lines but no empty lines) of text.

Note that multiple parameter parts are never separated by an empty line.

Symbol Description Part

   1  /**
   2   * ...
   3   *
   4   * symbol description
   5   * ...
   6   */

The Symbol Description Part is optional. When present, it must always be preceded by an empty line. It can contain multiple paragraphs (multiple lines and empty lines) describing what the function, property, signal, enum, or constant does.

Tag Part

   1  /**
   2   * ...
   3   * tag_name: (annotations)||value: description
   4   * ...
   5   */

The Tag Part is optional. There can be 0 or more tags, depending on the symbol you are documenting.

This part consists of:

• a required tag_name

  • There are only four valid tags: Returns, Since, Deprecated, and Stability.

• an optional annotations field (Returns)
  OR
  an optional value field (Since, Deprecated, and Stability)

• a required description field (can be "empty")
  • can contain multiple paragraphs (multiple lines and empty lines) of text.

tag parts can safely be preceded or followed by an empty line.

Annotations

Annotations are a way to rigorously describe the aspects of a symbol that can't be determined automatically. See the GObject introspection documentation for more information.

Markdown Support

Most of the plain text sections of the Documentation Block Parts support a custom variant of the basic text formatting syntax called Markdown. See the Markdown Page for a complete description.

Supported Symbols

All symbols (macros, functions) starting with '_' are considered private.

Functions

Please remember to:

• Use correct annotations for memory management transfer of returned objects.
• Use correct annotations to indicate whether parameters can be NULL, and document what happens if they are.
• Use correct annotations to indicate whether parameters are used for output.
• Mention interesting pre-conditions and post-conditions where appropriate.

/**
 * function_name:
 * @par1: description of parameter 1. These can extend over more than
 * one line.
 * @par2: (out) (transfer full) (allow-none): 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: (element-type GtkWidget) (transfer container): a list of #GtkWidgets.
 *
 * Since: 2.2
 * Deprecated: 2.18: Use other_function() instead.
 */

Properties

/**
 * SomeWidget:some-property:
 *
 * Here you can document a property.
 */
g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);

Signals

Please remember to:

• Document when the signal is emitted and whether it is emitted before or after other signals.
• Document what an application might do in the signal handler.

/**
 * 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",
                ...

Structures

/**
 * FooWidget:
 * @bar: some #gboolean
 *
 * This is the best widget, ever.
 */
typedef struct _FooWidget {
  /*< private >*/
  GtkWidget parent;

  /*< public >*/
  gboolean bar;
} FooWidget;

Use /*< private >*/ before the private structure fields you want to hide. Use /*< public >*/ for the reverse behavior.

Structure Documentation Blocks can also be used for GObjects and GObjectClasses. It is usually a good idea to add a Documenation Block for a class if it has virtual methods (as this is how they can be documented). For the GObject itself one can use the related section documentation, having a separate block for the instance structure would be useful if the instance has public fields. One disadvantage here is that this creates two index entries of the same name (the structure and the section).

Enumerations

/**
 * 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;

Use /*< private >*/ before the private enumeration values you want to hide. Use /*< public >*/ for the reverse behavior.

Other formatting needs

Most other items that benefit from some inline formatting, such as environment variables, program names, filenames, paths, and code fragments, should just be enclosed in single backquotes. Variable names and literal strings should be enclosed in double quotes:

The program `bob` is looked up in the `PATH`. It calls `printf` on every line in `/etc/passwd`. `bob` uses the “prefix“ argument to determine the prefix for each line. the default is “bob“.

See Also

• GTK-Doc Manual

• Original Markdown spec

• GitHub Flavored Markdown