<?xml version="1.0" encoding="utf-8" standalone="no"?>
<?xml-stylesheet type="text/xml" href="params.xsl"?>
<!-- vim: set ai tw=80 ts=3 sw=3: -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "
              http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY FDL SYSTEM "fdl-appendix.xml">
<!ENTITY FDLlink "<link linkend='fdl'>included</link>">
]>
<!-- =============Document Header ============================= -->
<book id="index" lang="gtk-doc-manual-es">
  <bookinfo>
    <title>Manual de GTK-Doc</title>
    <edition>1.24.1</edition>
    <abstract role="description"><para>Manual del usuario para desarrolladores con instrucciones del uso de GTK-Doc.</para></abstract>
    <authorgroup>
      <author><firstname>Chris</firstname> <surname>Lyttle</surname> <affiliation> <address> <email>chris@wilddev.net</email> </address> </affiliation></author>
      <author><firstname>Dan</firstname> <surname>Mueth</surname> <affiliation> <address> <email>d-mueth@uchicago.edu</email> </address> </affiliation></author>
      <author><firstname>Stefan</firstname> <surname>Sauer (Kost)</surname> <affiliation> <address> <email>ensonic@users.sf.net</email> </address> </affiliation></author>
    </authorgroup>
    <publisher role="maintainer"><publishername>Proyecto GTK-Doc</publishername> <address><email>gtk-doc-list@gnome.org</email></address></publisher>
    <copyright><year>2000, 2005</year> <holder>Dan Mueth and Chris Lyttle</holder></copyright>
    <copyright><year>2007-2019</year> <holder>Stefan Sauer (Kost)</holder></copyright>

    <!-- translators: uncomment this:
    <copyright>
      <year>2000</year>
      <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
    </copyright>
    -->

    <legalnotice>
      <para>Se concede autorización para copiar, distribuir o modificar este documento según los términos de la <citetitle>GNU Free Documentation License</citetitle>, Versión 1.1, o cualquier otra versión posterior publicada por Free Software Foundation sin secciones invariables, textos de portada ni textos de contraportada. Se <link linkend="fdl">incluye</link> una copia de la licencia.</para>
      <para>Muchos de los nombres usados por compañías para distinguir sus productos y servicios se mencionan como marcas comerciales. Donde aparezcan dichos nombres en cualquier documentación GNOME, y para que los miembros del proyecto de documentación las reconozcan dichas marcas comerciales, dichos nombres se imprimen en mayúsculas o iniciales mayúsculas.</para>
    </legalnotice>

    <revhistory>
      <revision>
         <revnumber>1.33.0</revnumber>
         <date>1 Oct 2020</date>
         <authorinitials>mc</authorinitials>
         <revremark>gtk4 version</revremark>
      </revision>
      <revision><revnumber>1.32.1</revnumber> <date>15 de agosto de 2019</date> <authorinitials>ss</authorinitials> <revremark>desarrollo</revremark></revision>
      <revision><revnumber>1.32</revnumber> <date>15 de agosto de 2019</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores</revremark></revision>
      <revision><revnumber>1.31</revnumber> <date>5 de agosto de 2019</date> <authorinitials>ss</authorinitials> <revremark>cobertura para más pruebas</revremark></revision>
      <revision><revnumber>1.30</revnumber> <date>8 de mayo de 2019</date> <authorinitials>ss</authorinitials> <revremark>cobertura para más pruebas</revremark></revision>
      <revision><revnumber>1.29</revnumber> <date>28 de agosto de 2018</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores</revremark></revision>
      <revision><revnumber>1.28</revnumber> <date>24 de marzo de 2018</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores</revremark></revision>
      <revision><revnumber>1.27</revnumber> <date>07 de diciembre de 2017</date> <authorinitials>ss</authorinitials> <revremark>ajustes para la migración a python</revremark></revision>
      <revision><revnumber>1.26</revnumber> <date>11 de agosto de 2017</date> <authorinitials>ss</authorinitials> <revremark>portar todas las herramientas de perl/bash a python</revremark></revision>
      <revision><revnumber>1.25</revnumber> <date>21 de marzo de 2016</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores, limpieza</revremark></revision>
      <revision><revnumber>1.24</revnumber> <date>29 de mayo de 2015</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores</revremark></revision>
      <revision><revnumber>1.23</revnumber> <date>17 de mayo de 2015</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores</revremark></revision>
      <revision><revnumber>1.22</revnumber> <date>7 de mayo de 2015</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores, eliminadas funcionalidades obsoletas</revremark></revision>
      <revision><revnumber>1.21</revnumber> <date>17 de julio de 2014</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores, eliminadas funcionalidades obsoletas</revremark></revision>
      <revision><revnumber>1.20</revnumber> <date>16 de febrero de 2014</date> <authorinitials>ss</authorinitials> <revremark>errores corregidos, soporte de marcado, mejoras en los estilos</revremark></revision>
      <revision><revnumber>1.19</revnumber> <date>05 de junio de 2013</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores</revremark></revision>
      <revision><revnumber>1.18</revnumber> <date>14 de septiembre de 2011</date> <authorinitials>ss</authorinitials> <revremark>correcciones de errores, mejoras en la velocidad y soporte de marcado</revremark></revision>
      <revision><revnumber>1.17</revnumber> <date>26 de febrero de 2011</date> <authorinitials>sk</authorinitials> <revremark>actualización urgente de corrección de error</revremark></revision>
      <revision><revnumber>1.16</revnumber> <date>14 de enero de 2011</date> <authorinitials>sk</authorinitials> <revremark>correcciones de errores y mejoras en la distribución</revremark></revision>
      <revision><revnumber>1.15</revnumber> <date>21 de mayo de 2010</date> <authorinitials>sk</authorinitials> <revremark>correcciones de errores y regresiones</revremark></revision>
      <revision><revnumber>1.14</revnumber> <date>28 de marzo de 2010</date> <authorinitials>sk</authorinitials> <revremark>correcciones de errores y mejoras en el rendimiento</revremark></revision>
      <revision><revnumber>1.13</revnumber> <date>18 de diciembre de 2009</date> <authorinitials>sk</authorinitials> <revremark>actualización del tarball roto</revremark></revision>
      <revision><revnumber>1.12</revnumber> <date>18 de diciembre de 2009</date> <authorinitials>sk</authorinitials> <revremark>correcciones de errores y nuevas características</revremark></revision>
      <revision><revnumber>1.11</revnumber> <date>16 de noviembre de 2008</date> <authorinitials>mal</authorinitials> <revremark>Migración a GNOME doc-utils</revremark></revision>
    </revhistory>

  
    <othercredit class="translator">
      <personname>
        <firstname>Daniel Mustieles</firstname>
      </personname>
      <email>daniel.mustieles@gmail.com</email>
    </othercredit>
    <copyright>
      
        <year>2009 - 2020</year>
      
      <holder>Daniel Mustieles</holder>
    </copyright>
  
    <othercredit class="translator">
      <personname>
        <firstname>Jorge González</firstname>
      </personname>
      <email>jorgegonz@svn.gnome.org</email>
    </othercredit>
    <copyright>
      
        <year>2009 - 2011</year>
      
      <holder>Jorge González</holder>
    </copyright>
  
    <othercredit class="translator">
      <personname>
        <firstname>Francisco Javier F. Serrador</firstname>
      </personname>
      <email>serrrador@svn.gnome.org</email>
    </othercredit>
    <copyright>
      
        <year>2009</year>
      
        <year>2010</year>
      
      <holder>Francisco Javier F. Serrador</holder>
    </copyright>
  </bookinfo>

  <!-- ======== Chapter 1: Introduction ======================== -->

  <chapter id="introduction">
    <title>Introducción</title>

    <para>Este capítulo introduce GTK-Doc y proporciona una visión general de lo que es y cómo usarlo.</para>

    <sect1 id="whatisgtkdoc">
      <title>¿Qué es GTK-Doc?</title>

      <para>GTK-Doc se usa para documentar código C. Generalmente se usa para documentar la API pública de bibliotecas, tales como las bibliotecas GTK+ y de GNOME. Pero también se puede usar para documentar código de aplicaciones.</para>
    </sect1>

    <sect1 id="howdoesgtkdocwork">
      <title>¿Cómo funciona GTK-Doc?</title>

      <para>GTK-Doc funciona usando documentación de las funciones ubicadas dentro de los archivos de fuentes en bloques de comentarios especialmente formateados, o documentación añadida a los archivos de plantillas que GTK-Doc usa (aunque debe notar que GTK-Doc sólo documentará las funciones declaradas en los archivos de cabecera; no produce salida para funciones estáticas).</para>

      <para>GTK-Doc consiste en un número de scripts en python, cada uno realiza un paso diferente en el proceso.</para>

      <para>Existen 5 pasos importantes en el proceso:</para>

      <orderedlist>

        <listitem>
          <para><guilabel>Escribir la documentación.</guilabel> El autor rellena los archivos de fuentes con la documentación para cada función, macro, unión, etc.</para>
        </listitem>

        <listitem>
          <para><guilabel>Obtener información acerca del código</guilabel>. <application>gtkdoc-scan</application> analiza los archivos de cabecera del código buscando declaraciones de funciones, macros, enumeraciones, estructuras y uniones. Crea el archivo <filename>&lt;module&gt;-decl-list.txt</filename> que contiene una lista de las declaraciones, ubicándolas en secciones de acuerdo con el archivo de cabecera en el que están. Durante la primera ejecución este archivo se copia en <filename>&lt;module&gt;-sections.txt</filename>. El autor puede reordenar las secciones y el orden de las declaraciones en ellas, para producir la salida que quiere. El segundo archivo que genera es <filename>&lt;module&gt;-decl.txt</filename>. Este archivo contiene las declaraciones completas que encontró el análisis. Si por alguna razón quisiese que algunos símbolos apareciesen en los documentos, donde el análisis no puede encontrar la declaración completa o la declaración debería aparecer de forma diferente, puede introducir entradas de forma similar a las que hay en <filename>&lt;module&gt;-decl.txt</filename> dentro de <filename>&lt;module&gt;-overrides.txt</filename>.</para>
         <para><application>gtkdoc-scangobj</application> también se puede usar para consultar dinámicamente una biblioteca sobre cualquiera de las subclases GObject que exporta. Guarda información sobre la posición de cada objeto en la jerarquía de clases y sobre cualquier propiedad de GObject y las señales que proporciona.</para>
         <para><application>gtkdoc-scanobj</application> no se debería usar más. Se necesitó en el pasado, cuando GObject todavía era GtkObject dentro de GTK+.</para>
        </listitem>

        <listitem>
          <para><guilabel>Generar el XML y el HTML/PDF.</guilabel><application>gtkdoc-mkdb</application> convierte los archivos de plantilla en archivos SGML o XML en la subcarpeta <filename class="directory">xml/</filename>. Si el código fuente contiene documentación de funciones, usando los bloques especiales de comentarios, entonces se mezclarán aquí. Si no se usan archivos tmpl sólo obtiene los documentos de los fuentes y los datos obtenidos en introspección.</para>
          <para><application>gtkdoc-mkhtml</application> convierte los archivos XML en archivos HTML en la subcarpeta <filename class="directory">html/</filename>. De la misma forma <application>gtkdoc-mkpdf</application> convierte los archivos XML en un documento PDF llamado <filename>&lt;paquete&gt;.pdf</filename>.</para>
          <para>Los archivos en las carpetas <filename class="directory">xml/</filename> y <filename class="directory">html/</filename> y siempre se sobrescriben. Nunca se deben editar directamente.</para>
        </listitem>

        <listitem>
          <para><guilabel>Arreglar referencias cruzadas entre documentos.</guilabel> Después de instalar los archivos HTML se puede ejecutar <application>gtkdoc-fixxref</application> para arreglar cualquier referencia cruzada entre documentos separados. Por ejemplo, la documentación GTK+ contiene muchas referencias cruzadas a tipos documentados en el manual de GLib. Al crear los archivadores «tarball» para su distribución, <application>gtkdoc-rebase</application> convierte todos los enlaces externos en enlaces web. Al instalar la documentación distribuida (pregenerada) la misma aplicación intentará convertir de nuevo los enlaces, esta vez a enlaces locales (donde esa documentación está instalada).</para>
        </listitem>
      </orderedlist>

    </sect1>

    <sect1 id="gettinggtkdoc">
      <title>Obtener GTK-Doc</title>

      <sect2 id="requirements">
        <title>Requerimientos</title>
        <para><guilabel>python 2/3</guilabel> - los scripts principales están escritos en python.</para>
        <para><guilabel>xsltproc</guilabel>: el procesador xslt de libxslt <ulink url="http://xmlsoft.org/XSLT/" type="http">xmlsoft.org/XSLT/</ulink></para>
        <para><guilabel>docbook-xsl</guilabel>: las hojas de estilo XLS de docbook <ulink url="http://sourceforge.net/projects/docbook/files/docbook-xsl/" type="http">sourceforge.net/projects/docbook/files/docbook-xsl</ulink></para>
        <para>Una de <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> o <guilabel>vim</guilabel>: opcional, usada para el resaltado de sintaxis de los ejemplos.</para>
      </sect2>
    </sect1>

    <sect1 id="aboutgtkdoc">
      <title>Acerca de GTK-Doc</title>

      <para>Históricamente, GTK-Doc se utilizaba para generar archivos de plantilla a partir del código fuente. Los desarrolladores pueden usar estos archivos de plantilla para introducir la documentación de la API. Este enfoque era bastante incómodo porque requería mantener los archivos generados bajo control de versiones. Desde GTK-Doc 1.9 se hizo posible colocar toda la información de la API en los comentarios de origen, lo que dejó obsoleto el soporte de la plantilla. En la versión 1.26 se ha eliminado el soporte de plantillas.</para>

      <para>(ARRÉGLAME)</para>

      <para>(autores, páginas web, listas de correo, licencias, planes futuros, comparación con otros sistemas similares.)</para>

    </sect1>

    <sect1 id="aboutthismanual">
      <title>Acerca de este manual</title>

      <para>(ARRÉGLAME)</para>

      <para>(a quién está dirigido, dónde puede obtenerse, licencia)</para>

    </sect1>

  </chapter>

  <chapter id="settingup">
    <title>Configuración del proyecto</title>

    <para>Este capítulo describe los pasos para integrar GTK-Doc en su proyecto. La integración de GTK-Doc incluye:</para>

    <itemizedlist>
      <listitem>
        <para>Preparación de la estructura de carpetas y crear los archivos de configuración necesarios para su documentación GTK-Doc (consulte <link linkend="settingup_docfiles"> Configurar el esqueleto de la documentación</link>).</para>
      </listitem>
      <listitem>
        <para>Ajustar el sistema de construcción para construir su documentación usando las herramientas de GTK-Doc. Hay varios sistemas de construcción soportados, en este manual se describe cómo integrar GTK-Doc con <link linkend="settingup_autotools">Autotools</link>, <link linkend="settingup_cmake">CMake</link>, y <link linkend="settingup_plain_makefiles">archivos Makefile</link>.</para>
      </listitem>
      <listitem>
        <para>Añadir archivos específicos de GTK-Doc al control de versiones y decidir qué archivos ignorar (consulte <link linkend="settingup_vcs">Integración con sistemas de control de versiones</link>).</para>
      </listitem>
    </itemizedlist>

    <para>La siguiente sección asume que se trabaja con un proyecto llamado <code>meep</code>. Este proyecto contiene dos paquetes (o módulos), una biblioteca llamada <code>libmeep</code> y una aplicación de usuario final llamada <code>meeper</code>.</para>

    <sect1 id="settingup_docfiles">
      <title>Configurar el esquema de la documentación</title>

      <para>Un convenio común es colocar la documentación en una carpeta llamada <code>docs</code> dentro de su carpeta de proyecto de nivel superior. Normalmente se distingue entre <emphasis>documentación de referencia</emphasis> destinada a desarrolladores y un <emphasis>manual de usuario</emphasis> destinado a usuarios finales. Nuevamente, el convenio es tener carpetas separadas para ambos. Por lo general, colocamos la documentación de referencia en una carpeta llamada <code>reference</code> y el manual del usuario final en una carpeta llamada <code>help</code> como. De acuerdo con el convenio anterior, la documentación de nuestro paquete <code>libmeep</code> se colocaría en: <code>docs/reference/libmeep</code>. Para paquetes con una sola biblioteca o aplicación, la documentación también se puede colocar directamente en <code>docs/reference </code>. No es obligatorio usar el convenio anterior, pero si elige usar una estructura de carpetas diferente, debe ajustar la configuración del sistema de compilación para que coincida con la estructura de su carpeta.</para>

      <para>En las siguientes secciones se asumirá que la estructura de carpetas de nuestro proyecto <emphasis>meep</emphasis> usa los convenios anteriores. <example>
          <title>Ejemplo de estructura de carpetas para el proyecto <emphasis>meep</emphasis></title>
          <programlisting>
