Documentar el código
GTK-Doc usa código fuente comentado con una sintaxis especial para documentar el código. Además obtiene información acerca de la estructura de su proyecto de otras fuentes. En la siguiente sección encontrará información acerca de la sintaxis de los comentarios.

Ubicación de la documentación
En el pasado la mayoría de la documentación se debía rellenar en campos dentro de la carpeta tmpl. Esto tiene las desventajas de que la información. Esto tiene las desventajas de que la información no se actualiza muy a menudo y que el archivo tiene tendencia a causar conflictos con los sistemas de control de versiones.
Para evitar los problemas anteriormente mencionados, se sugiere dejar la documentación dentro de los fuentes. Este manual sólo describe esta forma de documentar el código.
El analizador puede manejar bien la mayoría de cabeceras de C. En el caso de recibir avisos del analizador que parecen casos especiales, puede sugerir a GTK-Doc que los omita.

Bloque de comentario de GTK-Doc

#ifndef __GTK_DOC_IGNORE__
/* unparseable code here */
#endif

Limitaciones
Tenga en cuenta que GTK-Doc soporta #ifndef(__GTK_DOC_IGNORE__) pero #if !defined(__GTK_DOC_IGNORE__) u otras combinaciones.

Comentarios de la documentación
Un comentario de varias líneas que comienza con un «*» adicional marca un bloque de documentación que GTK-Doc tools procesarán.

Bloque de comentario de GTK-Doc

/**
 * identifier:
 * documentation ...
 */

El «identificador» es una línea con el nombre del elemento relacionado con el comentario. La sintaxis difiere un poco dependiendo del elemento. (Por hacer: añadir una tabla mostrando los identificadores)
El bloque de «Documentación» también es diferente para cada tipo de símbolo. Los tipos de símbolos que obtienen parámetros tales como funciones o macros, tienen primero las descripciones seguidas por una línea blanca (exactamente un «*»). Después siguen las descripciones detalladas. Todas las líneas (fuera de los programas; listados y CDATA de la secciones) que solo contengan un « *» (asterisco con espacio) se convierten en párrafos. Si no quiere un espaciado de párrafo, cámbielo a un « * » (espacio-asterisco-espacio). Esto es útil para texto preformateado (listados de código).
Al documentar código, describa dos aspectos:
Qué es: el nombre de la clase o la función puede confundir a veces a personas que provengan de otros entornos.
Qué hace: indique los usos comunes, en relación con las otras API.
Una ventaja del hipertexto sobre el texto plano es la capacidad de tener enlaces en el documento. Escribir las marcas adecuadas para un enlace puede ser tedioso aunque GTK-Doc le ayuda proporcionando abreviaturas útiles.
Use función() para referirse a funciones o macros que toman argumentos.
Use @parámetro para referirse a parámetros. Úselo también al referirse a parámetros de otras funciones, relacionados al que se describe.
Use %constant para referirse a una constante, ej: %G_TRAVERSE_LEAFS.
Use #símbolo para referirse a otro tipo de símbolos, como por ejemplo estructuras, enumeraciones y macros que no toman argumentos.
Use #Object::signal para referirse a una señal de GObject.
Use #Object:property para referirse a una propiedad de GObject.
Use #Struct.field para referirse a un campo dentro de una estructura y #GObjectClass.foo_bar() para referirse a un vmethod.
Si necesita usar los caracteres especiales «<», «>», «()», «@», «%», o «#» en su documentación sin que GTK-Doc los cambie, puede usar las entidades XML «&lt;», «&gt;», «amp;lpar;», «amp;rpar;», «amp;commat;» «&percnt;» y «&num;» respectivamente o escaparlas con una contrabarra doble «\».
DocBook puede crear algo más que enlaces. También se pueden tener listas, ejemplos, cabeceras e imágenes. En la versión 1.20, la manera prefefira de hacer esto es usando un subconjunto de la sintaxis básica de formateado de texto llamada Marcado. En versiones anteriores de GTK-Doc, cualquier documentación que incluya marcado se renderizará como tal. Por ejemplo, los elementos de una lista aparecerán como líneas que empiezan con un guión.
Aunque el marcado es el preferido, puede mezclar ambos. Una limitación aquí es que se puede usar docbook xml con marcado, pero el marcado con docbook xml no está soportado.
En versiones anteriores de GTK-Doc, si necesitaba soporte para formato adicional, necesitaba activar el uso de etiquetas XML dentro de comentarios en la documentación poniendo --xml-mode o --sgml-mode en la variable MKDB_OPTIONS dentro de Makefile.am.

Bloque de comentario de GTK-Doc usando marcado

