Documentar símbolos
Cada símbolo (función, macro, estructura, enum, señal y propiedad) está documentado en un bloque separado. La mejor posición para el bloque es junto a la definición del símbolo de tal forma que sea fácil mantenerlos sincronizados. Por ello las funciones generalmente se documentan en el código C y las macros, estructuras y enum en el archivo de cabecera.
- 3.3.1. Etiquetas generales
- 3.3.2. Anotaciones
- 3.3.3. Bloque de comentario de función
- 3.3.4. Bloque de comentario de propiedad
- 3.3.5. Bloque de comentario de señal
- 3.3.6. Bloque de comentario de estructura
- 3.3.7. Enumerar bloques de comentarios
3.3.1. Etiquetas generales
Puede añadir información de versiones a todos los elementos de la documentación para mostrar cuándo se introdujo una API o cuándo se declaró obsoleta.
- Desde:
-
Descripción desde qué versión del código está disponible la API.
- Obsoleto:
-
Párrafo que denota que esta función no se debería usar más. La descripción debería informar al lector de la nueva API.
(ARREGLAR: estabilidad de la información)
/** * 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. Anotaciones
Los bloques de documentación pueden contener etiquetas de anotaciones. Estas etiquetas se renderizarán con consejos que describan su significado. Las etiquetas se usan en la introspección de GObject para generar vinculaciones del lenguaje. Puede obtener una lista detallada de las etiquetas soportadas en el 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. Bloque de comentario de función
Recuerde:
- El documento, dependiendo de si devuelve objetos, listas, cadenas, etc. debería liberarse/desreferenciarse/etc.
- El documento, dependiendo de si sus parámetros pueden ser nulos, y qué sucede si lo son.
- Mencionar precondiciones y postcondiciones interesantes donde sea apropiado.
GTK-Doc asume que todos los símbolos (macros, funciones) que empiezan por «_» son privados. Se tratan como funciones estáticas.
/** * 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. */
- Devuelve:
-
Párrafo que describe el resultado devuelto.
- @...:
-
En el caso de que la función tenga argumentos variados debe usar esta etiqueta (@Vargargs: también funciona por razones históricas).
3.3.4. Bloque de comentario de propiedad
/** * SomeWidget:some-property: * * Here you can document a property. */ g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
3.3.5. Bloque de comentario de señal
Recuerde:
- Documentar cuando la señal se emite e indica si se emite antes o después de otras señales.
- Documentar qué aplicación debe gestionar las señales.
/** * 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. Bloque de comentario de estructura
/** * FooWidget: * @bar: some #gboolean * * This is the best widget, ever. */ typedef struct _FooWidget { /*< private >*/ GtkWidget parent; /*< public >*/ gboolean bar; } FooWidget;
Use /*< private >*/ antes de campos de estructuras privadas que quiera ocultar. Use /*< public >*/ para revertir el comportamiento anterior.
También se pueden usar bloques de comentario para GObjects y GObjectClasses. Generalmente es buena idea añadir un bloque de comentario para una clase, si tiene «vmethods» (ya que así se pueden documentar). Para el GObject en si, se puede usar la sección relativa a la documentación, tener un bloque separado para la estructura de la instancia sería útil si la instancia tiene campos públicos. Una desventaja aquí es que esto crea dos entradas de índice con el mismo nombre (la estructura y la sección).
3.3.7. Enumerar bloques de comentarios
/** * 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;
Use /*< private >*/ antes de enumerar valores privados que quiera ocultar. Use /*< public >*/ para revertir el comportamiento anterior.