meep/
  docs/
    reference/  # reference documentation
      libmeep/
      meeper/
    help/       # optional: user manual
      meeper/
  src/
    libmeep/
    meeper/
</programlisting>
        </example></para>
    </sect1>

    <sect1 id="settingup_autotools">
      <title>Integración con Autotools</title>
      <para>La integración de GTK-Doc en un sistema de construcción basado en autotools requiere los siguientes pasos:</para>
      <itemizedlist>
        <listitem>
          <para>Asegúrese de que <application>gtkdocize</application> se ejecuta antes del script <filename>configure</filename>. Si existe un script <filename>autogen.sh</filename> ajústelo para que compruebe que existe GTK-Doc y añada una llamada a <application>gtkdocize</application>.</para>

          <para>El propósito principal de <application>gtkdocize</application> es hacer que el Makefile <filename>gtk-doc.make</filename> y el archivo de definición de macros <filename>gtk-doc.m4</filename> estén disponibles para el sistema de construcción, bien copiándolos o enlazándolos en el proyecto.</para>
        </listitem>
        <listitem>
          <para>Añada las macros de <application>autoconf</application> necesarias a <filename>configure.ac</filename> para activar GTK-Doc en su sistema de construcción y permitir la configuración de GTK-Doc generada en el script <filename>configure</filename>.</para>
          <para>Entre otras la que registra la opción <code>--enable-gtk-doc</code> en el script <filename>configure</filename>.</para>
        </listitem>
        <listitem>
          <para>Cree un script <application>automake</application> para cada aplicación o biblioteca de su proyecto. En el ejemplo usado en esta documentación este paso se aplica a <code>meeper</code> y a <code>libmeep</code>.</para>
        </listitem>
      </itemizedlist>

      <para>En las siguientes secciones, se realizan los pasos anteriores en orden inverso. Comienza con los scripts <application>automake</application> y avanza hasta <filename>configure.ac</filename> y <filename> autogen.sh </filename>. Luego se muestra cómo activar Gtk-Doc en el sistema de compilación y cómo compilar la documentación.</para>

      <sect2 id="settingup_automake">
        <title>Integración con automake</title>

        <para>Primero copie el archivo <filename>Makefile.am</filename> de la subcarpeta <filename class="directory">examples</filename> de <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am"> gtkdoc-sources</ulink> a la carpeta de documentación de la API de su proyecto (<filename class="directory">./docs/reference/&lt;paquete&gt;</filename>). Debería haber una copia local disponible en <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>. Si tiene varios paquetes de documentación, repítalo para cada uno de ellos.</para>

        <note>
          <simpara>No olvide añadir cada <filename>Makefile.am</filename> a la macro <function>AC_CONFIG_FILES</function> en <filename>configure.ac</filename>. Para <filename>docs/reference/libmeep/Makefile.am</filename> deberá añadir la entrada <filename>docs/reference/libmeep/Makefile</filename> a <function>AC_CONFIG_FILES</function>.</simpara>
        </note>

        <example>
          <title>Ejemplo de estructura de carpetas con <filename>Makefiles.am</filename></title>
          <programlisting>
