help/manual/C/index.docbook

   1 <?xml version="1.0" standalone="no"?>
   2 <?xml-stylesheet type="text/xml" href="params.xsl"?>
   3 <!-- vim: set ai tw=80 ts=3 sw=3: -->
   4 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "
   5               http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
   6
   7 <!ENTITY FDL SYSTEM "fdl-appendix.xml">
   8 <!ENTITY FDLlink "<link linkend='fdl'>included</link>">
   9 ]><!-- =============Document Header ============================= -->
  10 <book id="index">
  11   <bookinfo>
  12     <title>GTK-Doc Manual</title>
  13     <edition>1.24.1</edition>
  14     <abstract role="description"><para>User manual for developers with instructions of GTK-Doc usage.</para></abstract>
  15     <authorgroup>
  16       <author>
  17         <firstname>Chris</firstname>
  18         <surname>Lyttle</surname>
  19         <affiliation>
  20           <address>
  21             <email>chris@wilddev.net</email>
  22           </address>
  23         </affiliation>
  24       </author>
  25       <author>
  26         <firstname>Dan</firstname>
  27         <surname>Mueth</surname>
  28         <affiliation>
  29           <address>
  30             <email>d-mueth@uchicago.edu</email>
  31           </address>
  32         </affiliation>
  33       </author>
  34       <author>
  35         <firstname>Stefan</firstname>
  36         <surname>Sauer (Kost)</surname>
  37         <affiliation>
  38           <address>
  39             <email>ensonic@users.sf.net</email>
  40           </address>
  41         </affiliation>
  42       </author>
  43     </authorgroup>
  44     <publisher role="maintainer">
  45       <publishername>GTK-Doc project</publishername>
  46       <address><email>gtk-doc-list@gnome.org</email></address>
  47     </publisher>
  48     <copyright>
  49       <year>2000, 2005</year>
  50       <holder>Dan Mueth and Chris Lyttle</holder>
  51     </copyright>
  52     <copyright>
  53       <year>2007-2015</year>
  54       <holder>Stefan Sauer (Kost)</holder>
  55     </copyright>
  56
  57     <!-- translators: uncomment this:
  58     <copyright>
  59       <year>2000</year>
  60       <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  61     </copyright>
  62     -->
  63
  64     <legalnotice>
  65       <para>
  66         Permission is granted to copy, distribute and/or modify this
  67         document under the terms of the <citetitle>GNU Free Documentation
  68         License</citetitle>, Version 1.1 or any later version published
  69         by the Free Software Foundation with no Invariant Sections, no
  70         Front-Cover Texts, and no Back-Cover Texts. A copy of the license
  71         is &FDLlink;.
  72       </para>
  73       <para>
  74         Many of the names used by companies to distinguish their products and
  75         services are claimed as trademarks. Where those names appear in any
  76         GNOME documentation, and those trademarks are made aware to the members
  77         of the GNOME Documentation Project, the names have been printed in caps
  78         or initial caps.
  79       </para>
  80     </legalnotice>
  81
  82     <revhistory>
  83       <revision>
  84          <revnumber>1.25.1</revnumber>
  85          <date>21 March 2016</date>
  86          <authorinitials>ss</authorinitials>
  87          <revremark>development version</revremark>
  88        </revision>
  89       <revision>
  90         <revnumber>1.25</revnumber>
  91         <date>21 March 2016</date>
  92         <authorinitials>ss</authorinitials>
  93         <revremark>bug fixes, test cleanups</revremark>
  94       </revision>
  95       <revision>
  96         <revnumber>1.24</revnumber>
  97         <date>29 May 2015</date>
  98         <authorinitials>ss</authorinitials>
  99         <revremark>bug fix</revremark>
 100       </revision>
 101       <revision>
 102         <revnumber>1.23</revnumber>
 103         <date>17 May 2015</date>
 104         <authorinitials>ss</authorinitials>
 105         <revremark>bug fix</revremark>
 106       </revision>
 107       <revision>
 108         <revnumber>1.22</revnumber>
 109         <date>07 May 2015</date>
 110         <authorinitials>ss</authorinitials>
 111         <revremark>bug fixes, dropping deprecated features</revremark>
 112       </revision>
 113       <revision>
 114         <revnumber>1.21</revnumber>
 115         <date>17 Jul 2014</date>
 116         <authorinitials>ss</authorinitials>
 117         <revremark>bug fixes, dropping deprecated features</revremark>
 118       </revision>
 119       <revision>
 120         <revnumber>1.20</revnumber>
 121         <date>16 Feb 2014</date>
 122         <authorinitials>ss</authorinitials>
 123         <revremark>bug fixes, markdown support, style improvements</revremark>
 124       </revision>
 125       <revision>
 126         <revnumber>1.19</revnumber>
 127         <date>05 Jun 2013</date>
 128         <authorinitials>ss</authorinitials>
 129         <revremark>bug fixes</revremark>
 130       </revision>
 131       <revision>
 132         <revnumber>1.18</revnumber>
 133         <date>14 Sep 2011</date>
 134         <authorinitials>ss</authorinitials>
 135         <revremark>bug fixes, speedups, markdown support</revremark>
 136       </revision>
 137       <revision>
 138         <revnumber>1.17</revnumber>
 139         <date>26 Feb 2011</date>
 140         <authorinitials>sk</authorinitials>
 141         <revremark>urgent bug fix update</revremark>
 142       </revision>
 143       <revision>
 144         <revnumber>1.16</revnumber>
 145         <date>14 Jan 2011</date>
 146         <authorinitials>sk</authorinitials>
 147         <revremark>bugfixes, layout improvements</revremark>
 148       </revision>
 149       <revision>
 150         <revnumber>1.15</revnumber>
 151         <date>21 May 2010</date>
 152         <authorinitials>sk</authorinitials>
 153         <revremark>bug and regression fixes</revremark>
 154       </revision>
 155       <revision>
 156         <revnumber>1.14</revnumber>
 157         <date>28 March 2010</date>
 158         <authorinitials>sk</authorinitials>
 159         <revremark>bugfixes and performance improvements</revremark>
 160       </revision>
 161       <revision>
 162         <revnumber>1.13</revnumber>
 163         <date>18 December 2009</date>
 164         <authorinitials>sk</authorinitials>
 165         <revremark>broken tarball update</revremark>
 166       </revision>
 167       <revision>
 168         <revnumber>1.12</revnumber>
 169         <date>18 December 2009</date>
 170         <authorinitials>sk</authorinitials>
 171         <revremark>new tool features and bugfixes</revremark>
 172       </revision>
 173       <revision>
 174         <revnumber>1.11</revnumber>
 175         <date>16 November 2008</date>
 176         <authorinitials>mal</authorinitials>
 177         <revremark>GNOME doc-utils migration</revremark>
 178       </revision>
 179     </revhistory>
 180
 181   </bookinfo>
 182
 183   <!-- ======== Chapter 1: Introduction ======================== -->
 184
 185   <chapter id="introduction">
 186     <title>Introduction</title>
 187
 188     <para>
 189       This chapter introduces GTK-Doc and gives an overview of what it is and
 190       how it is used.
 191     </para>
 192
 193     <sect1 id="whatisgtkdoc">
 194       <title>What is GTK-Doc?</title>
 195
 196       <para>
 197         GTK-Doc is used to document C code. It is typically used to document the public
 198         API of libraries, such as the GTK+ and GNOME libraries. But it can also be
 199         used to document application code.
 200       </para>
 201     </sect1>
 202
 203     <sect1 id="howdoesgtkdocwork">
 204       <title>How Does GTK-Doc Work?</title>
 205
 206       <para>
 207         GTK-Doc works by using documentation of functions placed inside the source files in
 208         specially-formatted comment blocks, or documentation added to the template files
 209         which GTK-Doc uses (though note that GTK-Doc will only document functions that
 210         are declared in header files; it won't produce output for static functions).
 211       </para>
 212
 213       <para>
 214         GTK-Doc consists of a number of perl scripts, each performing a different step
 215         in the process.
 216       </para>
 217
 218       <para>
 219         There are 5 main steps in the process:
 220       </para>
 221
 222       <orderedlist>
 223
 224         <listitem>
 225           <para>
 226             <guilabel>Writing the documentation.</guilabel>
 227
 228             The author fills in the source files with the documentation for each
 229             function, macro, union etc. (In the past information was entered in
 230             generated template files, which is not recommended anymore).
 231           </para>
 232         </listitem>
 233
 234         <listitem>
 235           <para>
 236             <guilabel>Gathering information about the code.</guilabel>
 237
 238             <application>gtkdoc-scan</application> scans the header files of the
 239             code looking for declarations of functions, macros, enums, structs, and unions.
 240             It creates the file <filename>&lt;module&gt;-decl-list.txt</filename> containing a list of the
 241             declarations, placing them into sections according to which header file they
 242             are in. On the first run this file is copied to <filename>&lt;module&gt;-sections.txt</filename>.
 243             The author can rearrange the sections, and the order of the
 244             declarations within them, to produce the final desired order.
 245             The second file it generates is <filename>&lt;module&gt;-decl.txt</filename>.
 246             This file contains the full declarations found by the scanner. If for
 247             some reason one would like some symbols to show up in the docs, where
 248             the full declaration cannot be found by the scanner or the declaration
 249             should appear differently, one can place entities similar to the ones in
 250             <filename>&lt;module&gt;-decl.txt</filename> into <filename>&lt;module&gt;-overrides.txt</filename>.
 251          </para>
 252          <para>
 253             <application>gtkdoc-scangobj</application> can also be used to dynamically query a library about
 254             any GObject subclasses it exports. It saves information about each
 255             object's position in the class hierarchy and about any GObject properties
 256             and signals it provides.
 257           </para>
 258          <para>
 259             <application>gtkdoc-scanobj</application> should not be used anymore.
 260             It was needed in the past when GObject was still GtkObject inside gtk+.
 261          </para>
 262         </listitem>
 263
 264         <listitem>
 265           <para>
 266             <guilabel>Generating the "template" files.</guilabel>
 267
 268             <application>gtkdoc-mktmpl</application> creates a number of files in
 269             the <filename class='directory'>tmpl/</filename> subdirectory, using the
 270             information gathered in the first step. (Note that this can be run
 271             repeatedly. It will try to ensure that no documentation is ever lost.)
 272           </para>
 273           <note>
 274             <para>
 275               Since GTK-Doc 1.9 the templates can be avoided. We encourage people to keep
 276               documentation in the code. <application>gtkdocize</application> supports now
 277               a <option>--flavour no-tmpl</option> option that chooses a makefile that
 278               skips tmpl usage totally.
 279               If you have never changed file in tmpl by hand, please remove the directory
 280               (e.g. from version control system).
 281             </para>
 282           </note>
 283         </listitem>
 284
 285         <listitem>
 286           <para>
 287             <guilabel>Generating the XML and HTML/PDF.</guilabel>
 288
 289             <application>gtkdoc-mkdb</application> turns the template files into
 290             XML files in the <filename class='directory'>xml/</filename> subdirectory.
 291             If the source code contains documentation on functions, using the
 292             special comment blocks, it gets merged in here. If there are no tmpl files used
 293             it only reads docs from sources and introspection data.
 294           </para>
 295           <para>
 296             <application>gtkdoc-mkhtml</application> turns the XML files into HTML
 297             files in the <filename class='directory'>html/</filename> subdirectory.
 298             Likewise <application>gtkdoc-mkpdf</application> turns the XML files into a PDF
 299             document called <filename>&lt;package&gt;.pdf</filename>.
 300           </para>
 301           <para>
 302             Files in <filename class='directory'>xml/</filename> and
 303             <filename class='directory'>html/</filename> directories are always
 304             overwritten. One should never edit them directly.
 305           </para>
 306         </listitem>
 307
 308         <listitem>
 309           <para>
 310             <guilabel>Fixing up cross-references between documents.</guilabel>
 311
 312             After installing the HTML files, <application>gtkdoc-fixxref</application> can be run to fix up any
 313             cross-references between separate documents. For example, the GTK+
 314             documentation contains many cross-references to types documented in the GLib manual.
 315
 316             When creating the source tarball for distribution, <application>gtkdoc-rebase</application>
 317             turns all external links into web-links. When installing distributed (pregenerated) docs
 318             the same application will try to turn links back to local links
 319             (where those docs are installed).
 320           </para>
 321         </listitem>
 322       </orderedlist>
 323
 324     </sect1>
 325
 326     <sect1 id="gettinggtkdoc">
 327       <title>Getting GTK-Doc</title>
 328
 329       <sect2 id="requirements">
 330         <title>Requirements</title>
 331         <para>
 332           <guilabel>Perl v5</guilabel> - the main scripts are in Perl.
 333         </para>
 334         <para>
 335           <guilabel>xsltproc</guilabel> - the xslt processor from libxslt
 336           <ulink url="http://xmlsoft.org/XSLT/" type="http">xmlsoft.org/XSLT/</ulink>
 337         </para>
 338         <para>
 339           <guilabel>docbook-xsl</guilabel> - the docbook xsl stylesheets
 340           <ulink url="http://sourceforge.net/projects/docbook/files/docbook-xsl/" type="http">sourceforge.net/projects/docbook/files/docbook-xsl</ulink>
 341         </para>
 342         <para>
 343           <guilabel>Python</guilabel> - optional - for gtkdoc-depscan
 344         </para>
 345         <para>
 346           One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> or
 347           <guilabel>vim</guilabel> - optional - used for syntax highlighting of examples
 348         </para>
 349       </sect2>
 350     </sect1>
 351
 352     <sect1 id="aboutgtkdoc">
 353       <title>About GTK-Doc</title>
 354
 355       <para>
 356         (FIXME)
 357       </para>
 358
 359       <para>
 360         (History, authors, web pages, mailing list, license, future plans,
 361         comparison with other similar systems.)
 362       </para>
 363
 364     </sect1>
 365
 366     <sect1 id="aboutthismanual">
 367       <title>About this Manual</title>
 368
 369       <para>
 370         (FIXME)
 371       </para>
 372
 373       <para>
 374         (who it is meant for, where you can get it, license)
 375       </para>
 376
 377     </sect1>
 378
 379   </chapter>
 380
 381   <chapter id="settingup">
 382     <title>Setting up your project</title>
 383
 384     <para>
 385       The next sections describe what steps to perform to integrate GTK-Doc into
 386       your project. Theses sections assume we work on a project called 'meep'.
 387       This project contains a library called 'libmeep' and
 388       an end-user app called 'meeper'. We also assume you will be using autoconf
 389       and automake. In addition section <link linkend="plain_makefiles">plain
 390       makefiles or other build systems</link> will describe the basics needed to
 391       work in a different build setup.
 392     </para>
 393
 394     <sect1 id="settingup_docfiles">
 395       <title>Setting up a skeleton documentation</title>
 396
 397       <para>
 398         Under your top-level project directory create folders called docs/reference
 399         (this way you can also have docs/help for end-user documentation).
 400         It is recommended to create another subdirectory with the name of the doc-package.
 401         For packages with just one library this step is not necessary.
 402       </para>
 403
 404       <para>
 405         This can then look as shown below:
 406         <example><title>Example directory structure</title>
 407           <programlisting><![CDATA[
 408 meep/
 409   docs/
 410     reference/
 411       libmeep/
 412       meeper/
 413   src/
 414     libmeep/
 415     meeper/
 416 ]]></programlisting>
 417         </example>
 418       </para>
 419     </sect1>
 420
 421     <sect1 id="settingup_autoconf">
 422       <title>Integration with autoconf</title>
 423
 424       <para>
 425         Very easy! Just add one line to your <filename>configure.ac</filename> script.
 426       </para>
 427
 428       <para>
 429         <example><title>Integration with autoconf</title>
 430           <programlisting><![CDATA[
 431 # check for gtk-doc
 432 GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
 433 ]]></programlisting>
 434         </example>
 435       </para>
 436
 437       <para>
 438         This will require all developers to have gtk-doc installed. If it is
 439         okay for your project to have optional api-doc build setup, you can
 440         solve this as below. Keep it as is, as gtkdocize is looking for
 441         <function>GTK_DOC_CHECK</function>  at the start of a line.
 442         <example><title>Keep gtk-doc optional</title>
 443           <programlisting><![CDATA[
 444 # check for gtk-doc
 445 m4_ifdef([GTK_DOC_CHECK], [
 446 GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
 447 ],[
 448 AM_CONDITIONAL([ENABLE_GTK_DOC], false)
 449 ])
 450 ]]></programlisting>
 451         </example>
 452       </para>
 453
 454       <para>
 455         The first argument is used to check for the gtkdocversion at configure time.
 456         The 2nd, optional argument is used by <application>gtkdocize</application>.
 457         The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure switches:
 458       </para>
 459       <orderedlist>
 460         <listitem><para>--with-html-dir=PATH : path to installed docs</para></listitem>
 461         <listitem><para>--enable-gtk-doc : use gtk-doc to build documentation [default=no]</para></listitem>
 462         <listitem><para>--enable-gtk-doc-html : build documentation in html format [default=yes]</para></listitem>
 463         <listitem><para>--enable-gtk-doc-pdf : build documentation in pdf format [default=no]</para></listitem>
 464       </orderedlist>
 465
 466       <important>
 467         <para>
 468           GTK-Doc is disabled by default! Remember to pass the option
 469           <option>'--enable-gtk-doc'</option> to the next
 470           <filename>configure</filename> run. Otherwise pregenerated documentation is installed
 471           (which makes sense for users but not for developers).
 472         </para>
 473       </important>
 474
 475       <para>
 476         Furthermore it is recommended that you have the following line inside
 477         you <filename>configure.ac</filename> script.
 478         This allows <application>gtkdocize</application> to automatically copy the
 479         macro definition for <function>GTK_DOC_CHECK</function> to your project.
 480       </para>
 481
 482       <para>
 483         <example><title>Preparation for gtkdocize</title>
 484           <programlisting><![CDATA[
 485 AC_CONFIG_MACRO_DIR(m4)
 486 ]]></programlisting>
 487         </example>
 488       </para>
 489       <para>
 490         After all changes to <filename>configure.ac</filename> are made, update
 491         the <filename>configure</filename> file. This can be done by re-running
 492         <code>autoreconf -i</code> or <code>autogen.sh</code>.
 493       </para>
 494     </sect1>
 495
 496     <sect1 id="settingup_automake">
 497       <title>Integration with automake</title>
 498
 499       <para>
 500         First copy the <filename>Makefile.am</filename> from the
 501         <filename class='directory'>examples</filename> sub directory of the
 502         <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink>
 503         to your project's API documentation directory (
 504         <filename class='directory'>./docs/reference/&lt;package&gt;</filename>).
 505         A local copy should be available under e.g.
 506         <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
 507         If you have multiple doc-packages repeat this for each one.
 508       </para>
 509
 510       <para>
 511         The next step is to edit the settings inside the <filename>Makefile.am</filename>.
 512         All the settings have a comment above that describes their purpose.
 513         Most settings are extra flags passed to the respective tools. Every tool
 514         has a variable of the form <option>&lt;TOOLNAME&gt;_OPTIONS</option>.
 515         All the tools support <option>--help</option> to list the supported
 516         parameters.
 517       </para>
 518
 519       <!-- FIXME: explain options ? -->
 520
 521     </sect1>
 522
 523     <sect1 id="settingup_autogen">
 524       <title>Integration with autogen</title>
 525
 526       <para>
 527         Most projects will have an <filename>autogen.sh</filename> script to
 528         setup the build infrastructure after a checkout from version control
 529         system (such as cvs/svn/git). GTK-Doc comes with a tool called
 530         <application>gtkdocize</application> which can be used in such a script.
 531         It should be run before autoheader, automake or autoconf.
 532       </para>
 533
 534       <para>
 535         <example><title>Running gtkdocize from autogen.sh</title>
 536           <programlisting><![CDATA[
 537 gtkdocize || exit 1
 538 ]]></programlisting>
 539         </example>
 540       </para>
 541
 542       <para>
 543         When running <application>gtkdocize</application> it copies
 544         <filename>gtk-doc.make</filename> to your project root (or any directory
 545         specified by the <option>--docdir</option> option).
 546         It also checks you configure script for the <function>GTK_DOC_CHECK</function>
 547         invocation. This macro can be used to pass extra parameters to
 548         <application>gtkdocize</application>.
 549       </para>
 550
 551       <para>
 552         Historically GTK-Doc was generating template files where developers entered the docs.
 553         This turned out to be not so good (e.g. the need for having generated
 554         files under version control).
 555         Since GTK-Doc 1.9 the tools can get all the information from source comments
 556         and thus the templates can be avoided. We encourage people to keep
 557         documentation in the code. <application>gtkdocize</application> supports now
 558         a <option>--flavour no-tmpl</option> option that chooses a makefile that skips
 559         tmpl usage totally. Besides adding the option directly to the command
 560         invocation, they can be added also to an environment variable called <symbol>GTKDOCIZE_FLAGS</symbol>
 561         or set as a 2nd parameter in <symbol>GTK_DOC_CHECK</symbol> macro in the configure script.
 562         If you have never changed file in tmpl by hand and migrating from older gtkdoc versions,
 563         please remove the directory (e.g. from version control system).
 564       </para>
 565     </sect1>
 566
 567     <sect1 id="settingup_firstrun">
 568       <title>Running the doc build</title>
 569
 570       <para>
 571         After the previous steps it's time to run the build. First we need to
 572         rerun <filename>autogen.sh</filename>. If this script runs configure for
 573         you, then give it the <option>--enable-gtk-doc</option> option.
 574         Otherwise manually run <filename>configure</filename> with this option
 575         afterwards.
 576       </para>
 577       <para>
 578         The first make run generates several additional files in the doc-directories.
 579         The important ones are:
 580         <filename>&lt;package&gt;.types</filename>,
 581         <filename>&lt;package&gt;-docs.xml</filename> (in the past .sgml),
 582         <filename>&lt;package&gt;-sections.txt</filename>.
 583       </para>
 584       <para>
 585         <example><title>Running the doc build</title>
 586           <programlisting><![CDATA[
 587 ./autogen.sh --enable-gtk-doc
 588 make
 589 ]]></programlisting>
 590         </example>
 591       </para>
 592       <para>
 593         Now you can point your browser to <filename>docs/reference/&lt;package&gt;/index.html</filename>.
 594         Yes, it's a bit disappointing still. But hang-on, during the next chapter we
 595         tell you how to fill the pages with life.
 596       </para>
 597     </sect1>
 598
 599     <sect1 id="settingup_vcs">
 600       <title>Integration with version control systems</title>
 601
 602       <para>
 603         As a rule of thumb, it's the files you edit which should go under
 604         version control. For typical projects it's these files:
 605         <filename>&lt;package&gt;.types</filename>,
 606         <filename>&lt;package&gt;-docs.xml</filename> (in the past .sgml),
 607         <filename>&lt;package&gt;-sections.txt</filename>,
 608         <filename>Makefile.am</filename>.
 609       </para>
 610       <para>
 611         Files in the <filename>xml/</filename> and <filename>html/</filename>
 612         directories should not go under version control. Neither should any of
 613         the <filename>.stamp</filename> files.
 614       </para>
 615     </sect1>
 616
 617     <sect1 id="plain_makefiles">
 618       <title>Integration with plain makefiles or other build systems</title>
 619
 620       <para>
 621         In the case one does not want to use automake and therefore
 622         <filename>gtk-doc.mak</filename> one will need to call the gtkdoc tools
 623         in the right order in own makefiles (or other build tools).
 624       </para>
 625
 626       <para>
 627         <example><title>Documentation build steps</title>
 628           <programlisting><![CDATA[
 629 DOC_MODULE=meep
 630 // sources have changed
 631 gtkdoc-scan --module=$(DOC_MODULE) <source-dir>
 632 gtkdoc-scangobj --module=$(DOC_MODULE)
 633 gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>
 634 // xml files have changed
 635 mkdir html
 636 cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
 637 gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
 638 ]]></programlisting>
 639         </example>
 640       </para>
 641
 642       <para>
 643         One will need to look at the <filename>Makefile.am</filename> and
 644         <filename>gtk-doc.mak</filename> to pick the extra options needed.
 645       </para>
 646     </sect1>
 647
 648     <sect1 id="cmake">
 649        <title>Integration with CMake build systems</title>
 650
 651        <para>
 652           GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
 653           (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
 654           module). This provides a <literal>gtk_doc_add_module</literal>
 655           command that you can set in your <filename>CMakeLists.txt</filename>
 656           file.
 657        </para>
 658
 659        <para>
 660           The following example shows how to use this command.
 661           <example><title>Example of using GTK-Doc from CMake</title>
 662              <programlisting><![CDATA[
 663 find_package(GtkDoc 1.25 REQUIRED)
 664
 665 # Create the doc-libmeep target.
 666 gtk_doc_add_module(
 667    libmeep ${CMAKE_SOURCE_DIR}/libmeep
 668       XML meep-docs.xml
 669       LIBRARIES libmeep
 670 )
 671
 672 # Build doc-libmeep as part of the default target. Without this, you would
 673 # have to explicitly run something like `make doc-libmeep` to build the docs.
 674 add_custom_target(documentation ALL DEPENDS doc-libmeep)
 675
 676 # Install the docs. (This assumes you're using the GNUInstallDirs CMake module
 677 # to set the CMAKE_INSTALL_DOCDIR variable correctly).
 678 install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
 679         DESTINATION ${CMAKE_INSTALL_DOCDIR})
 680 ]]></programlisting>
 681          </example>
 682        </para>
 683      </sect1>
 684   </chapter>
 685
 686   <chapter id="documenting">
 687     <title>Documenting the code</title>
 688
 689     <para>
 690       GTK-Doc uses source code comment with a special syntax for code documentation.
 691       Further it retrieves information about your project structure from other
 692       sources. During the next section you will find all information about the
 693       syntax of the comments.
 694     </para>
 695
 696     <note>
 697       <title>Documentation placement</title>
 698       <para>
 699         In the past most documentation had to be filled into files residing
 700         inside the <filename>tmpl</filename> directory. This has the
 701         disadvantages that the information is often not updated and also that
 702         the file tend to cause conflicts with version control systems.
 703       </para>
 704       <para>
 705         The avoid the aforementioned problems we suggest putting the
 706         documentation inside the sources. This manual will only describe this
 707         way of documenting code.
 708       </para>
 709     </note>
 710
 711     <para>
 712       The scanner can handle the majority of C headers fine. In the case of
 713       receiving warnings from the scanner that look like a special case, one can
 714       hint GTK-Doc to skip over them.
 715       <example><title>GTK-Doc comment block</title>
 716         <programlisting><![CDATA[
 717 #ifndef __GTK_DOC_IGNORE__
 718 /* unparseable code here */
 719 #endif
 720 ]]></programlisting>
 721       </example>
 722     </para>
 723
 724     <note>
 725       <title>Limitations</title>
 726       <para>
 727         Note, that GTK-Doc's supports
 728         <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
 729         <code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations.
 730       </para>
 731     </note>
 732
 733     <!--  -->
 734
 735     <sect1 id="documenting_syntax">
 736       <title>Documentation comments</title>
 737
 738       <para>
 739         A multiline comment that starts with an additional '*' marks a
 740         documentation block that will be processed by the GTK-Doc tools.
 741         <example><title>GTK-Doc comment block</title>
 742           <programlisting><![CDATA[
 743 /**
 744  * identifier:
 745  * documentation ...
 746  */
 747 ]]></programlisting>
 748         </example>
 749       </para>
 750
 751       <para>
 752         The 'identifier' is one line with the name of the item the comment is
 753         related to. The syntax differs a little depending on the item.
 754         (TODO add table showing identifiers)
 755       </para>
 756
 757       <para>
 758         The 'documentation' block is also different for each symbol type. Symbol
 759         types that get parameters such as functions or macros have the parameter
 760         description first followed by a blank line (just a '*').
 761         Afterwards follows the detailed description. All lines (outside program
 762         listings and CDATA sections) just containing a ' *' (blank-asterisk) are
 763         converted to paragraph breaks.
 764         If you don't want a paragraph break, change that into ' *  '
 765         (blank-asterisk-blank-blank). This is useful in preformatted text (code
 766         listings).
 767       </para>
 768
 769       <tip>
 770         <para>
 771           When documenting code, describe two aspects:
 772           <itemizedlist>
 773              <listitem>
 774                <para>
 775                  What it is: The name for a class or function can sometimes
 776                  be misleading for people coming from a different background.
 777                 </para>
 778              </listitem>
 779              <listitem>
 780                <para>
 781                  What it does: Tell about common uses. Put it in relation
 782                  with the other API.
 783                </para>
 784              </listitem>
 785            </itemizedlist>
 786         </para>
 787       </tip>
 788
 789       <para>
 790         One advantage of hyper-text over plain-text is the ability to have links
 791         in the document. Writing the correct markup for a link can be tedious
 792         though. GTK-Doc comes to help by providing several useful abbreviations.
 793         <itemizedlist>
 794           <listitem>
 795             <para>
 796               Use function() to refer to functions or macros which take arguments.
 797             </para>
 798           </listitem>
 799           <listitem>
 800             <para>
 801               Use @param to refer to parameters. Also use this when referring to
 802               parameters of other functions, related to the one being described.
 803             </para>
 804           </listitem>
 805           <listitem>
 806             <para>
 807               Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS.
 808             </para>
 809           </listitem>
 810           <listitem>
 811             <para>
 812               Use #symbol to refer to other types of symbol, e.g. structs and
 813               enums and macros which don't take arguments.
 814             </para>
 815           </listitem>
 816           <listitem>
 817             <para>
 818               Use #Object::signal to refer to a GObject signal.
 819             </para>
 820           </listitem>
 821           <listitem>
 822             <para>
 823               Use #Object:property to refer to a GObject property.
 824             </para>
 825           </listitem>
 826           <listitem>
 827             <para>
 828               Use #Struct.field to refer to a field inside a structure and
 829               #GObjectClass.foo_bar() to refer to a vmethod.
 830             </para>
 831           </listitem>
 832         </itemizedlist>
 833       </para>
 834
 835       <tip>
 836         <para>
 837           If you need to use the special characters '&lt;', '&gt;', '()', '@',
 838           '%', or '#' in your documentation without GTK-Doc changing them you
 839           can use the XML entities "&amp;lt;", "&amp;gt;", "&amp;lpar;",
 840           "&amp;rpar;", "&amp;commat;", "&amp;percnt;" and "&amp;num;"
 841           respectively or escape them with a backslash '\'.
 842         </para>
 843       </tip>
 844
 845       <para>
 846         DocBook can do more than just links. One can also have lists,
 847         examples, headings, and images. As of version 1.20, the
 848         preferred way is to use a subset of the basic text formatting
 849         syntax called
 850         <ulink url="http://daringfireball.net/projects/markdown/">Markdown</ulink>.
 851         On older GTK-Doc versions any documentation that includes
 852         Markdown will be rendered as is.  For example, list items will
 853         appear as lines starting with a dash.
 854       </para>
 855
 856       <para>
 857         While markdown is now preferred one can mix both. One limitation here is
 858         that one can use docbook xml within markdown, but markdown within
 859         docbook xml is not supported.
 860       </para>
 861
 862       <para>
 863         In older GTK-Doc releases, if you need support for additional
 864         formatting, you would need to enable the usage of docbook
 865         XML tags inside doc-comments by putting <option>--xml-mode</option>
 866         (or <option>--sgml-mode</option>) in the variable
 867         <symbol>MKDB_OPTIONS</symbol> inside <filename>Makefile.am</filename>.
 868       </para>
 869
 870       <para>
 871         <example><title>GTK-Doc comment block using Markdown</title>
 872           <programlisting><![CDATA[
 873 /**
 874  * identifier:
 875  *
 876  * documentation paragraph ...
 877  *
 878  * # Sub Heading #
 879  *
 880  * ## Second Sub Heading
 881  *
 882  * # Sub Heading With a Link Anchor # {#heading-two}
 883  *
 884  * more documentation:
 885  *
 886  * - list item 1
 887  *
 888  *   Paragraph inside a list item.
 889  *
 890  * - list item 2
 891  *
 892  * 1. numbered list item
 893  *
 894  * 2. another numbered list item
 895  *
 896  * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)
 897  *
 898  * ![an inline image](plot-result.png)
 899  *
 900  * [A link to the heading anchor above][heading-two]
 901  *
 902  * A C-language example:
 903  * |[<!-- language="C" -->
 904  * GtkWidget *label = gtk_label_new ("Gorgeous!");
 905  * ]|
 906  */
 907 ]]></programlisting>
 908         </example>
 909       </para>
 910
 911       <para>
 912         More examples of what markdown tags are supported can be found in the
 913         <ulink url="https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown">GTK+ Documentation Markdown Syntax Reference</ulink>.
 914       </para>
 915
 916       <tip>
 917         <para>
 918           As already mentioned earlier GTK-Doc is for documenting public API. Thus
 919           one cannot write documentation for static symbols. Nevertheless it is good
 920           to comment those symbols too. This helps other to understand you code.
 921           Therefore we recommend to comment these using normal comments (without the
 922           2nd '*' in the first line).
 923           If later the function needs to be made public, all one needs to do is to
 924           add another '*' in the comment block and insert the symbol name at the
 925           right place inside the sections file.
 926         </para>
 927       </tip>
 928     </sect1>
 929
 930     <sect1 id="documenting_sections">
 931       <title>Documenting sections</title>
 932
 933       <para>
 934         Each section of the documentation contains information about one class
 935         or module. To introduce the component one can write a section block.
 936         The short description is also used inside the table of contents.
 937         All the @fields are optional.
 938       </para>
 939
 940       <para>
 941         <example><title>Section comment block</title>
 942           <programlisting><![CDATA[
 943 /**
 944  * SECTION:meepapp
 945  * @short_description: the application class
 946  * @title: Meep application
 947  * @section_id:
 948  * @see_also: #MeepSettings
 949  * @stability: Stable
 950  * @include: meep/app.h
 951  * @image: application.png
 952  *
 953  * The application class handles ...
 954  */
 955 ]]></programlisting>
 956         </example>
 957       </para>
 958
 959       <variablelist>
 960         <varlistentry>
 961           <term>SECTION:&lt;name&gt;</term>
 962           <listitem>
 963             <para>
 964               The name links the section documentation to the respective part in
 965               the <filename>&lt;package&gt;-sections.txt</filename> file. The
 966               name give here should match the &lt;FILE&gt; tag in the
 967               <filename>&lt;package&gt;-sections.txt</filename> file.
 968             </para>
 969           </listitem>
 970         </varlistentry>
 971         <varlistentry>
 972           <term>@short_description</term>
 973           <listitem>
 974             <para>
 975               A one line description of the section, that later will appear after
 976               the links in the TOC and at the top of the section page.
 977             </para>
 978           </listitem>
 979         </varlistentry>
 980         <varlistentry>
 981           <term>@title</term>
 982           <listitem>
 983             <para>
 984               The section title defaults to &lt;name&gt; from the SECTION
 985               declaration. It can be overridden with the @title field.
 986             </para>
 987           </listitem>
 988         </varlistentry>
 989         <varlistentry>
 990           <term>@section_id</term>
 991           <listitem>
 992             <para>
 993               Overrides the use of title as a section identifier. For GObjects
 994               the &lt;title&gt; is used as a section_id and for other sections
 995               it is &lt;MODULE&gt;-&lt;title&gt;.
 996             </para>
 997           </listitem>
 998         </varlistentry>
 999         <varlistentry>
