Dokumentationssymboler

Varje symbol (funktion, makro, struktur, uppräkning, signal och egenskap) är dokumenterad i ett separat block. Blocket placeras bäst intill definitionen av symbolerna så att det är enkelt att hålla dem synkroniserade. Därför dokumenteras funktioner vanligtvis i c-källkoden och makron, strukturer och uppräkningar i huvudfilen.

3.3.1. Generella taggar

Du kan lägga till versioneringsinformation i alla dokumentationselement för att berätta när ett API introducerats eller blev föråldrat.

Versioneringstaggar
Since:

Beskrivning över från och med vilken version av koden som API:t är tillgängligt.

Deprecated:

Stycke som betecknar att denna funktion inte bör användas längre. Beskrivningen bör peka läsaren vidare till det nya API:t.

Du kan också lägga till stabilitetsinformation för alla dokumentationselement för att indikera huruvida API-stabilitet är garanterad för dem för alla framtida programfix-versioner av projektet.

Standardvärdet för stabilitetsnivån för alla dokumentations element kan ställas in genom att ange argumentet --default-stability till gtkdoc-mkdb med endera av värdena nedan.

Stabilitetstaggar
Stability: Stable

Markera elementet som stabilt. Detta är för publika API:er som är garanterade att hållas stabila i alla framtida programfix-versioner av projektet.

Stability: Unstable

Markera elementet som instabilt. Detta är för publika API:er som är släppta på förhand innan de blivit stabiliserade.

Stability: Private

Markera element som privat. Detta är avsett för gränssnitt som kan användas av tätt sammankopplade moduler, men inte av godtyckliga tredje parter.

Exempel 3-5Generella taggar
/**
 * foo_get_bar:
 * @foo: någon foo
 *
 * Hämtar bar från @foo.
 *
 * Returns: bar från @foo
 *
 * Since: 2.6
 * Deprecated: 2.12: Använd foo_baz_get_bar() istället.
 */
Bar *
foo_get_bar(Foo *foo)
{
…

3.3.2. Noteringar

Dokumentationsblock kan innehålla noteringstaggar. Dessa taggar kommer att renderas som verktygstips som beskriver deras syfte. Taggarna används av gobject-introspection för att generera språkbindningar. En detaljerad lista över vilka taggar som stöds hittas på wikisidan.

Exempel 3-6Noteringar
/**
 * foo_get_bar: (notering)
 * @foo: (notering): någon foo
 *
 * Hämtar bar från @foo.
 *
 * Returns: (notering): bar från @foo
 */
...
/**
 * foo_set_bar_using_the_frobnicator: (notering) (an annan notering)
 *                                    (ytterligare en annan notering)
 * @foo: (notering) (en annan notering): någon foo
 *
 * Ställer in bar i @foo.
 */

3.3.3. Kommentarsblock för funktioner

Kom ihåg att:

  • Dokumentera huruvida returnerade objekt, listor, strängar, etc. bör frigöras/avrefereras/släppas.
  • Dokumentera huruvida parametrar tillåts vara NULL och vad som händer om de är NULL.
  • Nämn intressanta förvillkor och eftervillkor där lämpligt.

Gtk-doc förutsätter att alla symboler (makron, funktioner) som börjar med ”_” är privata. De behandlas på samma sätt som statiska funktioner.

Exempel 3-7Kommentarsblock för funktioner
/**
 * funktionsnamn:
 * @par1:  beskrivning av parameter 1. Dessa kan sträcka sig
 *  över mer än en rad.
 * @par2:  beskrivning av parameter 2
 * @...: en %NULL-terminerad lista av flera bar
 *
 * Funktionsbeskrivningen ska vara här. Du kan använda @par1 för att
 * referera till parametrar så att de färgmarkeras i utdata. Du kan också
 * använda %konstant för konstanter, funktionsnamn2() för funktioner och
 * #GtkWidget för länkar till andra deklarationer (vilka kan vara dokumenterade
 * på annat håll).
 *
 * Returns: ett heltal.
 *
 * Since: 2.2
 * Deprecated: 2.18: Använd annan_funktion() istället.
 */
Funktions-taggar
Returns:

Stycke som beskriver det returnerade resultatet.

@...:

Om funktionen har variadiska argument bör du använda denna tagg (@Varargs: fungerar också på grund av historiska skäl).

3.3.4. Kommentarsblock för egenskaper

Exempel 3-8Kommentarsblock för egenskaper
/**
 * EnKomponent:en-egenskap:
 *
 * Här kan du dokumentera en egenskap.
 */
g_object_class_install_property (object_class, PROP_EN_EGENSKAP, …);

3.3.5. Kommentarsblock för signaler

Kom ihåg att:

  • Dokumentera när en signal sänds ut och huruvida den sänds ut före eller efter andra signaler.
  • Dokumentera vad ett program kan göra i signalhanteraren.

Exempel 3-9Kommentarsblock för signaler
/**
 * FooWidget::foobariserad:
 * @widget: komponenten som erhåller signalen
 * @foo: någon foo
 * @bar: någon bar
 *
 * Signalen ::foobarized sänds ut varje gång någon försöker att foobarisera @widget.
 */
foo_signals[FOOBARIZE] =
  g_signal_new ("foobarisera",
                ...

3.3.6. Kommentarsblock för strukturer

Exempel 3-10Kommentarsblock för strukturer
/**
 * FooWidget:
 * @bar: någon #gboolean
 *
 * Detta är den bästa komponenten någonsin.
 */
typedef struct _FooWidget {
  GtkWidget parent_instance;

  gboolean bar;
} FooWidget;

Använd/*< private >*/ före privata strukturfält som du vill gömma. Använd /*< public >*/ för det omvända beteendet.

Om det första fältet är ”g_iface”, ”parent_instance” eller ”parent_class” kommer det att anses vara privat automatiskt och behöver inte nämnas i kommentarsblocket.

Kommentarsblock för strukturer kan också användas för GObject och GObjectClass. Det är vanligtvis en bra idé att lägga till ett kommentarsblock för en klass om den har virtuella metoder (då detta är sättet på vilket de kan dokumenteras). För GObject i sig kan man använda den relaterade avsnittsdokumentationen, och ha ett separat block för varje instansstruktur vore användbart om instansen har publika fält. En nackdel här är att det skapar två indexposter med samma namn (strukturen och avsnittet).

3.3.7. Kommentarsblock för uppräkningar

Exempel 3-11Kommentarsblock för uppräkningar
/**
 * Something:
 * @SOMETHING_FOO: någonting foo
 * @SOMETHING_BAR: någonting bar
 *
 * Uppräkningsvärden som används för saken, för att specificera saken.
 */
typedef enum {
  SOMETHING_FOO,
  SOMETHING_BAR,
  /*< private >*/
  SOMETHING_COUNT
} Something;

Använd /*< private >*/ före privata uppräkningsvärden som du vill gömma. Använd /*< public >*/ för det omvända beteendet.