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.
/** * 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 «<», «>», «amp;lpar;», «amp;rpar;», «amp;commat;» «%» y «#» 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.
/** * 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/) * *  * * [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.