/**
 * identifier:
 *
 * documentation paragraph ...
 *
 * # Sub Heading #
 *
 * ## Second Sub Heading
 *
 * # Sub Heading With a Link Anchor # {#heading-two}
 *
 * more documentation:
 *
 * - list item 1
 *
 *   Paragraph inside a list item.
 *
 * - list item 2
 *
 * 1. numbered list item
 *
 * 2. another numbered list item
 *
 * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)
 *
 * ![an inline image](plot-result.png)
 *
 * [A link to the heading anchor above][heading-two]
 *
 * A C-language example:
 * |[<!-- language="C" -->
 * GtkWidget *label = gtk_label_new ("Gorgeous!");
 * ]|
 */

Se pueden encontrar más ejemplos de las etiquetas de marcado soportadas en el Manual de referencia de sintaxis de marcado de documentación de GTK+.
Tal y como se ha mencionado antes, la documentación anterior de GTK-Doc es para documentar la API pública .Por ello, no se puede escribir documentación para los símbolos estáticos. No obstante es una buena práctica comentar los símbolos. Esto ayuda a que otros entiendan su código. Por ello se recomienda comentarlos usando comentarios normales (sin el segundo «*» en la primera línea). Si la función, posteriormente, se debe hacer pública, todo lo que el programador debe hacer es añadir otro «*» en el bloque de comentario e introducir el nombre del símbolo en la parte derecha dentro del archivo de secciones.

Documentar secciones
Cada sección del documento contiene información acerca de una clase o un módulo. Para introducir el componente puede escribir un bloque de sección. La descripción corta además se usa dentro de la tabla de contenidos. Todos los campos @ son opcionales.

Bloque de comentarios en una sección

/**
 * SECTION:meepapp
 * @short_description: the application class
 * @title: Meep application
 * @section_id:
 * @see_also: #MeepSettings
 * @stability: Stable
 * @include: meep/app.h
 * @image: application.png
 *
 * The application class handles ...
 */

SECCIÓN <nombre> 	 El nombre enlaza la sección de la documentación con la parte respectiva en el archivo <paquete>-sections.txt. El nombre aquí proporcionado debería coincidir con la etiqueta <ARCHIVO> en el archivo <paquete>-sections.txt.
@short_description 	 Una línea descrita en la sección, que después aparece tras los enlaces en el TOC y en la página de la sección.
@title 	 De forma predeterminada el título de la sección es <name> de la declaración SECTION. Se puede sobrescribir con el campo @title.
@section_id 	 Sobrescribe el uso del título como el identificador de sección. <title> se usa en GObjects como el identificador de sección (section_id) y para otra sección es <MÓDULO>-<title>.
@see_also 	 Una lista de símbolos relacionados con esta sección.
@stability 	 Esta API tiene una descripción informal del nivel de estabilidad. Se recomienda el uso de uno de estos términos:
Estable: La intención de una interfaz estable es la de permitir que terceras partes arbitrarias desarrollen aplicaciones para esas interfaces, las liberen, y confíen que que se podrán ejecutar en todas las publicaciones menores del producto (después de que se introdujese la interfaz en una de ellas, y dentro de la misma versión principal de la publicación). Incluso en publicaciones importantes no se espera que existan cambios incompatibles, y de haberlos habrá buenas razones para ello.
Inestable: Las interfaces inestables son experimentales o de transición. Generalmente se usan para dar a los desarrolladores externos acceso a tecnología nueva o cambiante, o para proporcionar una solución a un problema, anticipándose a una solución más general. No se realizan reclamaciones acerca de la compatibilidad del código o del binario desde una publicación menor a la siguiente.
Privada: Una interfaz que se puede usar en la pila de GNOME en si misma, pero que no está documentada para usuarios finales. Tales funciones sólo se deberían usar de formas especificadas y documentadas.
Interna: Una interfaz que es interna a un módulo y no requiere documentación para el usuario final. Se asume que las funciones que están sin documentar son internas.
@include 	 Los archivos #include para mostrar en la sección del resumen (una lista separada por comas), sobrescribiendo el valor global del archivo de secciones o de la línea de comandos. Este elemento es opcional.
@image 	 La imagen para mostrar en la parte superior de la página de referencia, para esta sección. Generalmente será un tipo de diagrama para ilustrar la apariencia visual de una clase o diagrama de su relación con otras clases. Este elemento es opcional.
Para evitar recompilaciones innecesarias después de cambios en la documentación ponga los documentos de sección en el código fuente C cuando sea posible.

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.

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.

Versionado de etiquetas
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.
También puede añadir información de estabilidad a todos los elementos de la documentación para indicar si la se garantiza la estabilidad de la API en todas las versiones menores futuras del proyecto.
El nivel de estabilidad predeterminado para todos los elementos de la documentación se puede establecer pasando el argumento --default-stability a gtkdoc-mkdb con uno de los siguientes valores.

