gtk2/docs/reference/README.md

# 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, converted into DocBook format, and
cross-linked in order to match types, functions, signals, and properties.
From the DocBook output, we generate HTML, which can be used to read the
documentation both offline and online.

In both cases, 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][contributing]. Please, refer to that document for any further
question on the mechanics of contributing to GTK.

GTK uses [gtk-doc][gtkdoc] to generate its documentation. Please, visit the
gtk-doc website to read the project's documentation.

[contributing]: ../../CONTRIBUTING.md
[gtkdoc]: https://wiki.gnome.org/DocumentationProject/GtkDoc

## 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:

```c
/**
 * 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:

```c
/**
 * 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][coding], 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.

[coding]: ../CODING-STYLE.md

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

### 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][gi-annotations].

[gi-annotations]: https://gi.readthedocs.io/en/latest/annotations/giannotations.html

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

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:

```c
/**
 * 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:

```c
/**
 * 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: ...
 *
 * ...
```