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 can do more than just links. One can also have lists, examples, headings, and images. As of version 1.20, the preferred way is to use a subset of the basic text formatting syntax called Markdown. On older GTK-Doc versions any documentation that includes Markdown will be rendered as is. For example, list items will appear as lines starting with a dash.
In older GTK-Doc releases, if you need support for additional formatting, you would need to enable the usage of docbook SGML/XML tags inside doc-comments by putting --xml-mode or --sgml-mode in the variable MKDB_OPTIONS inside 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/) * * ![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!"); * ]| */
More examples of what markdown tags are supported can be found in the GTK+ Documentation Markdown Syntax Reference.
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.