| blob | ddcebb863ac6430a18fea98b53fb57a52a893359 |
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" [
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.12</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>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, 2007-2009</year>
50 <holder>Dan Mueth and Chris Lyttle and Stefan Kost</holder>
51 </copyright>
53 <!-- translators: uncomment this:
54 <copyright>
55 <year>2000</year>
56 <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
57 </copyright>
58 -->
60 <legalnotice>
61 <para>
62 Permission is granted to copy, distribute and/or modify this
63 document under the terms of the <citetitle>GNU Free Documentation
64 License</citetitle>, Version 1.1 or any later version published
65 by the Free Software Foundation with no Invariant Sections, no
66 Front-Cover Texts, and no Back-Cover Texts. A copy of the license
67 is &FDLlink;.
68 </para>
69 <para>
70 Many of the names used by companies to distinguish their products and
71 services are claimed as trademarks. Where those names appear in any
72 GNOME documentation, and those trademarks are made aware to the members
73 of the GNOME Documentation Project, the names have been printed in caps
74 or initial caps.
75 </para>
76 </legalnotice>
78 <revhistory>
79 <revision>
80 <revnumber>1.15</revnumber>
81 <date>21 May 2010</date>
82 <authorinitials>sk</authorinitials>
83 <revremark>bug and regression fixes</revremark>
84 </revision>
85 <revision>
86 <revnumber>1.14</revnumber>
87 <date>28 March 2010</date>
88 <authorinitials>sk</authorinitials>
89 <revremark>bugfixes and performance improvements</revremark>
90 </revision>
91 <revision>
92 <revnumber>1.13</revnumber>
93 <date>18 December 2009</date>
94 <authorinitials>sk</authorinitials>
95 <revremark>broken tarball update</revremark>
96 </revision>
97 <revision>
98 <revnumber>1.12</revnumber>
99 <date>18 December 2009</date>
100 <authorinitials>sk</authorinitials>
101 <revremark>new tool features and bugfixes</revremark>
102 </revision>
103 <revision>
104 <revnumber>1.11</revnumber>
105 <date>16 Novemebr 2008</date>
106 <authorinitials>mal</authorinitials>
107 <revremark>GNOME doc-utils migration</revremark>
108 </revision>
109 </revhistory>
111 </bookinfo>
113 <!-- ======== Chapter 1: Introduction ======================== -->
115 <chapter id="introduction">
116 <title>Introduction</title>
118 <para>
119 This chapter introduces GTK-Doc and gives an overview of what it is and
120 how it is used.
121 </para>
123 <sect1 id="whatisgtkdoc">
124 <title>What is GTK-Doc?</title>
126 <para>
127 GTK-Doc is used to document C code. It is typically used to document the public
128 API of libraries, such as the GTK+ and GNOME libraries. But it can also be
129 used to document application code.
130 </para>
131 </sect1>
133 <sect1 id="howdoesgtkdocwork">
134 <title>How Does GTK-Doc Work?</title>
136 <para>
137 GTK-Doc works by using documentation of functions placed inside the source files in
138 specially-formatted comment blocks, or documentation added to the template files
139 which GTK-Doc uses (though note that GTK-Doc will only document functions that
140 are declared in header files; it won't produce output for static functions).
141 </para>
143 <para>
144 GTK-Doc consists of a number of perl scripts, each performing a different step
145 in the process.
146 </para>
148 <para>
149 There are 5 main steps in the process:
150 </para>
152 <orderedlist>
154 <listitem>
155 <para>
156 <guilabel>Writing the documentation.</guilabel>
158 The author fills in the source files with the documentation for each
159 function, macro, union etc. (In the past information was entered in
160 generated template files, which is not recommended anymore).
161 </para>
162 </listitem>
164 <listitem>
165 <para>
166 <guilabel>Gathering information about the code.</guilabel>
168 <application>gtkdoc-scan</application> scans the header files of the
169 code looking for declarations of functions, macros, enums, structs, and unions.
170 It creates the file <filename><module>-decl-list.txt</filename> containg a list of the
171 declarations, placing them into sections according to which header file they
172 are in. On the first run this file is copied to <filename><module>-sections.txt</filename>
173 The author can rearrange the sections, and the order of the
174 declarations within them, to produce the final desired order.
175 The second file it generates is <filename><module>-decl.txt</filename>.
176 This file contains the full declarations found by the scanner. If for
177 some reason one would like some sybols to show up in the docs, where
178 the full declaration cannot be found by th scanner or the declaration
179 should appear differently, one can place enties similar to the ones in
180 <filename><module>-decl.txt</filename> into <filename><module>-overrides.txt</filename>.
182 <application>gtkdoc-scanobj</application> can also be used to dynamically query a library about
183 any GtkObject subclasses it exports. It saves information about each
184 object's position in the class hierarchy and about any GTK Args and Signals it
185 provides.
186 </para>
187 </listitem>
189 <listitem>
190 <para>
191 <guilabel>Generating the "template" files.</guilabel>
193 <application>gtkdoc-mktmpl</application> creates a number of files in
194 the <filename class='directory'>tmpl/</filename> subdirectory, using the
195 information gathered in the first step. (Note that this can be run
196 repeatedly. It will try to ensure that no documentation is ever lost.)
197 </para>
198 <note>
199 <para>
200 Since GTK-Doc 1.9 the templates can be avoided. We encourage people to keep
201 documentation in the code. <application>gtkdocize</application> supports now
202 a <option>--flavour no-tmpl</option> option that chooses a makefile that
203 skips tmpl usage totally.
204 If you have never changed file in tmpl by hand, please remove the dir
205 (e.g. from version control system).
206 </para>
207 </note>
208 </listitem>
210 <listitem>
211 <para>
212 <guilabel>Generating the SGML/XML and HTML/PDF.</guilabel>
214 <application>gtkdoc-mkdb</application> turns the template files into
215 SGML or XML files in the <filename class='directory'>sgml/</filename>
216 or <filename class='directory'>xml/</filename> subdirectory.
217 If the source code contains documentation on functions, using the
218 special comment blocks, it gets merged in here. If there are no tmpl files used
219 it only reads takes docs from sources and introspection data.
220 </para>
221 <para>
222 <application>gtkdoc-mkhtml</application> turns the SGML/XML files into HTML
223 files in the <filename class='directory'>html/</filename> subdirectory.
224 Likewise <application>gtkdoc-mkpdf</application> turns the SGML/XML files into a PDF
225 docuemnt called <filename><package>.pdf</filename>.
226 </para>
227 <para>
228 Files in <filename class='directory'>sgml/</filename> or
229 <filename class='directory'>xml/</filename> and <filename class='directory'>html/</filename>
230 directories are always overwritten. One should never edit them directly.
231 </para>
232 </listitem>
234 <listitem>
235 <para>
236 <guilabel>Fixing up cross-references between documents.</guilabel>
238 After installing the HTML files, <application>gtkdoc-fixxref</application> can be run to fix up any
239 cross-references between separate documents. For example, the GTK+
240 documentation contains many cross-references to types documented in the GLib manual.
242 When creating the source tarball for distribution, <application>gtkdoc-rebase</application>
243 turns all external links into web-links. When installing distributed (pregenerated) docs
244 the same application will try to turn links back to local links
245 (where those docs are installed).
246 </para>
247 </listitem>
248 </orderedlist>
250 </sect1>
252 <sect1 id="gettinggtkdoc">
253 <title>Getting GTK-Doc</title>
255 <sect2 id="requirements">
256 <title>Requirements</title>
257 <para>
258 <guilabel>Perl v5</guilabel> - the main scripts are in Perl.
259 </para>
260 <para>
261 <guilabel>DocBook DTD v3.0</guilabel> - This is the DocBook SGML DTD.
262 <ulink url="http://www.ora.com/davenport" type="http">http://www.ora.com/davenport</ulink>
263 </para>
264 <para>
265 <guilabel>Jade v1.1</guilabel> - This is a DSSSL processor for converting SGML to various formats.
266 <ulink url="http://www.jclark.com/jade" type="http">http://www.jclark.com/jade</ulink>
267 </para>
268 <para>
269 <guilabel>Modular DocBook Stylesheets</guilabel>
270 This is the DSSSL code to convert DocBook to HTML (and a few other
271 formats). It's used together with jade.
272 I've customized the DSSSL code slightly, in gtk-doc.dsl, to colour
273 the program code listings/declarations, and to support global
274 cross-reference indices in the generated HTML.
275 <ulink url="http://nwalsh.com/docbook/dsssl" type="http">http://nwalsh.com/docbook/dsssl</ulink>
276 </para>
277 <para>
278 <guilabel>docbook-to-man</guilabel> - if you want to create man pages from the DocBook.
279 I've customized the 'translation spec' slightly, to capitalise section
280 headings and add the 'GTK Library' title at the top of the pages and the
281 revision date at the bottom.
282 There is a link to this on <ulink url="http://www.ora.com/davenport" type="http">http://www.ora.com/davenport</ulink>
283 NOTE: This does not work yet.
284 </para>
285 </sect2>
287 <sect2 id="installation">
288 <title>Installation</title>
289 <para>
290 There is no standard place where the DocBook Modular Stylesheets are installed.
291 </para>
292 <para>
293 GTK-Doc's configure script searches these 3 directories automatically:
294 </para>
295 <para>
296 <filename> /usr/lib/sgml/stylesheets/nwalsh-modular </filename> (used by RedHat)
297 </para>
298 <para>
299 <filename> /usr/lib/dsssl/stylesheets/docbook </filename> (used by Debian)
300 </para>
301 <para>
302 <filename> /usr/share/sgml/docbkdsl </filename> (used by SuSE)
303 </para>
304 <para>
305 If you have the stylesheets installed somewhere else, you need to configure
306 GTK-Doc using the option:
307 <command> --with-dsssl-dir=<PATH_TO_TOPLEVEL_STYLESHEETS_DIR> </command>
308 </para>
309 </sect2>
311 </sect1>
313 <!-- not realy worth a section
314 <sect1 id="whentousegtkdoc">
315 <title>When to Use GTK-Doc</title>
317 <para>
318 (What things GTK-Doc should, and shouldn't, be used for.)
319 (- ???)
320 (- non C-based projects)
321 (+ Tutorials)
322 </para>
324 </sect1>
325 -->
327 <sect1 id="aboutgtkdoc">
328 <title>About GTK-Doc</title>
330 <para>
331 (FIXME)
332 </para>
334 <para>
335 (History, authors, web pages, license, future plans,
336 comparison with other similar systems.)
337 </para>
339 </sect1>
341 <sect1 id="aboutthismanual">
342 <title>About this Manual</title>
344 <para>
345 (FIXME)
346 </para>
348 <para>
349 (who it is meant for, where you can get it, license)
350 </para>
352 </sect1>
354 </chapter>
356 <chapter id="settingup">
357 <title>Setting up your project</title>
359 <para>
360 The next sections describe what steps to perform to integrate GTK-Doc into
361 your project. Theses section assume we work on a project called 'meep'.
362 This project contains a library called 'libmeep' and
363 an end-user app called 'meeper'.
364 </para>
366 <sect1 id="settingup_docfiles">
367 <title>Setting up a skeleton documentation</title>
369 <para>
370 Under your top-level project directory create folders called docs/reference
371 (this way you can also have docs/help for end-user documentation).
372 It is recommended to create another subdirectory with the name of the doc-package.
373 For packages with just one library this step is not necessary.
374 </para>
376 <para>
377 This can then look as show below:
378 <example><title>Example directory structure</title>
379 <programlisting>
380 <![CDATA[
381 meep/
382 docs/
383 reference/
384 libmeep/
385 meeper/
386 src/
387 libmeep/
388 meeper/
389 ]]>
390 </programlisting>
391 </example>
392 </para>
393 </sect1>
395 <sect1 id="settingup_autoconf">
396 <title>Integration with autoconf</title>
398 <para>
399 Very easy! Just add one line to your <filename>configure.ac</filename> script.
400 </para>
402 <para>
403 <example><title>Integration with autoconf</title>
404 <programlisting>
405 <![CDATA[
406 # check for gtk-doc
407 GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
408 ]]>
409 </programlisting>
410 </example>
411 </para>
413 <para>
414 The first argument is used to check for the gtkdocversion at configure time.
415 The 2nd, optional argument is used by <application>gtkdocize</application>.
416 The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure switches:
417 </para>
418 <orderedlist>
419 <listitem><para>--with-html-dir=PATH : path to installed docs</para></listitem>
420 <listitem><para>--enable-gtk-doc : use gtk-doc to build documentation [default=no]</para></listitem>
421 <listitem><para>--enable-gtk-doc-html : build documentation in html format [default=yes]</para></listitem>
422 <listitem><para>--enable-gtk-doc-pdf : build documentation in pdf format [default=no]</para></listitem>
423 </orderedlist>
425 <important>
426 <para>
427 GTK-Doc is disabled by default! Remember to pass the option
428 <option>'--enable-gtk-doc'</option> to the next
429 <filename>configure</filename> run. Otherwise pregenerated documentation is installed
430 (which makes sense for users but not for developers).
431 </para>
432 </important>
434 <para>
435 Furthermore it is recommended that you have the following line inside
436 you <filename>configure.ac</filename> script.
437 This allows <application>gtkdocize</application> to automatically copy the
438 macro definition for <function>GTK_DOC_CHECK</function> to your project.
439 </para>
441 <para>
442 <example><title>Preparation for gtkdocize</title>
443 <programlisting>
444 <![CDATA[
445 AC_CONFIG_MACRO_DIR(m4)
446 ]]>
447 </programlisting>
448 </example>
449 </para>
450 </sect1>
452 <sect1 id="settingup_automake">
453 <title>Integration with automake</title>
455 <para>
456 First copy the <filename>Makefile.am</filename> from the examples subdirectory of the gtkdoc-sources
457 to your project's API documentation directory (
458 <filename class='directory'>./docs/reference/<package></filename>).
459 If you have multiple doc-packages repeat this for each one.
460 </para>
462 <para>
463 The next step is to edit the setting inside the <filename>Makefile.am</filename>.
464 All the settings have a comment above that describes their purpose.
465 Most settings are extra flags passed to the respective tools. Every tool
466 has a variable of the form <option><TOOLNAME>_OPTIONS</option>.
467 All the tools support <option>--help</option> to list the supported
468 parameters.
469 </para>
471 <!-- FIXME: explain options ? -->
473 <para>
474 You may also want to enable GTK-Doc for the distcheckmake target. Just
475 add then one-liner show in the next example to you top-level
476 <filename>Makefile.am</filename>:
477 </para>
479 <para>
480 <example><title>Enable GTK-Doc during make distcheck</title>
481 <programlisting>
482 <![CDATA[
483 DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc
484 ]]>
485 </programlisting>
486 </example>
487 </para>
489 </sect1>
491 <sect1 id="settingup_autogen">
492 <title>Integration with autogen</title>
494 <para>
495 Most projects will have an <filename>autogen.sh</filename> script to
496 setup the build infrastructure after a checkout from version control
497 system (such as cvs/svn/git). GTK-Doc comes with a tool called
498 <application>gtkdocize</application> which can be used in such a script.
499 It should be run before autoheader, automake or autoconf.
500 </para>
502 <para>
503 <example><title>Running gtkdocize from autogen.sh</title>
504 <programlisting>
505 <![CDATA[
506 gtkdocize || exit 1
507 ]]>
508 </programlisting>
509 </example>
510 </para>
512 <para>
513 When running <application>gtkdocize</application> it copies
514 <filename>gtk-doc.make</filename> to you project root (or any directory
515 specified by the <option>--docdir</option> option).
516 If also check you configure script for the <function>GTK_DOC_CHECK</function>
517 invocation.
518 </para>
520 <para>
521 Historically GTK-Doc was gerating template files where developers entered the docs.
522 this turned out to be not so good. Since a few version GTK-Doc could also get all
523 the information from source comments.
524 Since GTK-Doc 1.9 the templates can be avoided. We encourage people to keep
525 documentation in the code. <application>gtkdocize</application> supports now
526 a <option>--flavour no-tmpl</option> option that chooses a makefile that skips
527 tmpl usage totally. Besides adding the option directly to the command
528 invocation, they can be added also to a environment variable called <symbol>GTKDOCIZE_FLAGS</symbol>
529 or set as a 2nd parameter in <symbol>GTK_DOC_CHECK</symbol> macro in the configure script.
530 If you have never changed file in tmpl by hand and migrating from older gtkdoc versions,
531 please remove the dir (e.g. from version control system).
532 </para>
533 </sect1>
535 <sect1 id="settingup_firstrun">
536 <title>Running the doc build</title>
538 <para>
539 After the previous steps it's time to run the build. First we need to
540 rerun <filename>autogen.sh</filename>. If this script runs configure for
541 you, then give it the <option>--enable-gtk-doc</option> option.
542 Otherwise manually run <filename>configure</filename> with this option
543 afterwards.
544 </para>
545 <para>
546 The first make run generates several additional files in the doc-dirs.
547 The important ones are:
548 <filename><package>.types</filename>,
549 <filename><package>-docs.sgml</filename>,
550 <filename><package>-sections.txt</filename>.
551 </para>
552 <para>
553 <example><title>Running the doc build</title>
554 <programlisting>
555 <![CDATA[
556 ./autogen.sh --enable-gtk-doc
557 make
558 ]]>
559 </programlisting>
560 </example>
561 </para>
562 <para>
563 Now you can point your browser to <filename>docs/reference/<package>/index.html</filename>.
564 Yes, it's a bit disappointing still. But hang-on, during the next chapter we
565 tell you how to fill the pages with life.
566 </para>
567 </sect1>
569 <sect1 id="settingup_vcs">
570 <title>Integration with version control systems</title>
572 <para>
573 As a rule of the thumb, it's those files you edit, that should go under
574 version control. For typical projects it's these files:
575 <filename><package>.types</filename>
576 <filename><package>-docs.sgml</filename>
577 <filename><package>-sections.txt</filename>
578 <filename>Makefile.am</filename>
579 </para>
580 </sect1>
582 </chapter>
584 <chapter id="documenting">
585 <title>Documenting the code</title>
587 <para>
588 GTK-Doc uses source code comment with a special syntax for code documentation.
589 Further it retrieves information about your project structure from other
590 sources. During the next section you find all information about the syntax
591 of the comments.
592 </para>
594 <note>
595 <title>Documentation placement</title>
596 <para>
597 In the past most documentation had to be filled into files residing
598 inside the <filename>tmpl</filename> directory. This has the
599 disadvantages that the information is often not updated and also that
600 the file tend to cause conflicts with version control systems.
601 </para>
602 <para>
603 The avoid the aforementioned problems we suggest putting the
604 documentation inside the sources. This manual will only describe this
605 way of documenting code.
606 </para>
607 </note>
609 <!-- -->
611 <sect1 id="documenting_syntax">
612 <title>Documentation comments</title>
614 <para>
615 A multiline comment that starts with an additional '*' marks a
616 documentation block that will be processed by the GTK-Doc tools.
617 <example><title>GTK-Doc comment block</title>
618 <programlisting>
619 <![CDATA[
620 /**
621 * identifier:
622 * documentation ...
623 */
624 ]]>
625 </programlisting>
626 </example>
627 </para>
629 <para>
630 The 'identifier' is one line with the name of the item the comment is
631 related to. The syntax differs a little depending on the item.
632 (TODO add table showing identifiers)
633 </para>
635 <para>
636 The 'documentation' block is also different for each symbol type. Symbol
637 types that get parameters such as functions or macros have the parameter
638 description first followed by a blank line (just a '*').
639 Afterwards follows the detailed description. All lines (outside program-
640 listings and CDATA sections) just containing a ' *' (blank-asterisk) are
641 converted to paragraph breaks.
642 If you don't want a paragraph break, change that into ' * '
643 (blank-asterisk-blank-blank).
644 </para>
646 <para>
647 One advantage of hyper-text over plain-text is the ability to have links
648 in the document. Writing the correct markup for a link can be tedious
649 though. GTK-Doc comes to help by providing several useful abbreviations.
650 <itemizedlist>
651 <listitem>
652 <para>
653 Use function() to refer to functions or macros which take arguments.
654 </para>
655 </listitem>
656 <listitem>
657 <para>
658 Use @param to refer to parameters. Also use this when referring to
659 parameters of other functions, related to the one being described.
660 </para>
661 </listitem>
662 <listitem>
663 <para>
664 Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS.
665 </para>
666 </listitem>
667 <listitem>
668 <para>
669 Use #symbol to refer to other types of symbol, e.g. structs and
670 enums and macros which don't take arguments.
671 </para>
672 </listitem>
673 <listitem>
674 <para>
675 Use #Object::signal to refer to a GObject signal
676 </para>
677 </listitem>
678 <listitem>
679 <para>
680 Use #Object:property to refer to a GObject property
681 </para>
682 </listitem>
683 <listitem>
684 <para>
685 Use #Struct.field to refer to a field inside a structure.
686 </para>
687 </listitem>
688 </itemizedlist>
689 </para>
691 <tip>
692 <para>
693 If you need to use the special characters '<', '>', '()', '@',
694 '%', or '#' in your documentation without GTK-Doc changing them you
695 can use the XML entities "&lt;", "&gt;", "&lpar;",
696 "&rpar;", "&commat;", "&percnt;" and "&num;"
697 respectively or escape them with a backslash '\'.
698 </para>
699 </tip>
701 <para>
702 DocBook can do more that just links. One can also have lists, tables and
703 examples. To enable the usage of SGML/XML tags inside doc-comments you
704 need to have <option>--sgml-mode</option> in the variable
705 <symbol>MKDB_OPTIONS</symbol> inside <filename>Makefile.am</filename>.
706 </para>
708 <tip>
709 <para>
710 As already mentioned earlier GTK-Doc is for documenting public API. Thus
711 one cannot write documentation for static symbols. Nevertheless it is good
712 to comment those symbols too. This helps other to understand you code.
713 Therefore we recommend to comment these using normal comments (without the
714 2nd '*' in the first line).
715 If later the function needs to be made public, all one needs to do is to
716 add another '*' in the comment block and insert the symbol name at the
717 right place inside the sections file.
718 </para>
719 </tip>
720 </sect1>
722 <sect1 id="documenting_sections">
723 <title>Documenting sections</title>
725 <para>
726 Each section of the documentation contains information about one class
727 or module. To introduce the component one can write a section block.
728 The short description is also used inside the table of contents.
729 All the @fields are optional.
730 </para>
732 <para>
733 <example><title>Section comment block</title>
734 <programlisting>
735 <![CDATA[
736 /**
737 * SECTION:meepapp
738 * @short_description: the application class
739 * @title: Meep application
740 * @section_id:
741 * @see_also: #MeepSettings
742 * @stability: Stable
743 * @include: meep/app.h
744 * @Image: application.png
745 *
746 * The application class handles ...
747 */
748 ]]>
749 </programlisting>
750 </example>
751 </para>
753 <variablelist>
754 <varlistentry>
755 <term>SECTION:<name></term>
756 <listitem>
757 <para>
758 The name links the section documentation to the respective part in
759 the <filename><package>-sections.txt</filename> file. The
760 name give here should match the <FILE> tag in the
761 <filename><package>-sections.txt</filename> file.
762 </para>
763 </listitem>
764 </varlistentry>
765 <varlistentry>
766 <term>@short_description</term>
767 <listitem>
768 <para>
769 A one line description of the section, that later will appear after
770 the links in the TOC and at the top of the section page.
771 </para>
772 </listitem>
773 </varlistentry>
774 <varlistentry>
775 <term>@title</term>
776 <listitem>
777 <para>
778 The section title defaults to <name> from the SECTION
779 declaration. It can be overridden with the @title field.
780 </para>
781 </listitem>
782 </varlistentry>
783 <varlistentry>
784 <term>@section_id</term>
785 <listitem>
786 <para>
787 Overrides the use of title as a section identifier. For GObjects
788 the <title> is used as a section_id and for other section it
789 is <MODULE>-<title>.
790 </para>
791 </listitem>
792 </varlistentry>
793 <varlistentry>
794 <term>@see_also</term>
795 <listitem>
796 <para>
797 A list of symbols that are related to this section..
798 </para>
799 </listitem>
800 </varlistentry>
801 <varlistentry>
802 <term>@stability</term>
803 <listitem>
804 <para>
805 A informal description of the stability level this API has.
806 We recommend the use of one of these terms:
807 <itemizedlist>
808 <listitem>
809 <para>
810 Stable
811 - The intention of a Stable interface is to enable arbitrary
812 third parties to develop applications to these interfaces,
813 release them, and have confidence that they will run on all
814 minor releases of the product (after the one in which the
815 interface was introduced, and within the same major release).
816 Even at a major release, incompatible changes are expected
817 to be rare, and to have strong justifications.
818 </para>
819 </listitem>
820 <listitem>
821 <para>
822 Unstable
823 - Unstable interfaces are experimental or transitional.
824 They are typically used to give outside developers early
825 access to new or rapidly changing technology, or to provide
826 an interim solution to a problem where a more general
827 solution is anticipated.
828 No claims are made about either source or binary
829 compatibility from one minor release to the next.
830 </para>
831 </listitem>
832 <listitem>
833 <para>
834 Private
835 - An interface that can be used within the GNOME stack
836 itself, but that is not documented for end-users. Such
837 functions should only be used in specified and documented
838 ways.
839 </para>
840 </listitem>
841 <listitem>
842 <para>
843 Internal
844 - An interface that is internal to a module and does not
845 require end-user documentation. Functions that are
846 undocumented are assumed to be Internal.
847 </para>
848 </listitem>
849 </itemizedlist>
850 </para>
851 </listitem>
852 </varlistentry>
853 <varlistentry>
854 <term>@include</term>
855 <listitem>
856 <para>
857 The <literal>#include</literal> files to show in the section
858 synopsis (a comma separated list), overriding the global
859 value from the <link linkend="metafiles_sections">section
860 file</link> or command line. This item is optional.
861 </para>
862 </listitem>
863 </varlistentry>
864 <varlistentry>
865 <term>@image</term>
866 <listitem>
867 <para>
868 The image to display at the top of the reference page for this
869 section. This will often be some sort of a diagram to illustrate
870 the visual appearance of a class or a diagram of its relationship
871 to other classes. This item is optional.
872 </para>
873 </listitem>
874 </varlistentry>
875 </variablelist>
877 <tip>
878 <para>
879 To avoid unnecessary recompilation after doc-changes put the section
880 docs into the c-source where possible.
881 </para>
882 </tip>
884 </sect1>
886 <sect1 id="documenting_symbols">
887 <title>Documenting symbols</title>
889 <para>
890 Each symbol (function, macro, struct, enum, signal and property) is
891 documented in a separate block. The block is best placed close to the
892 definition of the symbols so that it is easy to keep them in sync.
893 Thus function are usually documented in the c-source and macros, struct
894 and enum in the header file.
895 </para>
897 <sect2><title>General tags</title>
899 <para>
900 You can add versioning information to all documentation elements to tell
901 when an api was introduced, or when it was deprecated.
902 </para>
904 <variablelist><title>Versioning Tags</title>
905 <varlistentry><term>Since:</term>
906 <listitem>
907 <para>
908 Description since which version of the code the API is available.
909 </para>
910 </listitem>
911 </varlistentry>
912 <varlistentry><term>Deprecated:</term>
913 <listitem>
914 <para>
915 Paragraph denoting that this function should no be used anymore.
916 The description should point the reader to the new API.
917 </para>
918 </listitem>
919 </varlistentry>
920 </variablelist>
922 <para>
923 (FIXME : Stability information)
924 </para>
926 <example><title>General tags</title>
927 <programlisting>
928 <![CDATA[
929 /**
930 * foo_get_bar:
931 * @foo: some foo
932 *
933 * Retrieves @foo's bar.
934 *
935 * Returns: @foo's bar
936 *
937 * Since: 2.6
938 * Deprecated: 2.12: Use foo_baz_get_bar() instead.
939 **/
940 Bar *
941 foo_get_bar(Foo *foo)
942 {
943 ...
944 ]]>
945 </programlisting>
946 </example>
947 </sect2>
949 <sect2><title>Function comment block</title>
951 <para>
952 Please remember to:
953 <itemizedlist>
954 <listitem>
955 <para>
956 Document whether returned objects, lists, strings, etc, should be
957 freed/unrefed/released.
958 </para>
959 </listitem>
960 <listitem>
961 <para>
962 Document whether parameters can be NULL, and what happens if they are.
963 </para>
964 </listitem>
965 <listitem>
966 <para>
967 Mention interesting pre-conditions and post-conditions where appropriate.
968 </para>
969 </listitem>
970 </itemizedlist>
971 </para>
973 <para>
974 Gtk-doc assumes all symbols (macros, functions) starting with '_' are
975 private. They are treated like static functions.
976 </para>
978 <para>
979 <!-- FIXME: we should ideally link/describe the gobject introspection
980 annotation tag -->
981 Also, take a look at gobject introspection annotation tags:
982 http://live.gnome.org/GObjectIntrospection/Annotations
983 </para>
985 <example><title>Function comment block</title>
986 <programlisting>
987 <![CDATA[
988 /**
989 * function_name:
990 * @par1: description of parameter 1. These can extend over more than
991 * one line.
992 * @par2: description of parameter 2
993 * @...: a %NULL-terminated list of bars
994 *
995 * The function description goes here. You can use @par1 to refer to parameters
996 * so that they are highlighted in the output. You can also use %constant
997 * for constants, function_name2() for functions and #GtkWidget for links to
998 * other declarations (which may be documented elsewhere).
999 *
1000 * Returns: an integer.
1001 *
1002 * Since: 2.2
1003 * Deprecated: 2.18: Use other_function() instead.
1004 */
1005 ]]>
1006 </programlisting>
1007 </example>
1009 <variablelist><title>Function tags</title>
1010 <varlistentry><term>Returns:</term>
1011 <listitem>
1012 <para>
1013 Paragraph describing the returned result.
1014 </para>
1015 </listitem>
1016 </varlistentry>
1017 <varlistentry><term>@...:</term>
1018 <listitem>
1019 <para>
1020 In case the function has variadic arguments, you should use this
1021 tag (@Varargs: does also work for historic reasons).
1022 </para>
1023 </listitem>
1024 </varlistentry>
1025 </variablelist>
1027 </sect2>
1029 <sect2><title>Property comment block</title>
1031 <example><title>Property comment block</title>
1032 <programlisting>
1033 <![CDATA[
1034 /**
1035 * SomeWidget:some-property:
1036 *
1037 * Here you can document a property.
1038 */
1039 g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
1040 ]]>
1041 </programlisting>
1042 </example>
1044 </sect2>
1046 <sect2><title>Signal comment block</title>
1048 <para>
1049 Please remember to:
1050 <itemizedlist>
1051 <listitem>
1052 <para>
1053 Document when the signal is emitted and whether it is emitted before
1054 or after other signals.
1055 </para>
1056 </listitem>
1057 <listitem>
1058 <para>
1059 Document what an application might do in the signal handler.
1060 </para>
1061 </listitem>
1062 </itemizedlist>
1063 </para>
1065 <example><title>Signal comment block</title>
1066 <programlisting>
1067 <![CDATA[
1068 /**
1069 * FooWidget::foobarized:
1070 * @widget: the widget that received the signal
1071 * @foo: some foo
1072 * @bar: some bar
1073 *
1074 * The ::foobarized signal is emitted each time someone tries to foobarize @widget.
1075 */
1076 foo_signals[FOOBARIZE] =
1077 g_signal_new ("foobarize",
1078 ...
1079 ]]>
1080 </programlisting>
1081 </example>
1083 </sect2>
1085 <sect2><title>Struct comment block</title>
1086 <example><title>Struct comment block</title>
1087 <programlisting>
1088 <![CDATA[
1089 /**
1090 * FooWidget:
1091 * @bar: some #gboolean
1092 *
1093 * This is the best widget, ever.
1094 */
1095 typedef struct _FooWidget {
1096 /*< private >*/
1097 GtkWidget parent;
1099 /*< public >*/
1100 gboolean bar;
1101 } FooWidget;
1102 ]]>
1103 </programlisting>
1104 </example>
1106 <para>
1107 Use <code>/*< private >*/</code> before the private struct fields
1108 you want to hide. Use <code>/*< public >*/</code> for the reverse
1109 behavirour.
1110 </para>
1112 </sect2>
1114 <sect2><title>Enum comment block</title>
1115 <example><title>Enum comment block</title>
1116 <programlisting>
1117 <![CDATA[
1118 /**
1119 * Something:
1120 * @SOMETHING_FOO: something foo
1121 * @SOMETHING_BAR: something bar
1122 *
1123 * Enum values used for the thing, to specify the thing.
1124 *
1125 **/
1126 typedef enum {
1127 SOMETHING_FOO,
1128 SOMETHING_BAR,
1129 /*< private >*/
1130 SOMETHING_COUNT
1131 } Something;
1132 ]]>
1133 </programlisting>
1134 </example>
1136 <para>
1137 Use <code>/*< private >*/</code> before the private enum values
1138 you want to hide. Use <code>/*< public >*/</code> for the reverse
1139 behavirour.
1140 </para>
1142 </sect2>
1143 </sect1>
1145 <sect1 id="documenting_docbook">
1146 <title>Useful DocBook tags</title>
1148 <para>
1149 Here are some DocBook tags which are most useful when documenting the
1150 code.
1151 </para>
1153 <para>
1154 To link to another section in the GTK docs:
1156 <informalexample>
1157 <programlisting>
1158 <![CDATA[
1159 <link linkend="glib-Hash-Tables">Hash Tables</link>
1160 ]]>
1161 </programlisting>
1162 </informalexample>
1163 The linkend is the SGML/XML id on the top item of the page you want to link to.
1164 For most pages this is currently the part ("gtk", "gdk", "glib") and then
1165 the page title ("Hash Tables"). For widgets it is just the class name.
1166 Spaces and underscores are converted to '-' to conform to SGML/XML.
1167 </para>
1169 <para>
1170 To refer to an external function, e.g. a standard C function:
1171 <informalexample>
1172 <programlisting>
1173 <![CDATA[
1174 <function>...</function>
1175 ]]>
1176 </programlisting>
1177 </informalexample>
1178 </para>
1180 <para>
1181 To include example code:
1182 <informalexample>
1183 <programlisting>
1184 <![CDATA[
1185 <example>
1186 <title>Using a GHashTable.</title>
1187 <programlisting>
1188 ...
1189 </programlisting>
1190 </example>
1191 ]]>
1192 </programlisting>
1193 </informalexample>
1194 or possibly this, for very short code fragments which don't need a title:
1195 <informalexample>
1196 <programlisting>
1197 <![CDATA[
1198 <informalexample>
1199 <programlisting>
1200 ...
1201 </programlisting>
1202 </informalexample>
1203 ]]>
1204 </programlisting>
1205 </informalexample>
1206 For the latter GTK-Doc also supports an abbreviation:
1207 <![CDATA[
1208 |[
1209 ...
1210 ]|
1211 ]]>
1212 </para>
1214 <para>
1215 To include bulleted lists:
1216 <informalexample>
1217 <programlisting>
1218 <![CDATA[
1219 <itemizedlist>
1220 <listitem>
1221 <para>
1222 ...
1223 </para>
1224 </listitem>
1225 <listitem>
1226 <para>
1227 ...
1228 </para>
1229 </listitem>
1230 </itemizedlist>
1231 ]]>
1232 </programlisting>
1233 </informalexample>
1234 </para>
1236 <para>
1237 To include a note which stands out from the text:
1238 <informalexample>
1239 <programlisting>
1240 <![CDATA[
1241 <note>
1242 <para>
1243 Make sure you free the data after use.
1244 </para>
1245 </note>
1246 ]]>
1247 </programlisting>
1248 </informalexample>
1249 </para>
1251 <para>
1252 To refer to a type:
1253 <informalexample>
1254 <programlisting>
1255 <![CDATA[
1256 <type>unsigned char</type>
1257 ]]>
1258 </programlisting>
1259 </informalexample>
1260 </para>
1262 <para>
1263 To refer to an external structure (not one described in the GTK docs):
1264 <informalexample>
1265 <programlisting>
1266 <![CDATA[
1267 <structname>XFontStruct</structname>
1268 ]]>
1269 </programlisting>
1270 </informalexample>
1271 </para>
1273 <para>
1274 To refer to a field of a structure:
1275 <informalexample>
1276 <programlisting>
1277 <![CDATA[
1278 <structfield>len</structfield>
1279 ]]>
1280 </programlisting>
1281 </informalexample>
1282 </para>
1284 <para>
1285 To refer to a class name, we could possibly use:
1286 <informalexample>
1287 <programlisting>
1288 <![CDATA[
1289 <classname>GtkWidget</classname>
1290 ]]>
1291 </programlisting>
1292 </informalexample>
1293 but you'll probably be using #GtkWidget instead (to automatically create
1294 a link to the GtkWidget page - see <link linkend="documenting_syntax">the abbreviations</link>).
1295 </para>
1297 <para>
1298 To emphasize text:
1299 <informalexample>
1300 <programlisting>
1301 <![CDATA[
1302 <emphasis>This is important</emphasis>
1303 ]]>
1304 </programlisting>
1305 </informalexample>
1306 </para>
1308 <para>
1309 For filenames use:
1310 <informalexample>
1311 <programlisting>
1312 <![CDATA[
1313 <filename>/home/user/documents</filename>
1314 ]]>
1315 </programlisting>
1316 </informalexample>
1317 </para>
1319 <para>
1320 To refer to keys use:
1321 <informalexample>
1322 <programlisting>
1323 <![CDATA[
1324 <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>
1325 ]]>
1326 </programlisting>
1327 </informalexample>
1328 </para>
1330 </sect1>
1331 </chapter>
1333 <chapter id="metafiles">
1334 <title>Filling the extra files</title>
1336 <para>
1337 There are a couple of extra files, that need to be maintained along with
1338 the inline source code comments:
1339 <filename><package>.types</filename>,
1340 <filename><package>-docs.sgml</filename>,
1341 <filename><package>-sections.txt</filename>.
1342 </para>
1344 <sect1 id="metafiles_types">
1345 <title>Editing the types file</title>
1347 <para>
1348 If your library or application includes GtkObjects/GObjects, you want
1349 their signals, arguments/parameters and position in the hierarchy to be
1350 shown in the documentation. All you need to do, is to list the
1351 <function>xxx_get_type</function> functions together with their include
1352 inside the <filename><package>.types</filename> file.
1353 </para>
1355 <para>
1356 <example><title>Example types file snippet</title>
1357 <programlisting>
1358 <![CDATA[
1359 #include <gtk/gtk.h>
1361 gtk_accel_label_get_type
1362 gtk_adjustment_get_type
1363 gtk_alignment_get_type
1364 gtk_arrow_get_type
1365 ]]>
1366 </programlisting>
1367 </example>
1368 </para>
1370 <para>
1371 Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this list for you.
1372 Just add "--rebuild-types" to SCAN_OPTIONS in <filename>Makefile.am</filename>. If you
1373 use this approach you should not dist the types file nor have it under version control.
1374 </para>
1376 </sect1>
1378 <sect1 id="metafiles_master">
1379 <title>Editing the master document</title>
1381 <para>
1382 GTK-Doc produces documentation in DocBook SGML/XML. When processing the
1383 inline source comments, the GTK-Doc tools generate one documentation
1384 page per class or module as a separate file. The master document
1385 includes them and place them in a order.
1386 </para>
1388 <para>
1389 While GTK-Doc creates a template master document for you, later run will
1390 not touch it again. This means that one can freely structure the
1391 documentation. That includes grouping pages and adding extra pages.
1392 GTK-Doc has now a test suite, where also the master-document is recreated from scratch.
1393 Its a good idea to look at this from time to time to see if there are some new goodies
1394 introduced there.
1395 </para>
1397 <tip>
1398 <para>
1399 Do not create tutorials as extra documents. Just write extra chapters.
1400 The benefit of directly embedding the tutorial for your library into
1401 the API documentation is that it is easy to link for the tutorial to
1402 symbol documentation. Apart chances are higher that the tutorial gets
1403 updates along with the library.
1404 </para>
1405 </tip>
1407 <para>
1408 So what are the things to change inside the master document? For a start
1409 is only a little. There are some placeholders (text in square brackets)
1410 there which you should take care of.
1411 </para>
1413 <para>
1414 <example><title>Master document header</title>
1415 <programlisting>
1416 <![CDATA[
1417 <bookinfo>
1418 <title>MODULENAME Reference Manual</title>
1419 <releaseinfo>
1420 for MODULENAME [VERSION]
1421 The latest version of this documentation can be found on-line at
1422 <ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html">http://[SERVER]/MODULENAME/</ulink>.
1423 </releaseinfo>
1424 </bookinfo>
1426 <chapter>
1427 <title>[Insert title here]</title>
1428 ]]>
1429 </programlisting>
1430 </example>
1431 </para>
1433 </sect1>
1435 <sect1 id="metafiles_sections">
1436 <title>Editing the section file</title>
1438 <para>
1439 The section file is used to organise the documentation output by
1440 GTK-Doc. Here one specifies which symbol belongs to which module or
1441 class and control the visibility (public or private).
1442 </para>
1444 <para>
1445 The section file is a plain test file with xml like syntax (using tags).
1446 Blank lines are ignored and lines starting with a '#' are treated as
1447 comment lines.
1448 </para>
1450 <para>
1451 The <FILE> ... </FILE> tag is used to specify the file name,
1452 without any suffix. For example, using '<FILE>gnome-config</FILE>'
1453 will result in the section declarations being output in the template
1454 file <filename>tmpl/gnome-config.sgml</filename>, which will be
1455 converted into the DocBook SGML/XML file <filename>sgml/gnome-config.sgml</filename>
1456 or .DocBook XML file <filename>xml/gnome-config.xml</filename>.
1457 (The name of the html file is based on the module name and the section
1458 title, or for gobjects it is based on the gobjects class name converted
1459 to lower case).
1460 </para>
1462 <para>
1463 The <TITLE> ... </TITLE> tag is used to specify the title of
1464 the section. It is only useful before the templates (if used) are
1465 initially created, since the title set in the template file overrides
1466 this. Also if one uses SECTION comment in the sources, this is obsolete.
1467 </para>
1469 <para>
1470 You can group items in the section by using the <SUBSECTION> tag.
1471 Currently it outputs a blank line between subsections in the synopsis
1472 section.
1473 You can also use <SUBSECTION Standard> for standard GObject
1474 declarations (e.g. the functions like g_object_get_type and macros like
1475 G_OBJECT(), G_IS_OBJECT() etc.).
1476 Currently these are left out of the documentation.
1477 You can also use <SUBSECTION Private> for private declarations
1478 which will not be output (It is a handy way to avoid warning messages
1479 about unused declarations.).
1480 If your library contains private types which you don't want to appear in
1481 the object hierarchy and the list of implemented or required interfaces,
1482 add them to a Private subsection.
1483 </para>
1485 <para>
1486 You can also use <INCLUDE> ... </INCLUDE> to specify the
1487 #include files which are shown in the synopsis sections.
1488 It contains a comma-separate list of #include files, without the angle
1489 brackets. If you set it outside of any sections, it acts for all
1490 sections until the end of the file. If you set it within a section, it
1491 only applies to that section.
1492 </para>
1494 </sect1>
1496 </chapter>
1498 <chapter id="reports">
1499 <title>Controlling the result</title>
1501 <para>
1502 A GTK-Doc run generates report files inside the documentation directory.
1503 The generated files are named:
1504 <filename><package>-undocumented.txt</filename>,
1505 <filename><package>-undeclared.txt</filename> and
1506 <filename><package>-unused.txt</filename>.
1507 All those are plain text files that can be viewed and postprocessed easily.
1508 </para>
1510 <para>
1511 The <filename><package>-undocumented.txt</filename> file starts with
1512 the documentation coverage summary. Below are two sections divided by
1513 blank lines. The first section lists undocumented or incomplete symbols.
1514 The second section does the same for section docs. Incomplete entries are
1515 those, which have documentation, but where e.g. a new parameter has been
1516 added.
1517 </para>
1519 <para>
1520 The <filename><package>-undeclared.txt</filename> file lists symbols
1521 given in the <filename><package>-sections.txt</filename> but not
1522 found in the sources. Check if they have been removed or if they are
1523 misspelled.
1524 </para>
1526 <para>
1527 The <filename><package>-unused.txt</filename> file lists symbol
1528 names, where the GTK-Doc scanner has found documentation, but does not
1529 know where to put it. This means that the symbol has not yet been added to
1530 the <filename><package>-sections.txt</filename> file.
1531 </para>
1533 <tip>
1534 <para>
1535 Enable or add the <option>TESTS=$(GTKDOC_CHECK)</option> line in Makefile.am.
1536 If at least GTK-Doc 1.9 is installed, this will run sanity checks during
1537 <command>make check</command> run.
1538 </para>
1539 </tip>
1541 <para>
1542 One can also look at the files produced by the source code scanner:
1543 <filename><package>-decl-list.txt</filename> and
1544 <filename><package>-decl.txt</filename>. The first and can be
1545 compared with the section file if that is manualy maintained. The second
1546 lists all declarations fromt he headers If a symbol is missing one could
1547 check if this file contains it.
1548 </para>
1550 <para>
1551 If the project is GObject based, one can also look into the files produced
1552 by the object scanner:
1553 <filename><package>.args.txt</filename>,
1554 <filename><package>.hierarchy.txt</filename>,
1555 <filename><package>.interfaces.txt</filename>,
1556 <filename><package>.prerequisites.txt</filename> and
1557 <filename><package>.signals.txt</filename>. If there are missing
1558 symbols in any of those, one can ask gtkdoc to keep the intermedia scanner
1559 file for further analysis, but running it as
1560 <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
1561 </para>
1562 </chapter>
1564 <chapter id="faq">
1565 <title>Frequently asked question</title>
1567 <segmentedlist>
1568 <?dbhtml list-presentation="list"?>
1569 <segtitle>Question</segtitle>
1570 <segtitle>Answer</segtitle>
1571 <seglistitem>
1572 <seg>No class hierarchy.</seg>
1573 <seg>
1574 The objects <function>xxx_get_type()</function> function has not been
1575 entered into the <filename><package>.types</filename> file.
1576 </seg>
1577 </seglistitem>
1578 <seglistitem>
1579 <seg>Still no class hierarchy.</seg>
1580 <seg>
1581 Missing or wrong naming in <filename><package>-sections.txt</filename>
1582 file (see <ulink url="http://mail.gnome.org/archives/gtk-doc-list/2003-October/msg00006.html">explanation</ulink>).
1583 </seg>
1584 </seglistitem>
1585 <seglistitem>
1586 <seg>Damn, I have still no class hierarchy.</seg>
1587 <seg>
1588 Is the object name (name of the instance struct, e.g. <type>GtkWidget</type>)
1589 part of the normal section (don't put this into Standard or Private
1590 subsections).
1591 </seg>
1592 </seglistitem>
1593 <seglistitem>
1594 <seg>No symbol index.</seg>
1595 <seg>
1596 Does the <filename><package>-docs.{xml,sgml}</filename> contain a
1597 index that xi:includes the generated index?
1598 </seg>
1599 </seglistitem>
1600 <seglistitem>
1601 <seg>Symbols are not linked to their doc-section.</seg>
1602 <seg>
1603 Is the doc-comment using the correct markup (added #,% or ())?
1604 Check if the gtkdoc-fixxref warns about unresolvable xrefs.
1605 </seg>
1606 </seglistitem>
1607 <seglistitem>
1608 <seg>A new class does not appear in the docs.</seg>
1609 <seg>
1610 Is the new page xi:included from
1611 <filename><package>-docs.{xml,sgml}</filename>.
1612 </seg>
1613 </seglistitem>
1614 <seglistitem>
1615 <seg>A new symbol does not appear in the docs.</seg>
1616 <seg>
1617 Is the doc-comment properly formatted. Check for spelling mistakes in
1618 the begin of the comment. Check if the gtkdoc-fixxref warns about
1619 unresolvable xrefs. Check if the symbol is correctly listed in the
1620 <filename><package>-sections.txt</filename> in a public subsection.
1621 </seg>
1622 </seglistitem>
1623 <seglistitem>
1624 <seg>A type is missing from the class hierarchy.</seg>
1625 <seg>
1626 If the type is listed in <filename><package>.hierarchy</filename>
1627 but not in <filename>xml/tree_index.sgml</filename> then double check
1628 that the type is correctly placed in the <filename><package>-sections.txt</filename>.
1629 If the type instance (e.g. <type>GtkWidget</type>) is not listed or
1630 incidentialy makred private it will not be shown.
1631 </seg>
1632 </seglistitem>
1633 <seglistitem>
1634 <seg>I get foldoc links for all gobject annotations.</seg>
1635 <seg>
1636 Check that <filename>xml/annotation-glossary.xml</filename> is
1637 xi:included from <filename><package>-docs.{xml,sgml}</filename>.
1638 </seg>
1639 </seglistitem>
1641 <!-- gtk-doc warnings: -->
1642 <seglistitem>
1643 <seg>Parameter described in source code comment block but does not exist</seg>
1644 <seg>Check if the prototype in the header has different parameter names as in the source.</seg>
1645 </seglistitem>
1647 <!-- docbook warnings: -->
1648 <seglistitem>
1649 <seg>multiple "IDs" for constraint linkend: XYZ</seg>
1650 <seg>Symbol XYZ appears twice in <filename><package>-sections.txt</filename> file.</seg>
1651 </seglistitem>
1652 <seglistitem>
1653 <seg>Element typename in namespace '' encountered in para, but no template matches.</seg>
1654 <seg />
1655 </seglistitem>
1656 </segmentedlist>
1657 </chapter>
1659 <!-- ======== Appendix: FDL ================================== -->
1660 &FDL;
1662 </book>