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.

Ejemplo 3-2Bloque 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

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 hacer más que insertar enlaces. Puede tener listas, tablas y ejemplos. Para activar el uso de etiquetas SGML/XML dentro de comentarios en la documentación debe tener --xml-mode o --sgml-mode en la variable MKDB_OPTIONS dentro de Makefile.am.

Desde GTK-Doc-1.18 la herramienta soporta un subconjunto de lenguajes de marcado. Se pueden usar para títulos secundarios y listas de elementos simples. En versiones más antiguas de GTK-Doc el contenido se puede renderizar como tal (la lista de elementos aparecerá en una línea separada por guiones).

Ejemplo 3-3Bloque de comentario de GTK-Doc usando marcado
/**
 * identifier:
 *
 * documentation ...
 *
 * # Sub heading #
 *
 * more documentation:
 * - list item 1
 * - list item 2
 *
 * Even more docs.
 */

          

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.