1000           <term>@see_also</term>
1001           <listitem>
1002             <para>
1003               A list of symbols that are related to this section.
1004             </para>
1005           </listitem>
1006         </varlistentry>
1007         <varlistentry>
1008           <term>@stability</term>
1009           <listitem>
1010             <para>
1011               An informal description of the stability level this API has.
1012               We recommend the use of one of these terms:
1013               <itemizedlist>
1014                 <listitem>
1015                   <para>
1016                     Stable
1017                     - The intention of a Stable interface is to enable arbitrary
1018                     third parties to develop applications to these interfaces,
1019                     release them, and have confidence that they will run on all
1020                     minor releases of the product (after the one in which the
1021                     interface was introduced, and within the same major release).
1022                     Even at a major release, incompatible changes are expected
1023                     to be rare, and to have strong justifications.
1024                   </para>
1025                 </listitem>
1026                 <listitem>
1027                   <para>
1028                     Unstable
1029                     - Unstable interfaces are experimental or transitional.
1030                     They are typically used to give outside developers early
1031                     access to new or rapidly changing technology, or to provide
1032                     an interim solution to a problem where a more general
1033                     solution is anticipated.
1034                     No claims are made about either source or binary
1035                     compatibility from one minor release to the next.
1036                   </para>
1037                 </listitem>
1038                 <listitem>
1039                   <para>
1040                     Private
1041                     - An interface that can be used within the GNOME stack
1042                     itself, but that is not documented for end-users. Such
1043                     functions should only be used in specified and documented
1044                     ways.
1045                   </para>
1046                 </listitem>
1047                 <listitem>
1048                   <para>
1049                     Internal
1050                     - An interface that is internal to a module and does not
1051                     require end-user documentation. Functions that are
1052                     undocumented are assumed to be Internal.
1053                   </para>
1054                 </listitem>
1055               </itemizedlist>
1056             </para>
1057           </listitem>
1058         </varlistentry>
1059         <varlistentry>
1060           <term>@include</term>
1061           <listitem>
1062             <para>
1063               The <literal>#include</literal> files to show in the section
1064               synopsis (a comma separated list), overriding the global
1065               value from the <link linkend="metafiles_sections">section
1066               file</link> or command line.  This item is optional.
1067             </para>
1068           </listitem>
1069         </varlistentry>
1070         <varlistentry>
1071           <term>@image</term>
1072           <listitem>
1073             <para>
1074               The image to display at the top of the reference page for this
1075               section.  This will often be some sort of a diagram to illustrate
1076               the visual appearance of a class or a diagram of its relationship
1077               to other classes.  This item is optional.
1078             </para>
1079           </listitem>
1080         </varlistentry>
1081       </variablelist>
1082
1083       <tip>
1084         <para>
1085           To avoid unnecessary recompilation after doc-changes put the section
1086           docs into the c-source where possible.
1087         </para>
1088       </tip>
1089
1090     </sect1>
1091
1092     <sect1 id="documenting_symbols">
1093       <title>Documenting symbols</title>
1094
1095       <para>
1096         Each symbol (function, macro, struct, enum, signal and property) is
1097         documented in a separate block. The block is best placed close to the
1098         definition of the symbols so that it is easy to keep them in sync.
1099         Thus functions are usually documented in the c-source and macros,
1100         structs and enums in the header file.
1101       </para>
1102
1103       <sect2><title>General tags</title>
1104
1105         <para>
1106           You can add versioning information to all documentation elements to tell
1107           when an API was introduced, or when it was deprecated.
1108         </para>
1109
1110         <variablelist><title>Versioning Tags</title>
1111           <varlistentry><term>Since:</term>
1112             <listitem>
1113               <para>
1114                 Description since which version of the code the API is available.
1115               </para>
1116             </listitem>
1117           </varlistentry>
1118           <varlistentry><term>Deprecated:</term>
1119             <listitem>
1120               <para>
1121                 Paragraph denoting that this function should no be used anymore.
1122                 The description should point the reader to the new API.
1123               </para>
1124             </listitem>
1125           </varlistentry>
1126         </variablelist>
1127
1128         <para>
1129           You can also add stability information to all documentation elements
1130           to indicate whether API stability is guaranteed for them for all
1131           future minor releases of the project.
1132         </para>
1133
1134         <para>
1135           The default stability level for all documentation elements can be set
1136           by passing the <option>--default-stability</option> argument to
1137           <application>gtkdoc-mkdb</application> with one of the values below.
1138         </para>
1139
1140         <variablelist><title>Stability Tags</title>
1141           <varlistentry><term>Stability: Stable</term>
1142             <listitem>
1143               <para>
1144                 Mark the element as stable. This is for public APIs which are
1145                 guaranteed to remain stable for all future minor releases of the
1146                 project.
1147               </para>
1148             </listitem>
1149           </varlistentry>
1150           <varlistentry><term>Stability: Unstable</term>
1151             <listitem>
1152               <para>
1153                 Mark the element as unstable. This is for public APIs which are
1154                 released as a preview before being stabilised.
1155               </para>
1156             </listitem>
1157           </varlistentry>
1158           <varlistentry><term>Stability: Private</term>
1159             <listitem>
1160               <para>
1161                 Mark the element as private. This is for interfaces which can be
1162                 used by tightly coupled modules, but not by arbitrary third
1163                 parties.
1164               </para>
1165             </listitem>
1166           </varlistentry>
1167         </variablelist>
1168
1169         <example><title>General tags</title>
1170           <programlisting><![CDATA[
1171 /**
1172  * foo_get_bar:
1173  * @foo: some foo
1174  *
1175  * Retrieves @foo's bar.
1176  *
1177  * Returns: @foo's bar
1178  *
1179  * Since: 2.6
1180  * Deprecated: 2.12: Use foo_baz_get_bar() instead.
1181  */
1182 Bar *
1183 foo_get_bar(Foo *foo)
1184 {
1185 ...
1186 ]]></programlisting>
1187         </example>
1188       </sect2>
1189
1190       <sect2><title>Annotations</title>
1191
1192         <para>
1193           Documentation blocks can contain annotation-tags. These tags will be
1194           rendered with tooltips describing their meaning. The tags are used by
1195           gobject-introspection to generate language bindings. A detailed list
1196           of the supported tags can be found on
1197           <ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">the wiki</ulink>.
1198         </para>
1199
1200         <example><title>Annotations</title>
1201           <programlisting><![CDATA[
1202 /**
1203  * foo_get_bar: (annotation)
1204  * @foo: (annotation): some foo
1205  *
1206  * Retrieves @foo's bar.
1207  *
1208  * Returns: (annotation): @foo's bar
1209  */
1210 ...
1211 /**
1212  * foo_set_bar_using_the_frobnicator: (annotation) (another annotation)
1213  *                                    (and another annotation)
1214  * @foo: (annotation) (another annotation): some foo
1215  *
1216  * Sets bar on @foo.
1217  */
1218 ]]></programlisting>
1219         </example>
1220       </sect2>
1221
1222       <sect2><title>Function comment block</title>
1223
1224         <para>
1225           Please remember to:
1226           <itemizedlist>
1227             <listitem>
1228               <para>
1229                 Document whether returned objects, lists, strings, etc, should be
1230                 freed/unrefed/released.
1231               </para>
1232             </listitem>
1233             <listitem>
1234               <para>
1235                 Document whether parameters can be NULL, and what happens if they are.
1236               </para>
1237             </listitem>
1238             <listitem>
1239               <para>
1240                 Mention interesting pre-conditions and post-conditions where appropriate.
1241               </para>
1242             </listitem>
1243           </itemizedlist>
1244         </para>
1245
1246         <para>
1247           Gtk-doc assumes all symbols (macros, functions) starting with '_' are
1248           private. They are treated like static functions.
1249         </para>
1250
1251         <example><title>Function comment block</title>
1252           <programlisting><![CDATA[
1253 /**
1254  * function_name:
1255  * @par1:  description of parameter 1. These can extend over more than
1256  * one line.
1257  * @par2:  description of parameter 2
1258  * @...: a %NULL-terminated list of bars
1259  *
1260  * The function description goes here. You can use @par1 to refer to parameters
1261  * so that they are highlighted in the output. You can also use %constant
1262  * for constants, function_name2() for functions and #GtkWidget for links to
1263  * other declarations (which may be documented elsewhere).
1264  *
1265  * Returns: an integer.
1266  *
1267  * Since: 2.2
1268  * Deprecated: 2.18: Use other_function() instead.
1269  */
1270 ]]></programlisting>
1271         </example>
1272
1273         <variablelist><title>Function tags</title>
1274           <varlistentry><term>Returns:</term>
1275             <listitem>
1276               <para>
1277                 Paragraph describing the returned result.
1278               </para>
1279             </listitem>
1280           </varlistentry>
1281           <varlistentry><term>@...:</term>
1282             <listitem>
1283               <para>
1284                 In case the function has variadic arguments, you should use this
1285                 tag (@Varargs: does also work for historic reasons).
1286               </para>
1287             </listitem>
1288           </varlistentry>
1289         </variablelist>
1290
1291       </sect2>
1292
1293       <sect2><title>Property comment block</title>
1294
1295         <example><title>Property comment block</title>
1296           <programlisting><![CDATA[
1297 /**
1298  * SomeWidget:some-property:
1299  *
1300  * Here you can document a property.
1301  */
1302 g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
1303 ]]></programlisting>
1304         </example>
1305
1306       </sect2>
1307
1308       <sect2><title>Signal comment block</title>
1309
1310         <para>
1311           Please remember to:
1312           <itemizedlist>
1313             <listitem>
1314               <para>
1315                 Document when the signal is emitted and whether it is emitted before
1316                 or after other signals.
1317               </para>
1318             </listitem>
1319             <listitem>
1320               <para>
1321                 Document what an application might do in the signal handler.
1322               </para>
1323             </listitem>
1324           </itemizedlist>
1325         </para>
1326
1327         <example><title>Signal comment block</title>
1328           <programlisting><![CDATA[
1329 /**
1330  * FooWidget::foobarized:
1331  * @widget: the widget that received the signal
1332  * @foo: some foo
1333  * @bar: some bar
1334  *
1335  * The ::foobarized signal is emitted each time someone tries to foobarize @widget.
1336  */
1337 foo_signals[FOOBARIZE] =
1338   g_signal_new ("foobarize",
1339                 ...
1340 ]]></programlisting>
1341         </example>
1342
1343       </sect2>
1344
1345       <sect2><title>Struct comment block</title>
1346         <example><title>Struct comment block</title>
1347           <programlisting><![CDATA[
1348 /**
1349  * FooWidget:
1350  * @bar: some #gboolean
1351  *
1352  * This is the best widget, ever.
1353  */
1354 typedef struct _FooWidget {
1355   GtkWidget parent_instance;
1356
1357   gboolean bar;
1358 } FooWidget;
1359 ]]></programlisting>
1360         </example>
1361
1362         <para>
1363           Use <code>/*&lt; private &gt;*/</code> before the private struct fields
1364           you want to hide. Use <code>/*&lt; public &gt;*/</code> for the reverse
1365           behaviour.
1366         </para>
1367
1368         <para>
1369           If the first field is "g_iface", "parent_instance" or "parent_class"
1370           it will be considered private automatically and doesn't need to be
1371           mentioned in the comment block.
1372         </para>
1373
1374         <para>
1375           Struct comment blocks can also be used for GObjects and GObjectClasses.
1376           It is usually a good idea to add a comment block for a class, if it has
1377           vmethods (as this is how they can be documented). For the GObject
1378           itself one can use the related section docs, having a separate block
1379           for the instance struct would be useful if the instance has public
1380           fields. One disadvantage here is that this creates two index entries
1381           of the same name (the structure and the section).
1382         </para>
1383
1384       </sect2>
1385
1386       <sect2><title>Enum comment block</title>
1387         <example><title>Enum comment block</title>
1388           <programlisting><![CDATA[
1389 /**
1390  * Something:
1391  * @SOMETHING_FOO: something foo
1392  * @SOMETHING_BAR: something bar
1393  *
1394  * Enum values used for the thing, to specify the thing.
1395  */
1396 typedef enum {
1397   SOMETHING_FOO,
1398   SOMETHING_BAR,
1399   /*< private >*/
1400   SOMETHING_COUNT
1401 } Something;
1402 ]]></programlisting>
1403         </example>
1404
1405         <para>
1406           Use <code>/*&lt; private &gt;*/</code> before the private enum values
1407           you want to hide. Use <code>/*&lt; public &gt;*/</code> for the reverse
1408           behaviour.
1409         </para>
1410
1411       </sect2>
1412     </sect1>
1413
1414     <sect1 id="documenting_docbook">
1415       <title>Useful DocBook tags</title>
1416
1417       <para>
1418         Here are some DocBook tags which are most useful when documenting the
1419         code.
1420       </para>
1421
1422       <para>
1423         To link to another section in the GTK docs:
1424
1425         <informalexample>
1426           <programlisting><![CDATA[
1427 <link linkend="glib-Hash-Tables">Hash Tables</link>
1428 ]]></programlisting>
1429         </informalexample>
1430         The linkend is the SGML/XML id on the top item of the page you want to link to.
1431         For most pages this is currently the part ("gtk", "gdk", "glib") and then
1432         the page title ("Hash Tables"). For widgets it is just the class name.
1433         Spaces and underscores are converted to '-' to conform to SGML/XML.
1434       </para>
1435
1436       <para>
1437         To refer to an external function, e.g. a standard C function:
1438         <informalexample>
1439           <programlisting><![CDATA[
1440 <function>...</function>
1441 ]]></programlisting>
1442         </informalexample>
1443       </para>
1444
1445       <para>
1446         To include example code:
1447         <informalexample>
1448           <programlisting><![CDATA[
1449 <example>
1450   <title>Using a GHashTable.</title>
1451   <programlisting>
1452       ...
1453   </programlisting>
1454 </example>
1455 ]]></programlisting>
1456         </informalexample>
1457         or possibly this, for very short code fragments which don't need a title:
1458         <informalexample>
1459           <programlisting><![CDATA[
1460 <informalexample>
1461   <programlisting>
1462   ...
1463   </programlisting>
1464 </informalexample>
1465 ]]></programlisting>
1466         </informalexample>
1467         For the latter GTK-Doc also supports an abbreviation:
1468 <![CDATA[
1469 |[
1470   ...
1471 ]|
1472 ]]>
1473       </para>
1474
1475       <para>
1476         To include bulleted lists:
1477         <informalexample>
1478           <programlisting><![CDATA[
1479 <itemizedlist>
1480   <listitem>
1481     <para>
1482       ...
1483     </para>
1484   </listitem>
1485   <listitem>
1486     <para>
1487       ...
1488     </para>
1489   </listitem>
1490 </itemizedlist>
1491 ]]></programlisting>
1492         </informalexample>
1493       </para>
1494
1495       <para>
1496         To include a note which stands out from the text:
1497         <informalexample>
1498           <programlisting><![CDATA[
1499 <note>
1500   <para>
1501     Make sure you free the data after use.
1502   </para>
1503 </note>
1504 ]]></programlisting>
1505         </informalexample>
1506       </para>
1507
1508       <para>
1509         To refer to a type:
1510         <informalexample>
1511           <programlisting><![CDATA[
1512 <type>unsigned char</type>
1513 ]]></programlisting>
1514         </informalexample>
1515       </para>
1516
1517       <para>
1518         To refer to an external structure (not one described in the GTK docs):
1519         <informalexample>
1520           <programlisting><![CDATA[
1521 <structname>XFontStruct</structname>
1522 ]]></programlisting>
1523         </informalexample>
1524       </para>
1525
1526       <para>
1527         To refer to a field of a structure:
1528         <informalexample>
1529           <programlisting><![CDATA[
1530 <structfield>len</structfield>
1531 ]]></programlisting>
1532         </informalexample>
1533       </para>
1534
1535       <para>
1536         To refer to a class name, we could possibly use:
1537         <informalexample>
1538           <programlisting><![CDATA[
1539 <classname>GtkWidget</classname>
1540 ]]></programlisting>
1541         </informalexample>
1542         but you'll probably be using #GtkWidget instead (to automatically create
1543         a link to the GtkWidget page - see <link linkend="documenting_syntax">the abbreviations</link>).
1544       </para>
1545
1546       <para>
1547         To emphasize text:
1548         <informalexample>
1549           <programlisting><![CDATA[
1550 <emphasis>This is important</emphasis>
1551 ]]></programlisting>
1552         </informalexample>
1553       </para>
1554
1555       <para>
1556         For filenames use:
1557         <informalexample>
1558           <programlisting><![CDATA[
1559 <filename>/home/user/documents</filename>
1560 ]]></programlisting>
1561         </informalexample>
1562       </para>
1563
1564       <para>
1565         To refer to keys use:
1566         <informalexample>
1567           <programlisting><![CDATA[
1568 <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>
1569 ]]></programlisting>
1570         </informalexample>
1571       </para>
1572
1573     </sect1>
1574   </chapter>
1575
1576   <chapter id="metafiles">
1577     <title>Filling the extra files</title>
1578
1579     <para>
1580       There are a couple of extra files, that need to be maintained along with
1581       the inline source code comments:
1582       <filename>&lt;package&gt;.types</filename>,
1583       <filename>&lt;package&gt;-docs.xml</filename> (in the past .sgml),
1584       <filename>&lt;package&gt;-sections.txt</filename>.
1585     </para>
1586
1587     <sect1 id="metafiles_types">
1588       <title>Editing the types file</title>
1589
1590       <para>
1591         If your library or application includes GObjects, you want
1592         their signals, arguments/parameters and position in the hierarchy to be
1593         shown in the documentation. All you need to do, is to list the
1594         <function>xxx_get_type</function> functions together with their include
1595         inside the <filename>&lt;package&gt;.types</filename> file.
1596       </para>
1597
1598       <para>
1599         <example><title>Example types file snippet</title>
1600           <programlisting><![CDATA[
1601 #include <gtk/gtk.h>
1602
1603 gtk_accel_label_get_type
1604 gtk_adjustment_get_type
1605 gtk_alignment_get_type
1606 gtk_arrow_get_type
1607 ]]></programlisting>
1608         </example>
1609       </para>
1610
1611       <para>
1612         Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this list for you.
1613         Just add "--rebuild-types" to SCAN_OPTIONS in <filename>Makefile.am</filename>. If you
1614         use this approach you should not dist the types file nor have it under version control.
1615       </para>
1616
1617     </sect1>
1618
1619     <sect1 id="metafiles_master">
1620       <title>Editing the master document</title>
1621
1622       <para>
1623         GTK-Doc produces documentation in DocBook SGML/XML. When processing the
1624         inline source comments, the GTK-Doc tools generate one documentation
1625         page per class or module as a separate file. The master document
1626         includes them and place them in an order.
1627       </para>
1628
1629       <para>
1630         While GTK-Doc creates a template master document for you, later runs will
1631         not touch it again. This means that one can freely structure the
1632         documentation. That includes grouping pages and adding extra pages.
1633         GTK-Doc has now a test suite, where also the master-document is recreated from scratch.
1634         Its a good idea to look at this from time to time to see if there are
1635         some new goodies introduced there.
1636       </para>
1637
1638       <tip>
1639         <para>
1640           Do not create tutorials as extra documents. Just write extra chapters.
1641           The benefit of directly embedding the tutorial for your library into
1642           the API documentation is that it is easy to link for the tutorial to
1643           symbol documentation. Apart chances are higher that the tutorial gets
1644           updates along with the library.
1645         </para>
1646       </tip>
1647
1648       <para>
1649         So what are the things to change inside the master document? For a start
1650         is only a little. There are some placeholders (text in square brackets)
1651         there which you should take care of.
1652       </para>
1653
1654       <para>
1655         <example><title>Master document header</title>
1656           <programlisting><![CDATA[
1657 <bookinfo>
1658   <title>MODULENAME Reference Manual</title>
1659   <releaseinfo>
1660     for MODULENAME [VERSION]
1661     The latest version of this documentation can be found on-line at
1662     <ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html">http://[SERVER]/MODULENAME/</ulink>.
1663   </releaseinfo>
1664 </bookinfo>
1665
1666 <chapter>
1667   <title>[Insert title here]</title>
1668 ]]></programlisting>
1669         </example>
1670       </para>
1671
1672       <para>
1673         In addition a few option elements are created in commented form. You can
1674         review these and enable them as you like.
1675       </para>
1676
1677       <para>
1678         <example><title>Optional part in the master document</title>
1679           <programlisting><![CDATA[
1680   <!-- enable this when you use gobject introspection annotations
1681   <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
1682   -->
1683 ]]></programlisting>
1684         </example>
1685       </para>
1686
1687       <para>
1688         Finally you need to add new section whenever you introduce one. The
1689         <link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> tool will
1690         remind you of newly generated xml files that are not yet included into
1691         the doc.
1692       </para>
1693
1694       <para>
1695         <example><title>Including generated sections</title>
1696           <programlisting><![CDATA[
1697   <chapter>
1698     <title>my library</title>
1699       <xi:include href="xml/object.xml"/>
1700       ...
1701 ]]></programlisting>
1702         </example>
1703       </para>
1704
1705     </sect1>
1706
1707     <sect1 id="metafiles_sections">
1708       <title>Editing the section file</title>
1709
1710       <para>
1711         The section file is used to organise the documentation output by
1712         GTK-Doc. Here one specifies which symbol belongs to which module or
1713         class and control the visibility (public or private).
1714       </para>
1715
1716       <para>
1717         The section file is a plain text file with tags delimiting sections.
1718         Blank lines are ignored and lines starting with a '#' are treated as
1719         comment lines.
1720       </para>
1721
1722       <note>
1723         <para>
1724           While the tags make the file look like xml, it is not. Please do not
1725           close tags like &lt;SUBSECTION&gt;.
1726         </para>
1727       </note>
1728
1729       <para>
1730         <example><title>Including generated sections</title>
1731           <programlisting><![CDATA[
1732 <INCLUDE>libmeep/meep.h</INCLUDE>
1733
1734 <SECTION>
1735 <FILE>meepapp</FILE>
1736 <TITLE>MeepApp</TITLE>
1737 MeepApp
1738 <SUBSECTION Standard>
1739 MEEP_APP
1740 ...
1741 MeepAppClass
1742 meep_app_get_type
1743 </SECTION>
1744 ]]></programlisting>
1745         </example>
1746       </para>
1747
1748       <para>
1749         The &lt;FILE&gt; ... &lt;/FILE&gt; tag is used to specify the file name,
1750         without any suffix. For example, using '&lt;FILE&gt;gnome-config&lt;/FILE&gt;'
1751         will result in the section declarations being output in the template
1752         file <filename>tmpl/gnome-config.sgml</filename>, which will be
1753         converted into the DocBook XML file <filename>xml/gnome-config.sgml</filename>
1754         or the DocBook XML file <filename>xml/gnome-config.xml</filename>.
1755         (The name of the HTML file is based on the module name and the section
1756         title, or for GObjects it is based on the GObjects class name converted
1757         to lower case).
1758       </para>
1759
1760       <para>
1761         The &lt;TITLE&gt; ... &lt;/TITLE&gt; tag is used to specify the title of
1762         the section. It is only useful before the templates (if used) are
1763         initially created, since the title set in the template file overrides
1764         this. Also if one uses SECTION comment in the sources, this is obsolete.
1765       </para>
1766
1767       <para>
1768         You can group items in the section by using the &lt;SUBSECTION&gt; tag.
1769         Currently it outputs a blank line between subsections in the synopsis
1770         section.
1771         You can also use &lt;SUBSECTION Standard&gt; for standard GObject
1772         declarations (e.g. the functions like g_object_get_type and macros like
1773         G_OBJECT(), G_IS_OBJECT() etc.).
1774         Currently these are left out of the documentation.
1775         You can also use &lt;SUBSECTION Private&gt; for private declarations
1776         which will not be output (it is a handy way to avoid warning messages
1777         about unused declarations).
1778         If your library contains private types which you don't want to appear in
1779         the object hierarchy and the list of implemented or required interfaces,
1780         add them to a Private subsection.
1781         Whether you would place GObject and GObjectClass like structs in public
1782         or Standard section depends if they have public entries (variables,
1783         vmethods).
1784       </para>
1785
1786       <para>
1787         You can also use &lt;INCLUDE&gt; ... &lt;/INCLUDE&gt; to specify the
1788         #include files which are shown in the synopsis sections.
1789         It contains a comma-separate list of #include files, without the angle
1790         brackets. If you set it outside of any sections, it acts for all
1791         sections until the end of the file. If you set it within a section, it
1792         only applies to that section.
1793       </para>
1794
1795     </sect1>
1796
1797   </chapter>
1798
1799   <chapter id="reports">
1800     <title>Controlling the result</title>
1801
1802     <para>
1803       A GTK-Doc run generates report files inside the documentation directory.
1804       The generated files are named:
1805       <filename>&lt;package&gt;-undocumented.txt</filename>,
1806       <filename>&lt;package&gt;-undeclared.txt</filename> and
1807       <filename>&lt;package&gt;-unused.txt</filename>.
1808       All those are plain text files that can be viewed and postprocessed easily.
1809     </para>
1810
1811     <para>
1812       The <filename>&lt;package&gt;-undocumented.txt</filename> file starts with
1813       the documentation coverage summary. Below are two sections divided by
1814       blank lines. The first section lists undocumented or incomplete symbols.
1815       The second section does the same for section docs. Incomplete entries are
1816       those, which have documentation, but where e.g. a new parameter has been
1817       added.
1818     </para>
1819
1820     <para>
1821       The <filename>&lt;package&gt;-undeclared.txt</filename> file lists symbols
1822       given in the <filename>&lt;package&gt;-sections.txt</filename> but not
1823       found in the sources. Check if they have been removed or if they are
1824       misspelled.
1825     </para>
1826
1827     <para>
1828       The <filename>&lt;package&gt;-unused.txt</filename> file lists symbol
1829       names, where the GTK-Doc scanner has found documentation, but does not
1830       know where to put it. This means that the symbol has not yet been added to
1831       the <filename>&lt;package&gt;-sections.txt</filename> file.
1832     </para>
1833
1834     <tip>
1835       <para>
1836         Enable or add the <option>TESTS=$(GTKDOC_CHECK)</option> line in Makefile.am.
1837         If at least GTK-Doc 1.9 is installed, this will run sanity checks during
1838         <command>make check</command> run.
1839       </para>
1840     </tip>
1841
1842     <para>
1843       One can also look at the files produced by the source code scanner:
1844       <filename>&lt;package&gt;-decl-list.txt</filename> and
1845       <filename>&lt;package&gt;-decl.txt</filename>. The first one can be
1846       compared with the section file if that is manually maintained. The second
1847       lists all declarations from the headers. If a symbol is missing one could
1848       check if this file contains it.
1849     </para>
1850
1851     <para>
1852       If the project is GObject based, one can also look into the files produced
1853       by the object scanner:
1854       <filename>&lt;package&gt;.args.txt</filename>,
1855       <filename>&lt;package&gt;.hierarchy.txt</filename>,
1856       <filename>&lt;package&gt;.interfaces.txt</filename>,
1857       <filename>&lt;package&gt;.prerequisites.txt</filename> and
1858       <filename>&lt;package&gt;.signals.txt</filename>. If there are missing
1859       symbols in any of those, one can ask GTK-Doc to keep the intermediate
1860       scanner file for further analysis, by running it as
1861       <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
1862     </para>
1863   </chapter>
1864
1865   <chapter id="modernizing">
1866     <title>Modernizing the documentation</title>
1867
1868     <para>
1869       GTK-Doc has been around for quite some time. In this section we list new
1870       features together with the version since when it is available.
1871     </para>
1872
1873     <sect1 id="modernizing-gtk-doc-1-9">
1874       <title>GTK-Doc 1.9</title>
1875
1876       <para>
1877         When using xml instead of sgml, one can actually name the master
1878         document <filename>&lt;package&gt;-docs.xml</filename>.
1879       </para>
1880
1881       <para>
1882         This version supports <option>SCAN_OPTIONS=--rebuild-sections</option>
1883         in <filename>Makefile.am</filename>. When this is enabled, the
1884         <filename>&lt;package&gt;-sections.txt</filename> is autogenerated and
1885         can be removed from the vcs. This only works nicely for projects that
1886         have a very regular structure (e.g. each .{c,h} pair will create new
1887         section). If one organize a project close to that updating a manually
1888         maintained section file can be as simple as running
1889         <code>meld &lt;package&gt;-decl-list.txt &lt;package&gt;-sections.txt</code>.
1890       </para>
1891
1892       <para>
1893         Version 1.8 already introduced the syntax for documenting sections in
1894         the sources instead of the separate files under <filename class='directory'>tmpl</filename>.
1895         This version adds options to switch the whole doc module to not use the
1896         extra tmpl build step at all, by using <option>--flavour no-tmpl</option>
1897         in <filename>configure.ac</filename>. If you don't have a <filename class='directory'>tmpl</filename>
1898         checked into you source control system and haven't yet switched, just
1899         add the flag to <filename>configure.ac</filename> and you are done.
1900       </para>
1901     </sect1>
1902
1903     <sect1 id="modernizing-gtk-doc-1-10">
1904       <title>GTK-Doc 1.10</title>
1905
1906       <para>
1907         This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in
1908         <filename>Makefile.am</filename>. When this is enabled, the
1909         <filename>&lt;package&gt;.types</filename> is autogenerated and can be
1910         removed from the vcs. When using this feature it is important to also
1911         setup the <varname>IGNORE_HFILES</varname> in
1912         <filename>Makefile.am</filename> for code that is build conditionally.
1913       </para>
1914     </sect1>
1915
1916     <sect1 id="modernizing-gtk-doc-1-16">
1917       <title>GTK-Doc 1.16</title>
1918
1919       <para>
1920         This version includes a new tool called gtkdoc-check. This tool can run
1921         a set of sanity checks on your documentation. It is enabled by adding
1922         these lines to the end of <filename>Makefile.am</filename>.
1923         <example><title>Enable gtkdoc-check</title>
1924           <programlisting><![CDATA[
1925 if ENABLE_GTK_DOC
1926 TESTS_ENVIRONMENT = \
1927   DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
1928   SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
1929 TESTS = $(GTKDOC_CHECK)
1930 endif
1931 ]]></programlisting>
1932         </example>
1933       </para>
1934     </sect1>
1935
1936     <sect1 id="modernizing-gtk-doc-1-20">
1937       <title>GTK-Doc 1.20</title>
1938
1939       <para>
1940         Version 1.18 brought some initial markdown support. Using markdown in
1941         doc comments is less intrusive than writing docbook xml. This version
1942         improves a lot on this and add a lot more styles. The section that
1943         explains the <link linkend="documenting_syntax">comment syntax</link>
1944         has all the details.
1945       </para>
1946     </sect1>
1947
1948     <sect1 id="modernizing-gtk-doc-1-25">
1949       <title>GTK-Doc 1.25</title>
1950
1951       <para>
1952         The makefiles shipped with this version generate an entity file at <filename>xml/gtkdocentities.ent</filename>,
1953         containing entities for e.g. package_name and package_version. You can
1954         use this e.g. in the main xml file to avoid hardcoding the version
1955         number. Below is any example that shows how the entity file is included
1956         and how the entities are used. The entities can also be used in all
1957         generated files, GTK-Doc will use the same xml header in generated xml
1958         files.
1959         <example><title>Use pre-generated entities</title>
1960           <programlisting><![CDATA[
1961 <?xml version="1.0"?>
1962 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
1963                "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
1964 [
1965   <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
1966   <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
1967   %gtkdocentities;
1968 ]>
1969 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
1970   <bookinfo>
1971     <title>&package_name; Reference Manual</title>
1972     <releaseinfo>
1973       for &package_string;.
1974       The latest version of this documentation can be found on-line at
1975       <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
1976     </releaseinfo>
1977   </bookinfo>
1978 ]]></programlisting>
1979         </example>
1980       </para>
1981     </sect1>
1982   </chapter>
1983
1984   <chapter id="documenting-others">
1985     <title>Documenting other interfaces</title>
1986
1987     <para>
1988       So far we have been using GTK-Doc to document the API of code. The next
1989       sections contain suggestions how the tools can be used to document other
1990       interfaces too.
1991     </para>
1992
1993     <sect1 id="commandline-interfaces">
1994       <title>Command line options and man pages</title>
1995
1996       <para>
1997         As one can generate man pages for a docbook refentry as well, it sounds
1998         like a good idea to use it for that purpose. This way the interface is
1999         part of the reference and one gets the man-page for free.
2000       </para>
2001
2002       <sect2 id="commandline-interfaces-file">
2003         <title>Document the tool</title>
2004
2005         <para>
2006           Create one refentry file per tool. Following
2007           <link linkend="settingup_docfiles">our example</link> we would call it
2008           <filename>meep/docs/reference/meeper/meep.xml</filename>. For the xml
2009           tags that should be used and can look at generated file in the xml
2010           subdirectory as well as examples e.g. in glib.
2011         </para>
2012       </sect2>
2013
2014       <sect2 id="commandline-interfaces-configure">
2015         <title>Adding the extra configure check</title>
2016
2017         <para>
2018           <example><title>Extra configure checks</title>
2019             <programlisting><![CDATA[
2020 AC_ARG_ENABLE(man,
2021               [AC_HELP_STRING([--enable-man],
2022                               [regenerate man pages from Docbook [default=no]])],enable_man=yes,
2023               enable_man=no)
2024
2025 AC_PATH_PROG([XSLTPROC], [xsltproc])
2026 AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)
2027 ]]></programlisting>
2028           </example>
2029         </para>
2030       </sect2>
2031
2032       <sect2 id="commandline-interfaces-make">
2033         <title>Adding the extra makefile rules</title>
2034
2035         <para>
2036           <example><title>Extra configure checks</title>
2037             <programlisting><![CDATA[
2038 man_MANS = \
2039        meeper.1
2040
2041 if ENABLE_GTK_DOC
2042 if ENABLE_MAN
2043
2044 %.1 : %.xml
2045         @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
2046
2047 endif
2048 endif
2049
2050 BUILT_EXTRA_DIST = $(man_MANS)
2051 EXTRA_DIST += meep.xml
2052 ]]></programlisting>
2053           </example>
2054         </para>
2055       </sect2>
2056     </sect1>
2057
2058     <sect1 id="dbus-interfaces">
2059       <title>DBus interfaces</title>
2060
2061       <para>
2062         (FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html,
2063 http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)
2064       </para>
2065     </sect1>
2066
2067   </chapter>
2068
2069   <chapter id="faq">
2070     <title>Frequently asked questions</title>
2071
2072     <segmentedlist>
2073       <?dbhtml list-presentation="list"?>
2074       <segtitle>Question</segtitle>
2075       <segtitle>Answer</segtitle>
2076       <seglistitem>
2077         <seg>No class hierarchy.</seg>
2078         <seg>
2079           The objects <function>xxx_get_type()</function> function has not been
2080           entered into the <filename>&lt;package&gt;.types</filename> file.
2081         </seg>
2082       </seglistitem>
2083       <seglistitem>
2084         <seg>Still no class hierarchy.</seg>
2085         <seg>
2086           Missing or wrong naming in <filename>&lt;package&gt;-sections.txt</filename>
2087           file (see <ulink url="http://mail.gnome.org/archives/gtk-doc-list/2003-October/msg00006.html">explanation</ulink>).
2088         </seg>
2089       </seglistitem>
2090       <seglistitem>
2091         <seg>Damn, I have still no class hierarchy.</seg>
2092         <seg>
2093           Is the object name (name of the instance struct, e.g. <type>GtkWidget</type>)
2094           part of the normal section (don't put this into Standard or Private
2095           subsections).
2096         </seg>
2097       </seglistitem>
2098       <seglistitem>
2099         <seg>No symbol index.</seg>
2100         <seg>
2101           Does the <filename>&lt;package&gt;-docs.{xml,sgml}</filename> contain a
2102           index that xi:includes the generated index?
2103         </seg>
2104       </seglistitem>
2105       <seglistitem>
2106         <seg>Symbols are not linked to their doc-section.</seg>
2107         <seg>
2108           Is the doc-comment using the correct markup (added #,% or ())?
2109           Check if the gtkdoc-fixxref warns about unresolvable xrefs.
2110         </seg>
2111       </seglistitem>
2112       <seglistitem>
2113         <seg>A new class does not appear in the docs.</seg>
2114         <seg>
2115           Is the new page xi:included from
2116           <filename>&lt;package&gt;-docs.{xml,sgml}</filename>.
2117         </seg>
2118       </seglistitem>
2119       <seglistitem>
2120         <seg>A new symbol does not appear in the docs.</seg>
2121         <seg>
2122           Is the doc-comment properly formatted. Check for spelling mistakes in
2123           the begin of the comment. Check if the gtkdoc-fixxref warns about
2124           unresolvable xrefs. Check if the symbol is correctly listed in the
2125           <filename>&lt;package&gt;-sections.txt</filename> in a public subsection.
2126         </seg>
2127       </seglistitem>
2128       <seglistitem>
2129         <seg>A type is missing from the class hierarchy.</seg>
2130         <seg>
2131           If the type is listed in <filename>&lt;package&gt;.hierarchy</filename>
2132           but not in <filename>xml/tree_index.sgml</filename> then double check
2133           that the type is correctly placed in the <filename>&lt;package&gt;-sections.txt</filename>.
2134           If the type instance (e.g. <type>GtkWidget</type>) is not listed or
2135           incidentally marked private it will not be shown.
2136         </seg>
2137       </seglistitem>
2138       <seglistitem>
2139         <seg>I get foldoc links for all gobject annotations.</seg>
2140         <seg>
2141           Check that <filename>xml/annotation-glossary.xml</filename> is
2142           xi:included from <filename>&lt;package&gt;-docs.{xml,sgml}</filename>.
2143         </seg>
2144       </seglistitem>
2145
2146       <!-- gtk-doc warnings: -->
2147       <seglistitem>
2148         <seg>Parameter described in source code comment block but does not exist</seg>
2149         <seg>Check if the prototype in the header has different parameter names as in the source.</seg>
2150       </seglistitem>
2151
2152       <!-- docbook warnings: -->
2153       <seglistitem>
2154         <seg>multiple "IDs" for constraint linkend: XYZ</seg>
2155         <seg>Symbol XYZ appears twice in <filename>&lt;package&gt;-sections.txt</filename> file.</seg>
2156       </seglistitem>
2157       <seglistitem>
2158         <seg>Element typename in namespace '' encountered in para, but no template matches.</seg>
2159         <seg />
2160       </seglistitem>
2161     </segmentedlist>
2162   </chapter>
2163
2164   <chapter id="contrib">
2165     <title>Tools related to gtk-doc</title>
2166
2167     <para>
2168       GtkDocPlugin - a <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">Trac GTK-Doc</ulink>
2169       integration plugin, that adds API docs to a trac site and integrates with
2170       the trac search.
2171     </para>
2172     <para>
2173       Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since
2174       tags in the API to determine the minimum required version.
2175     </para>
2176
2177   </chapter>
2178
2179   <!-- ======== Appendix: FDL ================================== -->
2180   &FDL;
2181
2182 </book>
2183