Documenting sections

Each section of the documentation contains information about one class or module. To introduce the component one can write a section block. The short description is also used inside the table of contents. All the @fields are optional.

Example 3-4Section comment block
/**
 * SECTION:meepapp
 * @short_description: the application class
 * @title: Meep application
 * @section_id:
 * @see_also: #MeepSettings
 * @stability: Stable
 * @include: meep/app.h
 * @image: application.png
 *
 * The application class handles ...
 */

SECTION:<name>

The name links the section documentation to the respective part in the <package>-sections.txt file. The name given here should match the <FILE> tag in the <package>-sections.txt file.

@short_description

A one line description of the section, that later will appear after the links in the TOC and at the top of the section page.

@title

The section title defaults to <name> from the SECTION declaration. It can be overridden with the @title field.

@section_id

Overrides the use of title as a section identifier. For GObjects the <title> is used as a section_id and for other sections it is <MODULE>-<title>.

@see_also

A list of symbols that are related to this section.

@stability

An informal description of the stability level this API has. We recommend the use of one of these terms:

  • Stable - The intention of a Stable interface is to enable arbitrary third parties to develop applications to these interfaces, release them, and have confidence that they will run on all minor releases of the product (after the one in which the interface was introduced, and within the same major release). Even at a major release, incompatible changes are expected to be rare, and to have strong justifications.
  • Unstable - Unstable interfaces are experimental or transitional. They are typically used to give outside developers early access to new or rapidly changing technology, or to provide an interim solution to a problem where a more general solution is anticipated. No claims are made about either source or binary compatibility from one minor release to the next.
  • Private - An interface that can be used within the GNOME stack itself, but that is not documented for end-users. Such functions should only be used in specified and documented ways.
  • Internal - An interface that is internal to a module and does not require end-user documentation. Functions that are undocumented are assumed to be Internal.

@include

The #include files to show in the section synopsis (a comma separated list), overriding the global value from the section file or command line. This item is optional.

@image

The image to display at the top of the reference page for this section. This will often be some sort of a diagram to illustrate the visual appearance of a class or a diagram of its relationship to other classes. This item is optional.

To avoid unnecessary recompilation after doc-changes put the section docs into the c-source where possible.