Federico Mena-Quintero
federico@gnome.org 2013
Philip Withnall
philip.withnall@collabora.co.uk 2015
El equipo de GTK+
Añadir documentación para bibliotecas y API
Daniel Mustieles
daniel.mustieles@gmail.com 2016-2020
Javier Mazorra
mazi.debian@gmail.com 2016, 2020

# Documentación

#

        Resumen

          Use gtk-doc con una configuración actualizada para la documentación de la API. (Consulte la sección )

            Use XML entities for including external symbols into the documentation.
            ()

            Use a consistent, standard, table of contents for all API documentation
            to maintain familiarity. ()

          Use gdbus-codegen para generar la documentación de la API de D-Bus que incluir en la construcción de gtk-doc. (Consulte la sección )
          Añada anotaciones de instrospección a toda la documentación de la API. (Consulte la sección )

            Add Since lines to all API documentation.
            ()

          Activar las pruebas de gtk-doc. ()

# gtk-doc

The preferred documentation system for GNOME libraries is gtk-doc, which extracts inline comments from the code to let you build a DocBook document and collection of HTML pages. These can then be read in Devhelp. A lot of GNOME’s infrastructure is built to handle with documentation written using gtk-doc.

# Sistema de construcción

To integrate gtk-doc into a project’s build system, follow the instructions in the gtk-doc manual. Note that while the sections.txt file is automatically generated the first time gtk-doc is run, it is not generated subsequently, and should be kept up to date manually. It should also be in version control.

gtk-doc’s `no-tmpl` flavour should be used, and XML mode should be used instead of SGML. (tmpl mode and SGML are both outdated and slower than XML.)

If the package version is needed to be substituted into the documentation, create a file named docs/version.xml.in, containing:

@PACKAGE_VERSION@

Add it to `AC_CONFIG_FILES` in configure.ac, then include it into the main documentation file (*-docs.xml) using: `<!ENTITY version SYSTEM "version.xml">` in the `DOCTYPE` at the top of the document. The package version can then be used inline as `&version;`.

# Distribución estándar

Using a standard layout for the table of contents, sections, appendices, etc. means the same project-name-docs.xml template can be reused with few changes between projects. It also means the documentation layout is similar across all projects, making it more familiar to developers.

Se sugiere la siguiente distribución:

## nombre-proyecto-docs.xml

A template top-level gtk-doc file for a project

# Licencia

Es importante aclarar la licencia utilizada para las referencias API, especialmente si contienen ejemplos de código que podrían copiarse.

Typically, projects use the same license for their API reference as for the project’s code itself, to avoid confusion. Some other projects use CC-BY-SA 3.0 for all their reference documentation. The choice is yours.

As shown in the Standard Layout you should include a license.xml in the top-level gtk-doc DocBook file which gives the full text of your documentation license.

# API públicas

Todas las API públicas deben tener comentarios de tipo gtk-doc. Para las funciones, estos se deben colocar en el código fuente, encima de la función.

/** * gtk_get_flow: * @widget: a #GtkWidget * * Gets the flow of a widget. * * Note that flows may be laminar or turbulent... * * Returns: (transfer none): the flow of @widget */ GtkFlow * gtk_get_flow (GtkWidget *widget) {

...

}

Los comentarios de documentación para macros, tipos de funciones, estructuras de clase, etc. deben colocarse junto a las definiciones, generalmente en archivos de encabezado.

Las introducciones de la sección deben colocarse en el archivo fuente que describen, después del encabezado de la licencia:

/** * SECTION:gtksizerequest * @Short_Description: Height-for-width geometry management * @Title: GtkSizeRequest * * The GtkSizeRequest interface is GTK+'s height-for-width (and * width-for-height) geometry management system. * ... */

Keep in mind that in order to include a function, macro, function type, or struct type, it needs to be listed in your documentation’s modulename-sections.txt file.

To properly document a new class, it needs to be given its own section in modulename-sections.txt, needs to be included in your toplevel modulename-docs.sgml, and the `get_type()` function for your class needs to be listed in your modulename.types.

# Anotaciones de instrospección

Each gtk-doc comment should have appropriate GObject introspection annotations. These are useful for two reasons:

Añaden información importante sobre los tipos de parámetros, la nulabilidad y la administración de memoria a la documentación de la API C generada por gtk-doc.

Permiten que las API públicas se vinculen automáticamente en otros lenguajes, como Python o JavaScript.

Las anotaciones de introspección agregan información a las API (funciones, parámetros de función, valores de retorno de función, estructuras, propiedades de GObject, señales de GObject) que de otro modo no está presente en la API de C legible por máquina y solo existe en forma de documentación o convenio legible por humanos. Son muy importantes.

In gtk-doc comments, annotations should be preferred over human-readable equivalents. For example, when documenting a function parameter which may be `NULL`, use the `(nullable)` annotation rather than some text:

/** * my_function: * @parameter: (nullable): some parameter which affects something * * Body of the function documentation. */

En lugar de:

/** * my_bad_function: * @parameter: some parameter which affects something, or %NULL to ignore * * Bad body of the function documentation. */

For more information on introspection, see the introspection guidelines.

# Versionado de símbolos

Whenever a symbol is added to the public API, it should have a documentation comment added. This comment should always contain a `Since` line with the package version number of the release which will first contain the new API. This should be the number currently in configure.ac if post-release version incrementing is being used.

Por ejemplo:

/** * my_function: * @param: some parameter * * Body of the function documentation. * * Since: 0.5.0 */

gtk-doc uses this information to generate indexes of the APIs added in each release. These should be added to the main *-docs.xml as an appendix:

<part> <title>Appendices</title> <index id="api-index-full"> <title>API Index</title> <xi:include href="xml/api-index-full.xml"><xi:fallback/></xi:include> </index> <index id="api-index-deprecated"> <title>Index of deprecated symbols</title> <xi:include href="xml/api-index-deprecated.xml"><xi:fallback/></xi:include> </index> <index role="0.1.0"> <title>Index of new symbols in 0.1.0</title> <xi:include href="xml/api-index-0.1.0.xml"><xi:fallback/></xi:include> </index> <!-- More versions here. --> <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> </part>

# API de D-Bus

D-Bus interface descriptions contain documentation comments, and these can be extracted from the XML using gdbus-codegen, and turned into DocBook files to be included by gtk-doc.

The DocBook files can be included in the main *-docs.xml file using:

<chapter> <title>C Interfaces</title> <partintro> <para>C wrappers for the D-Bus interfaces.</para> </partintro>

<xi:include href="xml/SomeDBusService.xml"/> <xi:include href="xml/SomeOtherService.xml"/> </chapter>

The generated XML files must be included in the `content_files` variable in your gtk-doc Makefile.am, otherwise the build will fail. (This is to fix situations where the `builddir` does not equal the `srcdir`.)

# Mantener la documentación actualizada

gtk-doc comes with support for checking the documentation with some basic tests. These check that all version indexes are included in the main *-docs.xml file and that all symbols are documented, among other things.

These tests should always be enabled, by adding the following to your gtk-doc Makefile.am:

TESTS = $(GTKDOC_CHECK)

Se ejecutarán como parte de make check.