meep/
  docs/
    reference/  # reference documentation
      libmeep/
        Makefile.am
      meeper/
        Makefile.am
    help/       # optional: user manual
      meeper/
  src/
    libmeep/
    meeper/
</programlisting>
        </example>

        <para>A continuación, debe personalizar los Makefiles copiados y proporcionar valores para los distintos parámetros en cada <filename>Makefile.am</filename>. Todas las configuraciones tienen un comentario sobre ellas que describe su propósito y cómo personalizar la configuración. La mayoría de las configuraciones se utilizan para proporcionar indicadores adicionales a las herramientas respectivas a las que se aplican. Cada herramienta tiene una variable de la forma <option> &lt;TOOLNAME&gt;_OPTIONS </option> (por ejemplo, la herramienta <application>gtkdoc-mkhtml</application> tiene una opción llamada <code>MKHTML_OPTIONS</code>). Todas las herramientas admiten <option>--help</option> para enumerar las opciones admitidas.</para>

        <para>La siguiente lista explica las opciones más relevantes. Consulte el ejemplo <filename>Makefile.am</filename> para obtener opciones adicionales. <itemizedlist>
            <listitem>
              <para><option>DOC_MODULE</option> se usa para proporcionar el nombre del paquete que se está documentando (ej. <code>meeper</code>, o <code>libmeep</code>).</para>
            </listitem>
            <listitem>
              <para><option>DOC_SOURCE_DIR</option> se utiliza para especificar la ubicación de la carpeta de origen en el que GTK-Doc busca la documentación de su API. Esto generalmente será <code>DOC_SOURCE_DIR=$(top_srcdir)/src</code> o una subcarpeta de ese carpeta.</para>
            </listitem>

            <listitem>
              <para><option>HFILE_GLOB</option> y <option>CFILE_GLOB</option> se usan para dependencias. Cada opción toma un archivo glob (por ejemplo, <code>HFILE_GLOB=$(top_srcdir)/src/*.C</code>). La documentación se reconstruirá si alguno de los archivos coincidentes cambia.</para>
            </listitem>

            <listitem>
              <para><option>EXTRA_HFILES</option> permite especificar archivos de cabeceras adicionales que incluir al analizar la documentación de la API y que no están en <code>DOC_SOURCE_DIR</code> (ej. <code> EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).</para>
            </listitem>

            <listitem>
              <para><option>IGNORE_HFILES</option> permite especificar archivos de cabeceras o carpetas que ignorar al analizar la documentación de la API. Use el nombre base del archivo o la carpta (ej. <code> IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).</para>
            </listitem>

            <listitem>
              <para><option>HTML_IMAGES</option> permite especificar archivos de imágenes que se copiarán en la carpeta <filename>html/</filename> de la documentación generada. Si su documentación de la API incluye imágenes, deben agregarse a esta opción (por ejemplo, <code>HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).</para>
            </listitem>

            <listitem>
              <para><option>content_files</option> permite especificar archivos adicionales que están incluidos en <code>$(DOC_MAIN_SGML_FILE)</code> (por ejemplo, <code>content_files=running.xml building.xml changes-2.0.xml</code>)</para>
            </listitem>

            <listitem>
              <para><option>expand_content_files</option> permite especificar archivos donde <emphasis>gtk-doc abbreviations</emphasis> como <code>#GtkWidget</code> se expanden (por ejemplo, <code>expand_content_files=running.xml</code>).</para>
            </listitem>
          </itemizedlist></para>

      </sect2>

      <sect2 id="settingup_autoconf">
        <title>Integración con autoconf</title>

        <para>La integración con <application>autoconf</application> es muy simple e incluye un paso requerido y un paso opcional adicional (pero recomendado). El primer paso es agregar la macro <function>GTK_DOC_CHECK</function> a su script <filename>configure.ac</filename>. Esto registra varias opciones de configuración para habilitar GTK-Doc y le permite establecer argumentos predeterminados para <application>gtkdocize</application>.</para>

        <warning>
          <simpara>Asegúrese de que la macro <code>GTK_DOC_CHECK</code> no esté sangrada. La macro debe comenzar al principio de la línea y no debe comenzar con espacios en blanco.</simpara>
        </warning>

        <para>El segundo paso es agregar el <code>AC_CONFIG_MACRO_DIR (m4)</code> a su <filename>configure.ac</filename>. Esto no es obligatorio, pero ayuda a <application>gtkdocize</application> a copiar automáticamente la definición de macro (Ej., <filename>gtk-doc.m4</filename>) que contiene la macro <function>GTK_DOC_CHECK</function> en la carpeta de macros de su proyecto. Sin esto, es posible que no se encuentre la macro GTK_DOC_CHECK y necesitaría decirle explícitamente a la herramienta <application>aclocal</application> dónde encontrar el archivo de definición de macro.</para>

        <para>
          <example><title>Integración mínima con autoconf</title>
            <programlisting>
# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
# optional: register gtk-doc in configure
GTK_DOC_CHECK([1.28])
</programlisting>
          </example>
        </para>

        <para>El ejemplo anterior funciona, pero requerirá que todos los desarrolladores tengan instalado gtk-doc. Una mejor manera es hacer que la creación de la documentación sea opcional como se muestra en el siguiente ejemplo: <example>
            <title>Integración con dependencias opcionales de gtk-doc</title>
            <programlisting>
m4_ifdef([GTK_DOC_CHECK], [
# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
# optional: register gtk-doc in configure
GTK_DOC_CHECK([1.28])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])
</programlisting>
          </example></para>

        <para>El primer argumento se utiliza para verificar la versión de Gtk-Doc en el momento de la configuración. El segundo argumento opcional es usado por <application>gtkdocize</application>. La macro <symbol>GTK_DOC_CHECK</symbol> también agrega varios modificadores de configuración:</para>

        <orderedlist>
          <listitem><para>--with-html-dir=RUTA: ruta a los documentos instalados</para></listitem>
          <listitem><para>--enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=no]</para></listitem>
          <listitem><para>--enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=sí]</para></listitem>
          <listitem><para>--enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=no]</para></listitem>
        </orderedlist>

        <important>
          <para>GTK-Doc está desactivado de forma predeterminada. Recuerde pasar la opción <option>«--enable-gtk-doc»</option> en la siguiente ejecución de <filename>configure</filename>. De otra forma, la documentación pregenerada se instala (lo que tiene sentido para usuarios, pero no para desarrolladores).</para>
        </important>

        <para>Después de hacer los cambios en el <filename>configure.ac</filename> actualice el archivo <filename>configure</filename>. Esto se puede hacer volviendo a ejecutar <code>autogen.sh</code>.</para>
      </sect2>

      <sect2 id="settingup_autogen">
        <title>Integración con autogen</title>

        <para>La mayoría de los proyectos tendrán un script <filename>autogen.sh</filename> para configurar la infraestructura de compilación después de que el proyecto se haya extraído de un sistema de control de versiones (como git o svn). GTK-Doc viene con un script llamado <application>gtkdocize</application> que puede usarse para copiar los archivos necesarios que necesita Gtk-Doc en la carpeta fuente.</para>

        <para>Se debe ejecutar antes de autoreconf, autoheader, automake o autoconf.</para>

        <para>
          <example><title>Ejecutar gtkdocize desde autogen.sh</title>
            <programlisting>
gtkdocize || exit 1
</programlisting>
          </example>
        </para>

        <para>
          <example>
            <title>Condicionalmente, ejecutar gtkdocize desde autogen.sh</title>
            <programlisting>
GTKDOCIZE=$(which gtkdocize 2&gt;/dev/null)
if test $? -ne 0; then
  echo "No gtk-doc support found. You can't build the docs."
else
  $GTKDOCIZE || exit 1
fi
</programlisting>
          </example>
        </para>

        <para>Al ejecutar <filename>gtkdocize</filename> copia <filename>gtk-doc.make</filename> a la raíz de su proyecto (o cualquier carpeta especificada por la opción <option>--docdir</option>).</para>

        <para><application>gtkdocize</application> comprueba su script <filename> configure.ac </filename> para la macro <function> GTK_DOC_CHECK</function>. La macro <function> GTK_DOC_CHECK </function> se puede usar para pasar argumentos adicionales al script <application>gtkdocize</application>. el segundo parámetro en la macro <function>GTK_DOC_CHECK</function>.</para>

        <para>Alternativamente, también se pueden pasar argumentos adicionales a <application>gtkdocize</application> a través de la variable de entorno <function>GTKDOCIZE_FLAGS</function>, o especificándolos directamente a <application>gtkdocize</application> en <filename>autogen.sh</filename>.</para>

      </sect2>

      <sect2 id="settingup_firstrun">
        <title>Ejecutar GTH-Doc desde el sistema de construcción</title>

        <para>Después de los pasos anteriores es hora de ejecutar el constructor. Primero se debe volver a ejecutar <filename>autogen.sh</filename>. Si este script ejecuta configure automáticamente, entonces debe pasar la opción <option>--enable-gtk-doc</option>. De otra forma, ejecute posteriormente <filename>configure</filename> con esta opción.</para>
        <para>El primer make genera diversas líneas adicionales en las carpetas de documentación. Las importantes son: <filename>&lt;paquete&gt;.types</filename>, <filename>&lt;paquete&gt;-docs.xml</filename> (.sgml en el pasado), <filename>&lt;paquete&gt;-sections.txt</filename>.</para>
        <para>
          <example><title>Ejecutar la construcción de la documentación</title>
            <programlisting>
./autogen.sh --enable-gtk-doc
make
</programlisting>
          </example>
        </para>

        <para>Ahora puede apuntar su navegador a <filename>docs/reference/&lt;package&gt;/index.html</filename>. Con esta configuración inicial, solo verá un documento muy simple. El siguiente capítulo le enseñará cómo agregar documentación API a su código a través de bloques de comentarios especiales. Posteriormente, el Capítulo presenta <link linkend="metafiles">archivos adicionales</link> y muestra cómo editar la plantilla maestra <link linkend="metafiles_master"/> para agregar capítulos y secciones adicionales a sus archivos de documentación.</para>

      </sect2>

    </sect1>

    <sect1 id="settingup_cmake">
      <title>Integración con sistemas de construcción CMake</title>

      <para>Ahroa, GTK-Doc proporciona un módulo <filename>GtkDocConfig.cmake</filename> (y el correspondiente módulo <filename>GtkDocConfigVersion.cmake</filename>). Esto proporciona un comando <literal>gtk_doc_add_module</literal> que puede configurar en su archivo <filename>CMakeLists.txt</filename>.</para>

      <para>El siguiente ejemplo muestra cómo usar este comando. <example><title>Ejeplo de uso de GTK-Doc desde CMake</title>
          <programlisting>
find_package(GtkDoc 1.25 REQUIRED)

# Create the doc-libmeep target.
gtk_doc_add_module(
   libmeep ${CMAKE_SOURCE_DIR}/libmeep
      XML meep-docs.xml
      LIBRARIES libmeep
)

# Build doc-libmeep as part of the default target. Without this, you would
# have to explicitly run something like `make doc-libmeep` to build the docs.
add_custom_target(documentation ALL DEPENDS doc-libmeep)

# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
# to set the CMAKE_INSTALL_DOCDIR variable correctly).
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
        DESTINATION ${CMAKE_INSTALL_DOCDIR})
</programlisting>
        </example></para>
    </sect1>

    <sect1 id="settingup_plain_makefiles">
      <title>Integración con makefiles u otros sistemas de construcción</title>

      <para>En el caso de que no quiera usar automake y por ello <filename>gtk-doc.mak</filename> deberá llamar a las herramientas gtkdoc en el orden correcto en makefiles propios (o en otras herramientas de construcción).</para>

      <para>
        <example><title>Pasos de construcción de la documentación</title>
          <programlisting>
DOC_MODULE=meep
// sources have changed
gtkdoc-scan --module=$(DOC_MODULE) &lt;source-dir&gt;
gtkdoc-scangobj --module=$(DOC_MODULE)
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=&lt;source-dir&gt;
// xml files have changed
mkdir html
cd html &amp;&amp; gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
</programlisting>
        </example>
      </para>

      <para>Deberá mirar en el archivo <filename>Makefile.am</filename> y <filename>gtk-doc.mak</filename> para elegir las opciones adicionales necesarias.</para>
    </sect1>

    <sect1 id="settingup_vcs">
      <title>Integración con los sistemas de control de versiones</title>

      <para>Como regla principal, son los archivos que edita los que deberían estar bajo el control de versiones. Para proyectos típicos son los archivos: <filename>&lt;paquete&gt;.types</filename>, <filename>&lt;paquete&gt;-docs.xml</filename> (anteriormente .sgml), <filename>&lt;paquete&gt;-sections.txt</filename>, <filename>Makefile.am</filename>.</para>
      <para>Los archivos de las carpetas <filename>xml/</filename> y <filename>html/</filename> No deberían estar bajo control de versiones. Tampoco ninguno de los archivos <filename>.stamp</filename>.</para>
    </sect1>

  </chapter>

  <chapter id="documenting">
    <title>Documentar el código</title>

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

    <para>El escáner GTK-Doc puede manejar bien la mayoría de los encabezados C. En el caso de recibir advertencias del escáner que se vean como un caso especial, uno puede indicarle a GTK-Doc que las omita. <example><title>Bloque de comentario de GTK-Doc</title>
        <programlisting>
#ifndef __GTK_DOC_IGNORE__
/* unparseable code here */
#endif
</programlisting>
      </example></para>

    <note>
      <title>Limitaciones</title>
      <para>Tenga en cuenta que GTK-Doc soporta <code>#ifndef(__GTK_DOC_IGNORE__)</code> pero <code>#if !defined(__GTK_DOC_IGNORE__)</code> u otras combinaciones.</para>
    </note>

    <!--  -->

    <sect1 id="documenting_syntax">
      <title>Comentarios de la documentación</title>

      <para>Un comentario de varias líneas que comienza con un «*» adicional marca un bloque de documentación que GTK-Doc tools procesarán. <example><title>Bloque de comentario de GTK-Doc</title>
          <programlisting>
/**
 * identifier:
 * documentation ...
 */
</programlisting>
        </example></para>

      <para>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)</para>

      <para>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).</para>

      <tip>
        <para>Al documentar código, describa dos aspectos: <itemizedlist>
             <listitem>
               <para>Qué es: el nombre de la clase o la función puede confundir a veces a personas que provengan de otros entornos.</para>
             </listitem>
             <listitem>
               <para>Qué hace: indique los usos comunes, en relación con las otras API.</para>
             </listitem>
           </itemizedlist></para>
      </tip>

      <para>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. <itemizedlist>
          <listitem>
            <para>Use función() para referirse a funciones o macros que toman argumentos.</para>
          </listitem>
          <listitem>
            <para>Use @parámetro para referirse a parámetros. Úselo también al referirse a parámetros de otras funciones, relacionados al que se describe.</para>
          </listitem>
          <listitem>
            <para>Use %constant para referirse a una constante, ej: %G_TRAVERSE_LEAFS.</para>
          </listitem>
          <listitem>
            <para>Use #símbolo para referirse a otro tipo de símbolos, como por ejemplo estructuras, enumeraciones y macros que no toman argumentos.</para>
          </listitem>
          <listitem>
            <para>Use #Object::signal para referirse a una señal de GObject.</para>
          </listitem>
          <listitem>
            <para>Use #Object:property para referirse a una propiedad de GObject.</para>
          </listitem>
          <listitem>
            <para>Use #Struct.field para referirse a un campo dentro de una estructura y #GObjectClass.foo_bar() para referirse a un vmethod.</para>
          </listitem>
        </itemizedlist></para>

      <tip>
        <para>Si necesita usar los caracteres especiales «&lt;», «&gt;», «()», «@», «%», o «#» en su documentación sin que GTK-Doc los cambie, puede usar las entidades XML «&amp;lt;», «&amp;gt;», «amp;lpar;», «amp;rpar;», «amp;commat;» «&amp;percnt;» y «&amp;num;» respectivamente o escaparlas con una contrabarra doble «\».</para>
      </tip>

      <para>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 <ulink url="http://daringfireball.net/projects/markdown/">Marcado</ulink>. 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.</para>

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

      <para>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 <option>--xml-mode</option> o <option>--sgml-mode</option> en la variable <symbol>MKDB_OPTIONS</symbol> dentro de <filename>Makefile.am</filename>.</para>

      <para>
        <example><title>Bloque de comentario de GTK-Doc usando marcado</title>
          <programlisting>
