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
- 3.3.2. Annotations
- 3.3.3. Kommentarblock einer Funktion
- 3.3.4. Property-Kommentarblock
- 3.3.5. Signal-Kommentarblock
- 3.3.6. Struct-Kommentarblock
- 3.3.7. Enum-Kommentarblock
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.
- 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)
/** * 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. Annotations
Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list of the supported tags can be found on the wiki.
/** * 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.
/** * 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. */
- 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.4. Property-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.
/** * 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
/** * 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.7. Enum-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 >*/.