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.

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

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

@see_also

A list of symbols that are related to this section..

@stability

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

FIXME having @title here, would put this title into a newly generated section file, but later would be obsolete (right?)

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

Documentation commentsDocumenting symbols