Dokumentieren von Symbolen

Jedes Symbol (function, macro, struct, enum, signal und property) wird in einem separaten Block dokumentiert. Der Block wird am besten nahe der Definition der Symbole platziert, so dass es leichter ist, diese synchron zu halten. Die Funktion wird üblicherweise in den C-Quellen definiert, »macro«, »struct« und »enum« dagegen in der Header-Datei.

3.3.1. Allgemeine Markierungen

Sie können Versionsinformationen zu allen Dokumentationselementen hinzufügen, um darauf hinzuweisen, wann eine API eingeführt oder wann sie als veraltet markiert wurde.

Versionierungs-Markierungen
Since:

Beschreibung, seit welcher Version des Codes die API verfügbar ist.

Deprecated:

Absatz, der darüber informiert, dass diese Funktion nicht mehr genutzt werden sollte. Die Beschreibung sollte einen Verweis auf die neue API enthalten.

Sie können Stabilitätsinformationen zu allen Dokumentationselementen hinzufügen, um darauf hinzuweisen, ob API-Stabilität für alle Minor-Veröffentlichungen des Projekts garantiert wird.

Die Standard-Stabilitätsstufe für alle Dokumentationselemente setzen Sie durch Übergabe des Arguments --default-stability an gtkdoc-mkdb in einem der nachfolgend beschriebenen Werte.

Stabilitäts-Markierungen
Stability: Stable

Markiert das Element als stabil. Dies bezieht sich auf öffentliche APIs, für die für alle zukünftigen Minor-Veröffentlichungen des Projekts Stabilität gewährleistet ist.

Stability: Unstable

Markiert das Element als instabil. Dies bezieht sich auf öffentliche APIs, die als Vorschau vor der endgültigen Stabilisierung gedacht sind.

Stability: Private

Markiert das Element als privat. Dies bezieht sich auf Schnittstellen, die von eng damit verknüpften Modulen genutzt werden kann, aber nicht von beliebigen Drittanbietern.

Beispiel 3-5Allgemeine Markierungen
/**
 * foo_get_bar:
 * @foo: some foo
 *
 * Retrieves @foo's bar.
 *
 * Returns: @foo's bar
 *
 * Since: 2.6
 * Deprecated: 2.12: Use foo_baz_get_bar() instead.
 */
Bar *
foo_get_bar(Foo *foo)
{
...

3.3.2. Anmerkungen

Dokumentationsblöcke können Anmerkungs-Markierungen enthalten. Diese Markierungen werden als Tooltips (Minihilfen) dargestellt, die die jeweilige Bedeutung anzeigen. Sie werden von gobject-introspection genutzt, um Sprachbindungen zu erzeugen. Eine detaillierte Liste der unterstützten Markierungen finden Sie im Wiki.

Beispiel 3-6Anmerkungen
/**
 * foo_get_bar: (annotation)
 * @foo: (annotation): some foo
 *
 * Retrieves @foo's bar.
 *
 * Returns: (annotation): @foo's bar
 */
...
/**
 * foo_set_bar_using_the_frobnicator: (annotation) (another annotation)
 *                                    (and another annotation)
 * @foo: (annotation) (another annotation): some foo
 *
 * Sets bar on @foo.
 */

3.3.3. Kommentarblock einer Funktion

Bitte denken Sie an:

  • Dokumentieren, ob zurückgegebene Objekte, Listen, Zeichenketten usw. befreit/dereferenziert/freigegeben werden.
  • Dokumentiert, ob Parameter NULL sein können, und was in diesem Fall geschieht.
  • Erwähnen Sie interessante Vorbedingungen (und nachfolgende Bedingungen), wo es nützlich erscheint.

GTK-Doc nimmt an, dass alle Symbole (Makros, Funktionen), die mit »_« beginnen, privat sind. Sie werden wie statische Funktionen behandelt.

Beispiel 3-7Kommentarblock einer Funktion
/**
 * function_name:
 * @par1:  description of parameter 1. These can extend over more than
 * one line.
 * @par2:  description of parameter 2
 * @...: a %NULL-terminated list of bars
 *
 * The function description goes here. You can use @par1 to refer to parameters
 * so that they are highlighted in the output. You can also use %constant
 * for constants, function_name2() for functions and #GtkWidget for links to
 * other declarations (which may be documented elsewhere).
 *
 * Returns: an integer.
 *
 * Since: 2.2
 * Deprecated: 2.18: Use other_function() instead.
 */
Funktions-Markierungen
Returns:

Abschnitt, der das zurückgegebene Ergebnis beschreibt.

@...:

Wenn die Funktion variadische Argumente enthält, sollten Sie diese Markierung verwenden (@Varargs: funktioniert aus historischen Gründen ebenfalls).

3.3.4. Property-Kommentarblock

Beispiel 3-8Property-Kommentarblock
/**
 * SomeWidget:some-property:
 *
 * Here you can document a property.
 */
g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);

3.3.5. Signal-Kommentarblock

Bitte denken Sie an:

  • Dokumentiert, wann ein Signal ausgegeben wird und ob es vor oder nach anderen Signalen ausgegeben wird.
  • Dokumentiert, was eine Anwendung in dem Signal-Handler tun könnte.

Beispiel 3-9Signal-Kommentarblock
/**
 * FooWidget::foobarized:
 * @widget: the widget that received the signal
 * @foo: some foo
 * @bar: some bar
 *
 * The ::foobarized signal is emitted each time someone tries to foobarize @widget.
 */
foo_signals[FOOBARIZE] =
  g_signal_new ("foobarize",
                ...

3.3.6. Struct-Kommentarblock

Beispiel 3-10Struct-Kommentarblock
/**
 * FooWidget:
 * @bar: some #gboolean
 *
 * This is the best widget, ever.
 */
typedef struct _FooWidget {
  GtkWidget parent_instance;

  gboolean bar;
} FooWidget;

Verwenden Sie /*< private >*/ vor den privaten »struct«-Feldern, die Sie verbergen wollen. Um das umgekehrte Verhalten zu erzielen, verwenden Sie /*< public >*/.

Wenn das erste Feld »g_iface«, »parent_instance« oder »parent_class« ist, wird es automatisch als privat angesehen und muss nicht im Kommentarblock erwähnt werden.

Struct-Kommentarblöcke können auch für GObjects und GObjectClasses verwendet werden. Es ist ratsam, einen Kommentarblock für eine Klasse hinzuzufügen, wenn diese vmethods enthält (dies ist die Art der Dokumentation dafür). Für GObject selbst können Sie die jeweiligen Abschnittsdokumentationen verwenden, wobei ein separater Block für das Instanz-Struct sinnvoll ist, sofern die Instanz öffentliche Felder enthält. Ein Nachteil ist hier, dass dadurch zwei gleichnamige Indexeinträge erstellt werden (die Struktur und der Abschnitt).

3.3.7. Enum-Kommentarblock

Beispiel 3-11Enum-Kommentarblock
/**
 * Something:
 * @SOMETHING_FOO: something foo
 * @SOMETHING_BAR: something bar
 *
 * Enum values used for the thing, to specify the thing.
 */
typedef enum {
  SOMETHING_FOO,
  SOMETHING_BAR,
  /*< private >*/
  SOMETHING_COUNT
} Something;

Verwenden Sie /*< private >*/ vor den privaten »enum«-Werten, die Sie verbergen wollen. Um das umgekehrte Verhalten zu erzielen, verwenden Sie /*< public >*/.