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.

Beispiel 3-4Abschnitts-Kommentarblock
/**
 * 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

Überschreibt den Einsatz von Titeln als Abschnitts-Bezeichner. Für GObjects wird der <Titel> als section_id verwendet and für andere Abschnitte <MODUL>-<Titel>.

@see_also

Eine Liste von Symbolen, welche sich auf diesen Abschnitt beziehen.

@stability

Eine informelle Beschreibung der Stabilitätsstufe dieser API. Wir empfehlen dafür einen der folgenden Begriffe:

  • Stabil - Die Absicht einer stabilen Schnittstelle ist es beliebigen Dritten es zu ermöglichen Anwendungen zu diesen Schnittstellen zu entwickeln, diese freizugeben und sich darauf verlassen zu können, dass diese mit allen Unterversionen des Produkts laufen (nach derjenigen, wo die Schnittstelle eingeführt wurde, und innerhalb der gleichen Hauptversion). Selbst bei einer Hauptversion kann man nicht von inkompatiblen Änderungen ausgehen, abgesehen von stark berechtigten.
  • Instabil - Instabile Schnittstellen sind experimentell oder vorübergehend. Sie werden typischerweise verwendet, um außenstehenden Entwicklern frühen Zugang zu neuen oder sich schnell ändernder Technologie zu geben, oder um eine Übergangslösung für ein Problem zu liefern, für das eine allgemeinere Lösung erwartet wird. Es werden keine Garantien zu Quell- oder Binärkompatibilität von einer minor-Freigabe zur nächsten gegeben.
  • Privat - Eine Schnittstelle, die im GNOME-Stack selbst verwendet werden kann, aber nicht für Endanwender dokumentiert ist. Solche Funktionen sollten nur auf spezifizierte und dokumentierte Weisen verwendet werden.
  • Intern - Eine Schnittstelle, die für ein Modul intern ist und keine Endanwender-Dokumentation erfordert. Undokumentierte Funktionen werden als intern angesehen.

@include

Die #include -Dateien werden im Abschnitt Zusammenfassung angezeigt (eine durch Kommata getrennte Liste). Der globale Wert aus der Abschnittsdatei oder von der Befehlszeile wird überschrieben. Dieser Punkt ist 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.