/**
 * 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:
 * |[&lt;!-- language="C" --&gt;
 * GtkWidget *label = gtk_label_new ("Gorgeous!");
 * ]|
 */
</programlisting>
        </example>
      </para>

      <para>
        More examples of what markdown tags are supported can be found in the
        <ulink url="https://wiki.gnome.org/Projects/GTK/DocumentationSyntax/Markdown">GTK Documentation Markdown Syntax Reference</ulink>.
      </para>

      <tip>
        <para>Como ya se mencionó anteriormente, GTK-Doc es para documentar API públicas. Por lo tanto, no se puede escribir documentación para símbolos estáticos. Sin embargo, también es bueno comentar esos símbolos. Esto ayuda a otros desarrolladores a comprender su código. Por lo tanto, recomendamos comentarlos usando comentarios normales (sin el segundo «*» en la primera línea). Si luego la función necesita hacerse pública, todo lo que se debe hacer es agregar otro «*» en el bloque de comentarios e insertar el nombre del símbolo en el lugar correcto dentro del archivo de secciones.</para>
      </tip>
    </sect1>

    <sect1 id="documenting_sections">
      <title>Documentar secciones</title>

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

      <para>
        <example><title>Bloque de comentarios en una sección</title>
          <programlisting>
/**
 * 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 ...
 */
