gtk/docs/reference

How to contribute to GTK's documentation

The GTK documentation is divided in two major components:

• the API reference, which is generated from special comments in the GTK source code
• static pages that provide an overview of specific sections of the API

In both cases, the contents are parsed as markdown and cross-linked in order to match types, functions, signals, and properties. Ultimatively, we generate HTML, which can be used to read the documentation both offline and online.

Contributing to the GTK documentation requires modifying files tracked in the source control repository, and follows the same steps as any other code contribution as outlined in the GTK contribution guide. Please, refer to that document for any further question on the mechanics of contributing to GTK.

GTK uses [gi-docgen][gidocgen] to generate its documentation. Please, visit the gi-docgen website to read the project's documentation.

Contributing to the API reference

Whenever you need to add or modify the documentation of a type or a function, you will need to edit a comment stanza, typically right above the type or function declaration. For instance:

/**
 * gtk_foo_set_bar:
 * @self: a foo widget
 * @bar: (nullable): the bar to set
 *
 * Sets the given `GtkBar` instance on a foo widget.
 *
 * Returns: `TRUE` if the bar was set
 */
gboolean
gtk_foo_set_bar (GtkFoo *self,
                 GtkBar *bar)
{
  ...

Or, for types:

/**
 * GtkFoo:
 *
 * A foo widget instance.
 */
struct _GtkFoo
{
  /*< private >*/
  GtkWidget parent_instance;
};

The GTK documentation also contains a number of 'freestanding' chapters for which the source is in .md files in docs/reference/gtk.

Style guide

Like the coding style, these rules try to formalize the existing documentation style; in general, you should only ever modify existing code that does not match the rules if you're already changing that code for unrelated reasons.

Syntax

The input syntax for GTK documentation is Markdown, in a flavor that is similar to what you see on GitLab or GitHub. The markdown support for fragments that are extracted from sources is identical to the one for freestanding chapters. As an exception, man pages for tools are currently maintained in docbook, since the conversion from markdown to docbook is losing too much of the expected formatting.

In addition to typical markdown formatting such as *emphasis* or _italics_, the GTK documentation supports additional link formats, like:

[class@Namespace.ClassName] : Creates a link to the docs for a class

[method@Namespace.Method.name] : Creates a link to the docs for a method in a class

[func@Namespace.function] : Creates a link to the docs for a global function

For more information on the available link formats, see the gi-docgen documentation.

Every doc comment should start with a single-sentence paragraph that can serve as a summary of sorts (it will often be placed next to a link pointing to the full documentation for the symbol/class/etc). The summary should not include links.

Introspection annotations

The purpose of the annotations for function arguments, properties, signals, etc., is to describe the API in a machine readable way. The annotations are consumed by language bindings and by the documentation tools.

For more information about the annotations used by GTK, you should refer to the GObject Introspection documentation.

Type description

Each type should be annotated with a description of what the type does.

For classes, the description should contain an overview of the type; what it does; typical use cases; and idiomatic examples of its use.

For widget classes, the description should also contain:

• special XML elements and attributes parsed by the class, in case of a custom GtkBuildable implementation
• the CSS element name to be used by selectors
• the CSS selector hierarchy for children, in case of a composite widget
• the accessible role of the class

Each section in a type description can have a heading; it's preferred to use second and third level headings only.

Functions

• The argument names must match in the declaration, definition, and documentation stanza.
• The description should refer to the function as the subject, e.g.:

Adds a shortcut to the shortcuts controller.

Or:

Checks whether the widget is set to be visible or not.

Methods

• Methods are special functions whose first argument is always the instance of a certain class. The instance argument for newly written code should be called self.
• If a method is a setter or a getter for an object property, you should add an (attributes org.gtk.Method.set_property=property-name) or a an (attributes org.gtk.Method.get_property=property-name) annotation to the method's identifier
• If a method changes one or more properties as side effect, link those properties in the method's description
• If a method is a signal emitter, you should use the (attributes org.gtk.Method.signal=signal-name) annotation in the method's identifier

Arguments and return values

• Arguments should be descriptive, but short
• There is no need to mention the type of the argument
• Always annotate nullability, direction, and ownership transfer

Signals

• While GObject can introspect argument and return types for signals, you should always document them with an explicit documentation stanza.
• The syntax for signal stanzas is similar to functions:

/**
 * GtkFoo::signal-name:
 * @arg1: ...
 * @arg2: ...
 *
 * ...

Properties

• While GObject properties contain text that can be extracted programmatically in order to build their documentation, you should always document them with an explicit documentation stanza. The text associated to the property is short and meant to be used when programmatically building user interfaces, and not for documentation purposes.
• Always note if setting a property has side effects, like causing another property to change state.
• If the property has public accessors you should annotate it with the (attributes org.gtk.Property.set=setter_function) and (attributes org.gtk.Property.get=getter_function) attributes
• The syntax for property documentation is:

/**
 * GtkFoo:property-name:
 *
 * ...

Actions

• Actions are new in GTK 4, and describe an action associated to a widget class
• The syntax for action documentation is:

/**c
 * GtkFoo|action-name:
 * @arg1: ...
 * @arg2: ...
 *
 * ...