Dokumentationsavsnitt

Varje avsnitt av dokumentation innehåller information om en klass eller en modul. För att introducera komponenten kan man skriva ett avsnittsblock. Den korta beskrivningen används också i innehållsförteckningen. Alla @fälten är valfria.

Exempel 3-4Kommentarsblock för avsnitt
/**
 * SECTION:meepapp
 * @short_description: programklassen
 * @title: Meep-programmet
 * @section_id:
 * @see_also: #MeepSettings
 * @stability: Stable
 * @include: meep/app.h
 * @image: application.png
 *
 * Programklassen hanterar …
 */

SECTION:<namn>

Namnet länkar till avsnittsdokumentationen för respektive del i filen <paket>-sections.txt. Namnet som anges här bör matcha taggen <FILE> i filen <paket>-sections.txt.

@short_description

En enradsbeskrivning av avsnittet som senare kommer att visas efter länkar i innehållsförteckningen och lägst upp på avsnittssidan.

@title

Avsnittstiteln är som standard <namn> från SECTION-deklarationen. Den kan åsidosättas med fältet @title.

@section_id

Åsidosätter användningen av titeln som avsnittsidentifierare. För GObjects används <title> som ett section_id och för andra avsnitt är det <MODULE>-<title>.

@see_also

En lista över symboler som är relaterade till detta avsnitt.

@stability

En informell beskrivning över stabiliteten för detta API. Vi rekommenderar att använda en av dessa termer:

  • Stable - Avsikten med ett stabilt gränssnitt är att möjliggöra för tredje parter att utveckla program mot dessa gränssnitt, släppa dem och vara säkra på att de kommer att köra på alla programfixversioner av produkten (efter den i vilken gränssnittet introducerats, och inom samma huvudversion). Även vid en ny huvudversion förväntas inkompatibla ändringar vara få och vara väl motiverade.
  • Unstable - Instabila gränssnitt är experimentella eller i en övergångsfas. De används typiskt för att ge utomstående utvecklare tidig tillgång till ny eller snabbt föränderlig teknologi, eller för att tillhandahålla provisoriska lösningar för ett problem där en mer generell lösning förutses. Inga påståenden görs om endera källkods- eller binärkompatibilitet från en programfixversion till nästa.
  • Private - Ett gränssnitt som kan användas inom GNOME-stacken i sig, men som inte dokumenterats för slutanvändare. Sådana funktioner bör endast användas på angivna och dokumenterade sätt.
  • Internal - ett gränssnitt som är internt för en modul och inte behöver slutanvändardokumentation. Funktioner som är odokumenterade förutsätts vara interna.

@include

#include-filerna som ska visas i avsnittssammanfattningen (en kommaavgränsad lista), vilket åsidosätter det globala värdet från avsnittsfilen eller kommandoraden. Detta objekt är valfritt.

@image

Bilden som ska visas längst upp på referenssidan för detta avsnitt. Detta kommer ofta att vara någon form av diagram för att illustrera det visuella utseendet för en klass eller ett diagram över dess relationer med andra klasser. Detta objekt är valfritt.

För att undvika onödig omkompilering efter dokumentationsändringar, placera avsnittsdokumentationen i c-källkoden där möjligt.