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.

(FIXME : Stabilitätsinformation)

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. Kommentarblock einer Funktion

Bitte denken Sie an:

  • Document whether returned objects, lists, strings, etc, should be freed/unrefed/released.
  • 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.

Also, take a look at GObject Introspection annotation tags: http://live.gnome.org/GObjectIntrospection/Annotations

Beispiel 3-6Kommentarblock 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-Tags
Returns:

Abschnitt, der das zurückgegebene Ergebnis beschreibt.

@...:

In case the function has variadic arguments, you should use this tag (@Varargs: does also work for historic reasons).

3.3.3. Property-Kommentarblock

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

          

3.3.4. 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-8Signal-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.5. Struct-Kommentarblock

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

  /*< public >*/
  gboolean bar;
} FooWidget;

          

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

Struct comment blocks can also be used for GObjects and GObjectClasses. It is usually a good idea to add a comment block for a class, if it has vmethods (as this is how they can be documented). For the GObject itself one can use the related section docs, having a separate block for the instance struct would be useful if the instance has public fields. One disadvantage here is that this creates two index entries of the same name (the structure and the section).

3.3.6. Enum-Kommentarblock

Beispiel 3-10Enum-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 >*/.