Dokumentieren von Abschnitten
Jeder Abschnitt der Dokumentation enthält Informationen über eine Klasse oder ein Modul. Um eine Komponente hinzuzufügen, können Sie einen Abschnittsblock schreiben. Die Kurzbeschreibung wird auch im Inhaltsverzeichnis verwendet. Alle @-Felder sind optional.
/** * 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>
-
Der Name verweist auf die Abschnittsdokumentation des entsprechenden Teils der Datei <package>-sections.txt. Der hier angegebene Name sollte der Markierung <FILE> in der Datei <package>-sections.txt entsprechen.
- @short_description
-
Eine einzeilige Beschreibung des Abschnitts, die später hinter den Verweisen im Inhaltsverzeichnis und oben in der Abschnittsseite erscheint.
- @title
-
Der Abschnittstitel in der SECTION-Deklaration, Vorgabe ist <name>. Er kann im Feld @title überschrieben werden.
- @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
-
Eine Liste von Symbolen, welche sich auf diesen Abschnitt beziehen.
- @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
-
Das Bild, das am Beginn einer Referenzseite für diesen Abschnitt angezeigt wird. Meist wird es eine Art Diagramm für visuelle Erscheinungsbild einer Klasse oder ein Diagramm sein, das die Beziehungen zu anderen Klassen darstellt. Dieses Objekt ist optional.
Um unnötiges Rekompilieren nach Dokumentationsänderungen zu vermeiden, platzieren Sie die Abschnittsdokumentation in die C-Quellen, wo immer es möglich ist.