</programlisting>
        </example>
      </para>

      <variablelist>
        <varlistentry>
          <term>SECCIÓN &lt;nombre&gt;</term>
          <listitem>
            <para>El nombre enlaza la sección de la documentación con la parte respectiva en el archivo <filename>&lt;paquete&gt;-sections.txt</filename>. El nombre aquí proporcionado debería coincidir con la etiqueta &lt;ARCHIVO&gt; en el archivo <filename>&lt;paquete&gt;-sections.txt</filename>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@short_description</term>
          <listitem>
            <para>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.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@title</term>
          <listitem>
            <para>De forma predeterminada el título de la sección es &lt;name&gt; de la declaración SECTION. Se puede sobrescribir con el campo @title.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@section_id</term>
          <listitem>
            <para>Sobrescribe el uso del título como el identificador de sección. &lt;title&gt; se usa en GObjects como el identificador de sección (section_id) y para otra sección es &lt;MÓDULO&gt;-&lt;title&gt;.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@see_also</term>
          <listitem>
            <para>Una lista de símbolos relacionados con esta sección.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@stability</term>
          <listitem>
            <para>Esta API tiene una descripción informal del nivel de estabilidad. Se recomienda el uso de uno de estos términos: <itemizedlist>
                <listitem>
                  <para>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.</para>
                </listitem>
                <listitem>
                  <para>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.</para>
                </listitem>
                <listitem>
                  <para>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.</para>
                </listitem>
                <listitem>
                  <para>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.</para>
                </listitem>
              </itemizedlist></para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@include</term>
          <listitem>
            <para>Los archivos <literal>#include</literal> para mostrar en la sección del resumen (una lista separada por comas), sobrescribiendo el valor global del <link linkend="metafiles_sections">archivo de secciones</link> o de la línea de comandos. Este elemento es opcional.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@image</term>
          <listitem>
            <para>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>
          </listitem>
        </varlistentry>
      </variablelist>

      <tip>
        <para>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.</para>
      </tip>

    </sect1>

    <sect1 id="documenting_symbols">
      <title>Documentar símbolos</title>

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

      <sect2><title>Etiquetas generales</title>

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

        <variablelist><title>Versionado de etiquetas</title>
          <varlistentry><term>Desde:</term>
            <listitem>
              <para>Descripción desde qué versión del código está disponible la API.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>Obsoleto:</term>
            <listitem>
              <para>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.</para>
            </listitem>
          </varlistentry>
        </variablelist>

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

        <para>El nivel de estabilidad predeterminado para todos los elementos de la documentación se puede establecer pasando el argumento <option>--default-stability</option> a <application>gtkdoc-mkdb</application> con uno de los siguientes valores.</para>

        <variablelist><title>Etiquetas de estabilidad</title>
          <varlistentry><term>Estabilidad: estable</term>
            <listitem>
              <para>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.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>Estabilidad: inestable</term>
            <listitem>
              <para>Marcar el elemento como inestable. Esto es para las API públicas que se publican como versión previa antes de estabilizarse.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>Estabilidad: privado</term>
            <listitem>
              <para>Marcar el elemento como privado. Esto es para interfaces que se pueden usar en módulos fuertemente acoplados, pero no en terceras partes aleatorias.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <example><title>Etiquetas generales</title>
          <programlisting>
/**
 * 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)
{
...
</programlisting>
        </example>
      </sect2>

      <sect2><title>Anotaciones</title>

        <para>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 <ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">el wiki</ulink>.</para>

        <example><title>Anotaciones</title>
          <programlisting>
/**
 * 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.
 */
</programlisting>
        </example>
      </sect2>

      <sect2><title>Bloque de comentario de función</title>

        <para>Recuerde: <itemizedlist>
            <listitem>
              <para>El documento, dependiendo de si devuelve objetos, listas, cadenas, etc. debería liberarse/desreferenciarse/etc.</para>
            </listitem>
            <listitem>
              <para>El documento, dependiendo de si sus parámetros pueden ser nulos, y qué sucede si lo son.</para>
            </listitem>
            <listitem>
              <para>Mencionar precondiciones y postcondiciones interesantes donde sea apropiado.</para>
            </listitem>
          </itemizedlist></para>

        <para>GTK-Doc asume que todos los símbolos (macros, funciones) que empiezan por «_» son privados. Se tratan como funciones estáticas.</para>

        <example><title>Bloque de comentario de función</title>
          <programlisting>
/**
 * 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.
 */
</programlisting>
        </example>

        <variablelist><title>Etiquetas de funciones</title>
          <varlistentry><term>Devuelve:</term>
            <listitem>
              <para>Párrafo que describe el resultado devuelto.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>@...:</term>
            <listitem>
              <para>En el caso de que la función tenga argumentos variados debe usar esta etiqueta (@Vargargs: también funciona por razones históricas).</para>
            </listitem>
          </varlistentry>
        </variablelist>

      </sect2>

      <sect2><title>Bloque de comentario de propiedad</title>

        <example><title>Bloque de comentario de propiedad</title>
          <programlisting>
/**
 * SomeWidget:some-property:
 *
 * Here you can document a property.
 */
g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
</programlisting>
        </example>

      </sect2>

      <sect2><title>Bloque de comentario de señal</title>

        <para>Recuerde: <itemizedlist>
            <listitem>
              <para>Documentar cuando la señal se emite e indica si se emite antes o después de otras señales.</para>
            </listitem>
            <listitem>
              <para>Documentar qué aplicación debe gestionar las señales.</para>
            </listitem>
          </itemizedlist></para>

        <example><title>Bloque de comentario de señal</title>
          <programlisting>
/**
 * 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",
                ...
</programlisting>
        </example>

      </sect2>

      <sect2><title>Bloque de comentario de estructura</title>
        <example><title>Bloque de comentario de estructura</title>
          <programlisting>
/**
 * FooWidget:
 * @bar: some #gboolean
 *
 * This is the best widget, ever.
 */
typedef struct _FooWidget {
  GtkWidget parent_instance;

  gboolean bar;
} FooWidget;
</programlisting>
        </example>

        <para>Use <code>/*&lt; private &gt;*/</code> antes de campos de estructuras privadas que quiera ocultar. Use <code>/*&lt; public &gt;*/</code> para revertir el comportamiento anterior.</para>

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

        <para>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).</para>

      </sect2>

      <sect2><title>Enumerar bloques de comentarios</title>
        <example><title>Enumerar bloques de comentarios</title>
          <programlisting>
/**
 * 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,
  /*&lt; private &gt;*/
  SOMETHING_COUNT
} Something;
</programlisting>
        </example>

        <para>Use <code>/*&lt; private &gt;*/</code> antes de enumerar valores privados que quiera ocultar. Use <code>/*&lt; public &gt;*/</code> para revertir el comportamiento anterior.</para>

      </sect2>
    </sect1>


    <sect1 id="documenting_inline_program">
      <title>Documentación en línea del programa</title>
      <para>Puede documentar programas y su interfaz de línea de comandos usando la documentación en línea.</para>

      <variablelist>
      <title>Etiquetas</title>

      <varlistentry><term>PROGRAM</term>

      <listitem>
      <para>Define el inicio de la documentación de un programa.</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@short_description:</term>
      <listitem>
      <para>Define una descripción corta del programa. (Opcional)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@synopsis:</term>
      <listitem>
      <para>Define el argumento o la lista de argumentos que el programa puede usar. (Opcional)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@see_also:</term>
      <listitem>
      <para>Página del manual Ver también. (Opcional)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@arg:</term>
      <listitem>
      <para>Argumentos pasados al programa y su descripción. (Opcional)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>Description:</term>
      <listitem>
      <para>Una descripción más larga del programa.</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>Devuelve:</term>
      <listitem>
      <para>Especifique qué valores devuelve el programa. (Opcional)</para>
      </listitem>
      </varlistentry>

      </variablelist>

      <sect2>
        <title>Ejemplo de documentación de un programa.</title>
        <example><title>Bloque de documentación del programa</title>
        <programlisting>
