Debian Codegraph @

help/manual/C/index.docbook

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