Etiquetas de estabilidad
Estabilidad: estable 	 Marcar el elemento como estable. Esto es para API públicas que está garantizado que serán estables para todas las versiones menores futuras del proyecto.
Estabilidad: inestable 	 Marcar el elemento como inestable. Esto es para las API públicas que se publican como versión previa antes de estabilizarse.
Estabilidad: privado 	 Marcar el elemento como privado. Esto es para interfaces que se pueden usar en módulos fuertemente acoplados, pero no en terceras partes aleatorias.

Etiquetas generales

/**
 * 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)
{
...

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.

Anotaciones

/**
 * 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.
 */

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.

Bloque de comentario de función

/**
 * 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.
 */

Etiquetas de funciones
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).

Bloque de comentario de propiedad

Bloque de comentario de propiedad

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

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.

Bloque de comentario de señal

/**
 * 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[FOOBARIZED] =
  g_signal_new ("foobarized",
                ...

Bloque de comentario de estructura

Bloque de comentario de estructura

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

  gboolean bar;
} FooWidget;

Use /*< private >*/ antes de campos de estructuras privadas que quiera ocultar. Use /*< public >*/ para revertir el comportamiento anterior.
Si el primer campo es «g_iface», «parent_instance» o «parent_class» se considerará como privado automáticamente y no necesita mencionarse en el bloque de comentario.
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).

Enumerar bloques de comentarios

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.

Documentación en línea del programa
Puede documentar programas y su interfaz de línea de comandos usando la documentación en línea.

Etiquetas
PROGRAM 	 Define el inicio de la documentación de un programa.
@short_description: 	 Define una descripción corta del programa. (Opcional)
@synopsis: 	 Define el argumento o la lista de argumentos que el programa puede usar. (Opcional)
@see_also: 	 Página del manual Ver también. (Opcional)
@arg: 	 Argumentos pasados al programa y su descripción. (Opcional)
Description: 	 Una descripción más larga del programa.
Devuelve: 	 Especifique qué valores devuelve el programa. (Opcional)

Ejemplo de documentación de un programa.

Bloque de documentación del programa

/**
 * PROGRAM:test-program
 * @short_description: A test program
 * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
 * @see_also: test(1)
 * @--arg1 *arg*: set arg1 to *arg*
 * @--arg2 *arg*: set arg2 to *arg*
 * @-v, --version: Print the version number
 * @-h, --help: Print the help message
 *
 * Long description of program.
 *
 * Returns: Zero on success, non-zero on failure
 */
int main(int argc, char *argv[])
{
	return 0;
}

Etiquetas DocBook útiles
Aquí están varias etiquetas de DocBook muy útiles al documentar código.
Para enlazar otra sección en GTK docs:

<link linkend="glib-Hash-Tables">Hash Tables</link>

. El enlace es el id SGML en el elemento superior de la página a la que quiere enlazar. Para la mayoría de las páginas esta es la parte («gtk», «gdk», «glib») y después el título de página («Tablas hash»). Para los widgets es simplemente el nombre de la clase. Los espacios y guiones bajos se convierten a «-» para ajustarse a SGML/XML.
Para referirse a una función externa, ej. una función de C estándar:

<function>...</function>

Para incluir un código de ejemplo:

<example>
  <title>Using a GHashTable.</title>
  <programlisting>
      ...
  </programlisting>
</example>

o posiblemente este, para fragmentos de código muy cortos que no necesitan título:

<informalexample>
  <programlisting>
  ...
  </programlisting>
</informalexample>

. El último GTK-Doc también soporta abreviación: |[ ... ]|
Para incluir listas de topos:

<itemizedlist>
  <listitem>
    <para>
      ...
    </para>
  </listitem>
  <listitem>
    <para>
      ...
    </para>
  </listitem>
</itemizedlist>

Para incluir una nota que sobresale del texto:

<note>
  <para>
    Make sure you free the data after use.
  </para>
</note>

Para referirse a un tipo:

<type>unsigned char</type>

Para referirse a una estructura externa (no una descrita en la documentación de GTK):

<structname>XFontStruct</structname>

Para referirse a un campo o a una estructura:

<structfield>len</structfield>

Para referirse a un nombre de clase, se podría usar:

<classname>GtkWidget</classname>

pero probablemente estará usando #GtkWidget en su lugar (para crear automáticamente un enlace a la página GtkWidget; consulte abreviaciones).
Para enfatizar un texto:

<emphasis>This is important</emphasis>

Para uso de nombres de archivo:

<filename>/home/user/documents</filename>

Para referirse a claves:

<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>