/**
 * 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;
}
</programlisting>
        </example>

      </sect2>
    </sect1>

    <sect1 id="documenting_docbook">
      <title>Etiquetas DocBook útiles</title>

      <para>Aquí están varias etiquetas de DocBook muy útiles al documentar código.</para>

      <para>Para enlazar otra sección en GTK docs: <informalexample>
          <programlisting>
&lt;link linkend="glib-Hash-Tables"&gt;Hash Tables&lt;/link&gt;
</programlisting>
        </informalexample>. 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>

      <para>Para referirse a una función externa, ej. una función de C estándar: <informalexample>
          <programlisting>
&lt;function&gt;...&lt;/function&gt;
</programlisting>
        </informalexample></para>

      <para>Para incluir código de ejemplo: <informalexample>
          <programlisting>
&lt;example&gt;
  &lt;title&gt;Using a GHashTable.&lt;/title&gt;
  &lt;programlisting language="C"&gt;
      ...
  &lt;/programlisting&gt;
&lt;/example&gt;
</programlisting>
        </informalexample> o posiblemente esto, para fragmentos de código muy cortos que no necesitan un título: <informalexample>
          <programlisting>
&lt;informalexample&gt;
  &lt;programlisting language="C"&gt;
  ...
  &lt;/programlisting&gt;
&lt;/informalexample&gt;
</programlisting>
        </informalexample> En ambos casos, el atributo de lenguaje es opcional y se utiliza como una pista para el motor de resaltado de sintaxis (pygments para salida html). Para este último, GTK-Doc también admite una abreviatura: <informalexample>
          <programlisting>
|[&lt;!-- language="C" --&gt;
  ...
]|
</programlisting>
        </informalexample></para>

      <para>Para incluir listas de topos: <informalexample>
          <programlisting>
&lt;itemizedlist&gt;
  &lt;listitem&gt;
    &lt;para&gt;
      ...
    &lt;/para&gt;
  &lt;/listitem&gt;
  &lt;listitem&gt;
    &lt;para&gt;
      ...
    &lt;/para&gt;
  &lt;/listitem&gt;
&lt;/itemizedlist&gt;
</programlisting>
        </informalexample></para>

      <para>Para incluir una nota que sobresale del texto: <informalexample>
          <programlisting>
&lt;note&gt;
  &lt;para&gt;
    Make sure you free the data after use.
  &lt;/para&gt;
&lt;/note&gt;
</programlisting>
        </informalexample></para>

      <para>Para referirse a un tipo: <informalexample>
          <programlisting>
&lt;type&gt;unsigned char&lt;/type&gt;
</programlisting>
        </informalexample></para>

      <para>Para referirse a una estructura externa (no una descrita en la documentación de GTK): <informalexample>
          <programlisting>
&lt;structname&gt;XFontStruct&lt;/structname&gt;
</programlisting>
        </informalexample></para>

      <para>Para referirse a un campo o a una estructura: <informalexample>
          <programlisting>
&lt;structfield&gt;len&lt;/structfield&gt;
</programlisting>
        </informalexample></para>

      <para>Para referirse a un nombre de clase, se podría usar: <informalexample>
          <programlisting>
&lt;classname&gt;GtkWidget&lt;/classname&gt;
</programlisting>
        </informalexample> pero probablemente estará usando #GtkWidget en su lugar (para crear automáticamente un enlace a la página GtkWidget; consulte <link linkend="documenting_syntax">abreviaciones</link>).</para>

      <para>Para enfatizar un texto: <informalexample>
          <programlisting>
&lt;emphasis&gt;This is important&lt;/emphasis&gt;
</programlisting>
        </informalexample></para>

      <para>Para uso de nombres de archivo: <informalexample>
          <programlisting>
&lt;filename&gt;/home/user/documents&lt;/filename&gt;
</programlisting>
        </informalexample></para>

      <para>Para referirse a claves: <informalexample>
          <programlisting>
&lt;keycombo&gt;&lt;keycap&gt;Control&lt;/keycap&gt;&lt;keycap&gt;L&lt;/keycap&gt;&lt;/keycombo&gt;
</programlisting>
        </informalexample></para>

    </sect1>
  </chapter>

  <chapter id="metafiles">
    <title>Rellenar campos adicionales</title>

    <para>Existen tres archivos adicionales que deben mantenerse junto con los comentarios en línea del código fuente: <filename>&lt;paquete&gt;.types</filename>, <filename>&lt;paquete&gt;-docs.xml</filename> (.sgml en el pasado) y <filename>&lt;paquete&gt;-sections.txt</filename>.</para>

    <sect1 id="metafiles_types">
      <title>Editar los tipos de archivo</title>

      <para>Si su biblioteca o aplicación incluye GObjects puede querer que sus señales, argumentos y/o parámetros y posición en la jerarquía se muestre en la documentación. Todo lo que debe hacer es listar las funciones <function>xxx_get_type</function> junto con sus «include» en el archivo <filename>&lt;paquete&gt;.types</filename>.</para>

      <para>
        <example><title>Ejemplo de archivo &lt;paquete&gt;.tipos</title>
          <programlisting>
#include &lt;gtk/gtk.h&gt;

gtk_accel_label_get_type
gtk_adjustment_get_type
gtk_alignment_get_type
gtk_arrow_get_type
</programlisting>
        </example>
      </para>

      <para>Desde GTK-Doc 1.8 <application>gtkdoc-scan</application> puede genera esta lista. Simplemente añada «--rebuild-types» a SCAN_OPTIONS en el <filename>Makefile.am</filename>. Si usa esto no debería ejecutar dist sobre los tipos de archivo ni tenerlos bajo el control de versiones.</para>

    </sect1>

    <sect1 id="metafiles_master">
      <title>Editar la sección maestra del documento</title>

      <para>GTK-Doc produce documentación en DocBook SGML/XML. Cuando se procesan los comentarios en las líneas del código, las herramientas de GTK-Doc generan una página de documentación por clase o módulo en un archivo aparte. El documento maestro las incluye y ordena.</para>

      <para>Puesto que GTK-Doc crea una documento maestro de plantilla, una posterior ejecución no lo modificará de nuevo. Esto significa que se puede estructurar libremente la documentación. Esto incluye agrupar páginas y añadir páginas adicionales. Ahora GTK-Doc tiene un entorno de pruebas, donde también el documento maestro se vuelve a crear desde cero. Es una buena idea mirarlo de vez en cuando para ver si se han introducido algunas mejoras.</para>

      <tip>
        <para>No crear tutoriales como documentos adicionales. Solamente escriba capítulos adicionales. La ventaja de integrar directamente el tutorial para su biblioteca en la documentación de la API es que es fácil para el tutorial enlazar la documentación de símbolos. Además las posibilidades de actualizar el tutorial junto con la biblioteca son mayores.</para>
      </tip>

      <para>¿Así que qué es lo que hay que cambiar en el documento maestro? Para empezar es muy poco. Existen algunos «placeholders» (texto entre corchetes) de los que habría que encargarse.</para>

      <para>
        <example><title>Cabecera del documento maestro</title>
          <programlisting>
&lt;bookinfo&gt;
  &lt;title&gt;MODULENAME Reference Manual&lt;/title&gt;
  &lt;releaseinfo&gt;
    for MODULENAME [VERSION]
    The latest version of this documentation can be found on-line at
    &lt;ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html"&gt;http://[SERVER]/MODULENAME/&lt;/ulink&gt;.
  &lt;/releaseinfo&gt;
&lt;/bookinfo&gt;

&lt;chapter&gt;
  &lt;title&gt;[Insert title here]&lt;/title&gt;
</programlisting>
        </example>
      </para>

      <para>Se crean además unos pocos elementos de opciones de la manera comentada. Puede revisarlos y activarlos como quiera.</para>

      <para>
        <example><title>Parte opcional en el documento maestro</title>
          <programlisting>
  &lt;!-- active esto cuando use anotaciones de introspección de gobject
  &lt;xi:include href="xml/annotation-glossary.xml"&gt;&lt;xi:fallback /&gt;&lt;/xi:include&gt;
  --&gt;          
</programlisting>
        </example>
      </para>

      <para>Por último, necesita añadir una sección nueva siempre que quiera introducir una. La herramienta <link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> le recordará los nuevos archivos xml generados que no estén inclídos todavía en la documentación.</para>

      <para>
        <example><title>Incluir secciones generadas</title>
          <programlisting>
  &lt;chapter&gt;
    &lt;title&gt;mi biblioteca&lt;/title&gt;
      &lt;xi:include href="xml/object.xml"/&gt;
      ...
</programlisting>
        </example>
      </para>

    </sect1>

    <sect1 id="metafiles_sections">
      <title>Editar el archivo de sección</title>

      <para>El archivo de sección se usa para organizar la salida de la documentación por GTK-Doc. Aquí se especifica qué símbolos pertenecen a qué módulo o clase y el control de la visibilidad (pública o privada).</para>

      <para>El archivo de sección es un archivo de texto plano con etiquetas que delimitan las secciones. Se ignoran las líneas vacías y las líneas que comiencen con «#» se tratan como comentarios.</para>

      <note>
        <para>Aunque las etiquetas hacen que el archivo parezca XML, no lo es. No incluya etiquetas del tipo &lt;SUBSECTION&gt;.</para>
      </note>

      <para>
        <example><title>Incluir secciones generadas</title>
          <programlisting>
&lt;INCLUDE&gt;libmeep/meep.h&lt;/INCLUDE&gt;

&lt;SECTION&gt;
&lt;FILE&gt;meepapp&lt;/FILE&gt;
&lt;TITLE&gt;MeepApp&lt;/TITLE&gt;
MeepApp
&lt;SUBSECTION Standard&gt;
MEEP_APP
...
MeepAppClass
meep_app_get_type
&lt;/SECTION&gt;
</programlisting>
        </example>
      </para>

      <para>La etiqueta &lt;FILE&gt; ... &lt;/FILE&gt; se usa para especificar el nombre del archivo, sin sufijo. Por ejemplo, usar «&lt;FILE&gt;gnome-config&lt;/FILE&gt;» dará como resultado en la sección de declaraciones la salida <filename>tmpl/gnome-config.sgml</filename> en el archivo de plantilla, que se convertirá al archivo DocBook XML <filename>sgml/gnome-config.sgml</filename> o al archivo DocBook XML <filename>xml/gnome-config.xml</filename>. (El nombre del archivo HTML está basado en el nombre del módulo y en el título de la sección, o para GObjects está basado en el nombre de clase de GObject convertido a minúscula.)</para>

      <para>La etiqueta &lt;TITLE&gt; ... &lt;/TITLE&gt; se usa para especificar el título de una sección. Sólo es útil antes de que las plantillas (si se usan) se creen inicialmente, ya que el título configurado en la plantilla lo sobrescribe. Además, si una usa comentarios SECTION en los fuentes, se queda obsoleto.</para>

      <para>Puede agrupar elementos en la sección usando la etiqueta &lt;SUBSECTION&gt;. Actualmente esto genera una línea en blanco entre subsecciones en la sección de resumen. También puede usar &lt;SUBSECTION Standard&gt; para declaraciones estándar de GObject (ej. funciones como g_object_get_type and macros como G_OBJECT(), G_IS_OBJECT() etc.). Actualmente éstas se han dejado fuera de la documentación. También puede usar &lt;SUBSECTION Private&gt; para declaraciones privadas que no producirán ninguna salida (s una manera práctica de evitar mensajes de advertencia sobre declaraciones sin usar). Si sus bibliotecas contienen tipos privados que no quiere que aparezcan en la jerarquía de objetos o en la lista de interfaces implementados o necesarios, añádalos a una subsección Privada. Si ubica GObject y GObjectClass como estructuras en la sección pública o estándar, depende de si tienen entradas públicas (variables, vmethods).</para>

      <para>También puede usar &lt;INCLUDE&gt; ... &lt;/INCLUDE&gt; para especificar qué archivos #include se muestran en la sección de resumen. Contiene una lista de archivos #include separados por comas, sin las almohadillas. Si lo configura fuera de cualquier sección, actúa para todas las secciones hasta el final del archivo. Si lo configura dentro de una sección, sólo se aplica a esa sección.</para>

    </sect1>

  </chapter>

  <chapter id="reports">
    <title>Controlar el resultado</title>

    <para>Una ejecución de GTK-Doc genera archivos de informe dentro de la carpeta de la documentación. Los archivos generados se llaman <filename>&lt;paquete&gt;-undocumented.txt</filename>, <filename>&lt;paquete&gt;-undeclared.txt</filename> y <filename>&lt;paquete&gt;-unused.txt</filename>.Todos son archivos de texto plano y se pueden ver y posprocesar fácilmente.</para>

    <para>El archivo <filename>&lt;paquete&gt;-undocumented.txt</filename> comienza con el resumen de cobertura de la documentación. Debajo hay dos secciones divididas por líneas vacías. La primera sección lista los símbolos incompletos o indocumentados. La segunda sección hace lo mismo para los documentos de sección. Las entradas incompletas son aquellas que tienen documentación pero dónde; p.e. se ha añadido un parámetro nuevo.</para>

    <para>El archivo <filename>&lt;paquete&gt;-undeclared.txt</filename> lista símbolos proporcionados en el archivo <filename>&lt;paquete&gt;-sections.txt</filename>, pero no encontrados en los fuentes. Compruebe si se han eliminado o no se han escrito correctamente.</para>

    <para>El archivo <filename>&lt;paquete&gt;-unused.txt</filename> lista nombres de símbolos, donde el analizador de GTK-Doc ha encontrado documentación, pero no sabe dónde ponerla. Esto significa que el símbolo no se ha añadido todavía al archivo <filename>&lt;paquete&gt;-sections.txt</filename>.</para>

    <tip>
      <para>Activar o añadir la línea <option>TESTS=($GTKDOC_CHECK)</option> en Makefile.am. Si como mínimo está instalado GTK-Doc 1.9, esto ejecutará comprobaciones de integridad durante la ejecución de make check.</para>
    </tip>

    <para>También puede mirar los archivos producidos por el analizador del código fuente: <filename>&lt;paquete&gt;-decl-list.txt</filename> y <filename>&lt;paquete&gt;-decl.txt</filename>. El primero se puede comparar con el archivo de sección si se mantiene manualmente. El segundo lista todas las declaraciones desde las cabeceras. Si falta un símbolo, se puede comprobar si este archivo lo contiene.</para>

    <para>Si el proyecto está basado en GObject, también se puede mirar en los archivos producidos por el analizador de objetos: <filename>&lt;paquete&gt;.args.txt</filename>, <filename>&lt;paquete&gt;.hierarchy.txt</filename>, <filename>&lt;paquete&gt;.interfaces.txt</filename>, <filename>&lt;paquete&gt;.prerequisites.txt</filename> y <filename>&lt;paquete&gt;.signals.txt</filename>. Si faltan símbolos en cualquiera de ellos, puede hacer que GTK-Doc guarde el análisis de archivos para futuros análisis, pero ejecutándolo como <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.</para>
  </chapter>

  <chapter id="modernizing">
    <title>Modernizar la documentación</title>

    <para>GTK-Doc ha existido durante mucho tiempo. En esta sección se listan las características nuevas junto con la versión desde la que están disponibles.</para>

    <sect1 id="modernizing-gtk-doc-1-9">
      <title>GTK-Doc 1.9</title>

      <para>Al usar XML en lugar de SGML, actualmente se puede nombrar el documento maestro <filename>&lt;paquete&gt;-docs.xml</filename>.</para>

      <para>Esta versión soporta <option>SCAN_OPTIONS=--rebuild-sections</option> en <filename>Makefile.am</filename>. Cuando está activada, el archivo <filename>&lt;paquete&gt;-sections.txt</filename> se genera automáticamente y se puede quitar del control de versiones. Esto sólo funciona en proyectos que tienen una estructura regular (ej. cada pareja .{c,h} creará una sección nueva). Si se organiza un proyecto parecido a esto, actualizar una sección mantenida manualmente puede ser tan sencillo como ejecutar <code>meld &lt;paquete&gt;-decl-list.txt &lt;paquete&gt;-sections.txt</code>.</para>

      <para>La versión 1.18 ya introdujo la sintaxis para documentar secciones en las fuentes en lugar de tener que hacerlo en archivos separados bajo <filename class="directory">tmpl</filename>. Esta versión añade opciones para cambiar todo el módulo «doc» del documento para que no realice el paso de construcción de tmpl adicional, usando <option>--flavour no-tmpl</option> en <filename>configure.ac</filename>. Si no tiene una <filename class="directory">tmpl</filename> marcada en su sistema de control de versiones y todavía no ha cambiado, simplemente añada la opción al archivo <filename>configure.ac</filename> y lo tendrá hecho.</para>
    </sect1>

    <sect1 id="modernizing-gtk-doc-1-10">
      <title>GTK-Doc 1.10</title>

      <para>Esta versión soporta <option>SCAN_OPTIONS=--rebuild-types</option> en <filename>Makefile.am</filename>. Cuando está activado, el archivo <filename>&lt;package&gt;.types</filename> se genera automáticamente y se puede eliminar del control de versiones. Al usar esta característica es importante configurar la variable <varname>IGNORE_HFILES</varname> en el <filename>Makefile.am</filename> para el código que se construye de manera condicional.</para>
    </sect1>

    <sect1 id="modernizing-gtk-doc-1-16">
      <title>GTK-Doc 1.16</title>

      <para>Esta versión incluye una herramienta nueva llamada gtkdoc-check. Esta herramienta puede ejecutar una serie de comprobaciones de integridad de la documentación. Se activa añadiendo las siguientes líneas al final del archivo <filename>Makefile.am</filename>. <example><title>Activar gtkdoc-check</title>
          <programlisting>
if ENABLE_GTK_DOC
TESTS_ENVIRONMENT = \
  DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
  SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
TESTS = $(GTKDOC_CHECK)
endif
</programlisting>
        </example></para>
    </sect1>

    <sect1 id="modernizing-gtk-doc-1-20">
      <title>GTK-Doc 1.20</title>

      <para>La versión 1.18 incluía soporte para cierto marcado inicial. Usar el marcado en los comentarios del documento es menos intrusivo que escribir el XML del «docbook». Esta versión mejora mucho esto y añade muchos más estilos. La sección que explica la <link linkend="documenting_syntax">sintaxis de los comentarios</link> contiene todos los detalles.</para>
    </sect1>

    <sect1 id="modernizing-gtk-doc-1-25">
      <title>GTK-Doc 1.25</title>

      <para>Los makefiles distribuidos con esta versión generan un archivo de entidad en <filename>xml/gtkdocentities.ent</filename>, que contiene entidades para, por ejemplo, nombre_paquete y versión_paquete. Puedes usar esto, por ejemplo, en el archivo xml principal para evitar codificar el número de versión. A continuación se muestra un ejemplo que muestra cómo se incluye el archivo de entidad en la plantilla maestra y cómo se utilizan las entidades. Las entidades también se pueden usar en todos los archivos generados, GTK-Doc usará el mismo encabezado xml en los archivos xml generados. <example><title>Usar entidades generadas previamenet</title>
          <programlisting>
&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  &lt;!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'"&gt;
  &lt;!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent"&gt;
  %gtkdocentities;
]&gt;
&lt;book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"&gt;
  &lt;bookinfo&gt;
    &lt;title&gt;&amp;package_name; Reference Manual&lt;/title&gt;
    &lt;releaseinfo&gt;
      for &amp;package_string;.
      The latest version of this documentation can be found on-line at
      &lt;ulink role="online-location" url="http://[SERVER]/&amp;package_name;/index.html"&gt;http://[SERVER]/&amp;package_name;/&lt;/ulink&gt;.
    &lt;/releaseinfo&gt;
  &lt;/bookinfo&gt;
</programlisting>
        </example></para>
    </sect1>
  </chapter>

  <chapter id="documenting-others">
    <title>Documentar otras interfaces</title>

    <para>Hasta ahora se ha usado GTK-Doc para documentar la API del código. Las siguientes secciones contienen sugerencias acerca de cómo se pueden usar las herramientas para documentar otras interfaces.</para>

    <sect1 id="commandline-interfaces">
      <title>Opciones de la línea de comandos y páginas man</title>

      <para>Ya que también se pueden generar páginas man para referencias de entrada docbook, parece buena idea usarlas para ese propósito. De esta forma la interfaz es parte de la referencia y se obtienen las páginas man sin trabajo.</para>

      <sect2 id="commandline-interfaces-file">
        <title>Documentar la herramienta</title>

        <para>Cree un archivo de entrada de referencia para cada herramienta. Siguiendo <link linkend="settingup_docfiles">el ejemplo</link> se llamará <filename>meep/docs/reference/meeper/meep.xml</filename>. Para las etiquetas xml que se deben usar puede mirar al archivo generado en la subcarpeta xml así como los ejemplos en, por ejemplo, glib.</para>
      </sect2>

      <sect2 id="commandline-interfaces-configure">
        <title>Añadir la comprobación de configuración adicional</title>

        <para>
          <example><title>Comprobaciones de configuración adicionales</title>
            <programlisting>
AC_ARG_ENABLE(man,
              [AC_HELP_STRING([--enable-man],
                              [regenerate man pages from Docbook [default=no]])],enable_man=yes,
              enable_man=no)

AC_PATH_PROG([XSLTPROC], [xsltproc])
AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)
</programlisting>
          </example>
        </para>
      </sect2>

      <sect2 id="commandline-interfaces-make">
        <title>Añadir reglas de makefile adicionales</title>

        <para>
          <example><title>Comprobaciones de configuración adicionales</title>
            <programlisting>
man_MANS = \
       meeper.1

if ENABLE_GTK_DOC
if ENABLE_MAN

%.1 : %.xml
        @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $&lt;

endif
endif

BUILT_EXTRA_DIST = $(man_MANS)
EXTRA_DIST += meep.xml
</programlisting>
          </example>
        </para>
      </sect2>
    </sect1>

    <sect1 id="dbus-interfaces">
      <title>Interfaces de DBus</title>

      <para>(ARREGLAR: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)</para>
    </sect1>

  </chapter>

  <chapter id="faq">
    <title>Preguntas más frecuentes</title>

    <segmentedlist>
      <?dbhtml list-presentation="list"?>
      <segtitle>Pregunta</segtitle>
      <segtitle>Respuesta</segtitle>
      <seglistitem>
        <seg>Sin jerarquía de clases.</seg>
        <seg>Los objetos de la función <function>xxx_get_type()</function> no se han introducido en el archivo <filename>&lt;package&gt;.types</filename>.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Aún sin jerarquía de clases.</seg>
        <seg>Nombre incorrecto o ausente en el archivo <filename>&lt;package&gt;-sections.txt</filename> (consulte la <ulink url="http://mail.gnome.org/archives/gtk-doc-list/2003-October/msg00006.html">explicación</ulink>).</seg>
      </seglistitem>
      <seglistitem>
        <seg>Maldición, aún no hay una jerarquía de clases.</seg>
        <seg>Es el nombre del objeto (nombre de la estructura de la instancia, ej. <type>GtkWidget</type>) parte de la sección normal (no ponga esto en Estándar o Privado).</seg>
      </seglistitem>
      <seglistitem>
        <seg>Sin índice de símbolos.</seg>
        <seg>¿<filename>&lt;package&gt;-docs.{xml,sgml}</filename> contiene un índice que «xi:includes» el índice generado?</seg>
      </seglistitem>
      <seglistitem>
        <seg>Los símbolos no se enlazan con su sección en el documento.</seg>
        <seg>¿Está doc-comment usando el marcado correcto (añadido #,% o ())? Compruebe si gtk-doc-fixxref avisa de alguna referencia xref sin resolver.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Una clase nueva no aparece en la documentación.</seg>
        <seg>Es la página nueva «xi:included» desde <filename>&lt;package&gt;-docs.{xml,sgml}</filename>.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Un símbolo nuevo no aparece en la documentación.</seg>
        <seg>Comprobar que el doc-comment está formateado correctamente. Compruebe errores de escritura al principio del comentario. Compruebe si gtkdoc-fixxref avisa acerca de referencias xref no solventables. Compruebe si el símbolo está listado correctamente en <filename>&lt;package&gt;-sections.txt</filename> en una subsección pública.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Falta un tipo en la clase de jerarquías</seg>
        <seg>Si el tipo está listado en <filename>&lt;package&gt;.hierarchy</filename> pero no en <filename>xml/tree_index.sgml</filename>, entonces compruebe dos veces que el tipo está correctamente ubicado en la <filename>&lt;package&gt;-sections.txt</filename>. No se mostrará el tipo de instancia (ej. <type>GtkWidget</type>) si no está listada o accidentalmente marcada como privada.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Obtengo enlaces de seguimiento de documentos para todas las anotaciones gobject.</seg>
        <seg>Compruebe que <filename>xml/annotation-glossary.xml</filename> está «xi:included» desde <filename>&lt;package&gt;-docs.{xml,sgml}</filename>.</seg>
      </seglistitem>

      <!-- gtk-doc warnings: -->
      <seglistitem>
        <seg>Parámetro descrito en el bloque de comentarios del código fuente pero no existe</seg>
        <seg>Compruebe si el prototipo en la cabecera tiene nombres de parámetro diferentes de la fuente.</seg>
      </seglistitem>

      <!-- docbook warnings: -->
      <seglistitem>
        <seg>múltiples «ID» para la restricción enlazada: XYZ</seg>
        <seg>El símbolo XYZ aparece dos veces en el archivo <filename>&lt;package&gt;-sections.txt</filename>.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Elemento typename en namespace «» encontrado en para, pero ninguna plantilla coincide.</seg>
        <seg/>
      </seglistitem>
    </segmentedlist>
  </chapter>

  <chapter id="contrib">
    <title>Herramientas relacionadas con GTK-Doc</title>

    <para>GtkDocPlugin: un complemento de integración <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">Trac GTK-Doc</ulink> que añade documentos de la API a un sitio «trac» y se integra con la búsqueda de «trac».</para>
    <para>Gtkdoc-depscan: una herramienta (parte de gtk-doc) para comprobar la API usada contra etiquetas en la API para determinar la versión mínima necesaria.</para>

  </chapter>

  <!-- ======== Appendix: FDL ================================== -->
  

</book>
