文档章节

文档的每个章节都包含着关于一个类或模块的信息。要介绍它的组件,你可以编写一节注释块。在内容表格中也可以使用简短的描述。所有的@fields都是可选的。

Example 3-4节注释块
/**
 * 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

该节的单行描述,不久将出现在TOC里的链接后和该节页面的顶部。

@title

段落的标题在SECTION声明里默认是 <name> 。它可以由@title字段替换。

@section_id

替换标题的用途作为一个段落指示器。对于GObjects,<title>用作section_id且对于其它的段落它是<MODULE>-<title>。

@see_also

与本节相关的标识符。

@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

本章节的参考页顶部显示的图像。这常常是某些用于阐释一个类或者图表与其它类之间关系的可视化图示。这个项是可选的。

为避免不必要的重编译,在文档改动后尽可能把段落文档放入C代码中合适的位置。