| blob | 9d8dd207b9a8409a9e6e6bc8637ac16c479f2246 |
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.1.2//EN" "
5 http://www.oasis-open.org/docbook/xml/4.1.2/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.13</revnumber>
81 <date>18 December 2009</date>
82 </revision>
83 <revision>
84 <revnumber>1.12</revnumber>
85 <date>18 December 2009</date>
86 </revision>
87 <revision>
88 <revnumber>1.11</revnumber>
89 <date>16 Novemebr 2008</date>
90 <authorinitials>mal</authorinitials>
91 <revremark>GNOME doc-utils migration</revremark>
92 </revision>
93 </revhistory>
95 </bookinfo>
97 <!-- ======== Chapter 1: Introduction ======================== -->
99 <chapter id="introduction">
100 <title>Introduction</title>
102 <para>
103 This chapter introduces GTK-Doc and gives an overview of what it is and
104 how it is used.
105 </para>
107 <sect1 id="whatisgtkdoc">
108 <title>What is GTK-Doc?</title>
110 <para>
111 GTK-Doc is used to document C code. It is typically used to document the public
112 API of libraries, such as the GTK+ and GNOME libraries. But it can also be
113 used to document application code.
114 </para>
115 </sect1>
117 <sect1 id="howdoesgtkdocwork">
118 <title>How Does GTK-Doc Work?</title>
120 <para>
121 GTK-Doc works by using documentation of functions placed inside the source files in
122 specially-formatted comment blocks, or documentation added to the template files
123 which GTK-Doc uses (though note that GTK-Doc will only document functions that
124 are declared in header files; it won't produce output for static functions).
125 </para>
127 <para>
128 GTK-Doc consists of a number of perl scripts, each performing a different step
129 in the process.
130 </para>
132 <para>
133 There are 5 main steps in the process:
134 </para>
136 <orderedlist>
138 <listitem>
139 <para>
140 <guilabel>Writing the documentation.</guilabel>
142 The author fills in the source files with the documentation for each
143 function, macro, union etc. (In the past information was entered in
144 generated template files, which is not recommended anymore).
145 </para>
146 </listitem>
148 <listitem>
149 <para>
150 <guilabel>Gathering information about the code.</guilabel>
152 <application>gtkdoc-scan</application> scans the header files of the
153 code looking for declarations of functions, macros, enums, structs, and unions.
154 It creates the file <filename><module>-decl-list.txt</filename> containg a list of the
155 declarations, placing them into sections according to which header file they
156 are in. On the first run this file is copied to <filename><module>-sections.txt</filename>
157 The author can rearrange the sections, and the order of the
158 declarations within them, to produce the final desired order.
159 The second file it generates is <filename><module>-decl.txt</filename>.
160 This file contains the full declarations found by the scanner. If for
161 some reason one would like some sybols to show up in the docs, where
162 the full declaration cannot be found by th scanner or the declaration
163 should appear differently, one can place enties similar to the ones in
164 <filename><module>-decl.txt</filename> into <filename><module>-overrides.txt</filename>.
166 <application>gtkdoc-scanobj</application> can also be used to dynamically query a library about
167 any GtkObject subclasses it exports. It saves information about each
168 object's position in the class hierarchy and about any GTK Args and Signals it
169 provides.
170 </para>
171 </listitem>
173 <listitem>
174 <para>
175 <guilabel>Generating the "template" files.</guilabel>
177 <application>gtkdoc-mktmpl</application> creates a number of files in
178 the <filename class='directory'>tmpl/</filename> subdirectory, using the
179 information gathered in the first step. (Note that this can be run
180 repeatedly. It will try to ensure that no documentation is ever lost.)
181 </para>
182 <note>
183 <para>
184 Since gtk-doc 1.9 the templates can be avoided. We encourage people to keep
185 documentation in the code. <application>gtkdocize</application> supports now
186 a <command>--flavour no-tmpl</command> option that chooses a makefile that skips tmpl usage totally.
187 If you have never changed file in tmpl by hand, please remove the dir once.
188 </para>
189 </note>
190 </listitem>
192 <listitem>
193 <para>
194 <guilabel>Generating the SGML/XML and HTML.</guilabel>
196 <application>gtkdoc-mkdb</application> turns the template files into
197 SGML or XML files in the <filename class='directory'>sgml/</filename>
198 or <filename class='directory'>xml/</filename> subdirectory.
199 If the source code contains documentation on functions, using the
200 special comment blocks, it gets merged in here. If there are no tmpl files used
201 it only reads takes docs from sources and introspection data.
203 <application>gtkdoc-mkhtml</application> turns the SGML files into HTML
204 files in the <filename class='directory'>html/</filename> subdirectory.
206 Files in <filename class='directory'>sgml/</filename> or
207 <filename class='directory'>xml/</filename> and <filename class='directory'>html/</filename>
208 directories are always overwritten. One should never edit them directly.
209 </para>
210 </listitem>
212 <listitem>
213 <para>
214 <guilabel>Fixing up cross-references between documents.</guilabel>
216 After installing the HTML files, <application>gtkdoc-fixxref</application> can be run to fix up any
217 cross-references between separate documents. For example, the GTK+
218 documentation contains many cross-references to types documented in the GLib manual.
220 When creating the source tarball for distribution, <application>gtkdoc-rebase</application>
221 turns all external links into web-links. When installing distributed (pregenerated) docs
222 the same application will try to turn links back to local links
223 (where those docs are installed).
224 </para>
225 </listitem>
226 </orderedlist>
228 </sect1>
230 <sect1 id="gettinggtkdoc">
231 <title>Getting GTK-Doc</title>
233 <sect2 id="requirements">
234 <title>Requirements</title>
235 <para>
236 <guilabel>Perl v5</guilabel> - the main scripts are in Perl.
237 </para>
238 <para>
239 <guilabel>DocBook DTD v3.0</guilabel> - This is the DocBook SGML DTD.
240 <ulink url="http://www.ora.com/davenport" type="http">http://www.ora.com/davenport</ulink>
241 </para>
242 <para>
243 <guilabel>Jade v1.1</guilabel> - This is a DSSSL processor for converting SGML to various formats.
244 <ulink url="http://www.jclark.com/jade" type="http">http://www.jclark.com/jade</ulink>
245 </para>
246 <para>
247 <guilabel>Modular DocBook Stylesheets</guilabel>
248 This is the DSSSL code to convert DocBook to HTML (and a few other
249 formats). It's used together with jade.
250 I've customized the DSSSL code slightly, in gtk-doc.dsl, to colour
251 the program code listings/declarations, and to support global
252 cross-reference indices in the generated HTML.
253 <ulink url="http://nwalsh.com/docbook/dsssl" type="http">http://nwalsh.com/docbook/dsssl</ulink>
254 </para>
255 <para>
256 <guilabel>docbook-to-man</guilabel> - if you want to create man pages from the DocBook.
257 I've customized the 'translation spec' slightly, to capitalise section
258 headings and add the 'GTK Library' title at the top of the pages and the
259 revision date at the bottom.
260 There is a link to this on <ulink url="http://www.ora.com/davenport" type="http">http://www.ora.com/davenport</ulink>
261 NOTE: This does not work yet.
262 </para>
263 </sect2>
265 <sect2 id="installation">
266 <title>Installation</title>
267 <para>
268 There is no standard place where the DocBook Modular Stylesheets are installed.
269 </para>
270 <para>
271 gtk-doc's configure script searches these 3 directories automatically:
272 </para>
273 <para>
274 <filename> /usr/lib/sgml/stylesheets/nwalsh-modular </filename> (used by RedHat)
275 </para>
276 <para>
277 <filename> /usr/lib/dsssl/stylesheets/docbook </filename> (used by Debian)
278 </para>
279 <para>
280 <filename> /usr/share/sgml/docbkdsl </filename> (used by SuSE)
281 </para>
282 <para>
283 If you have the stylesheets installed somewhere else, you need to configure
284 gtk-doc using the option:
285 <command> --with-dsssl-dir=<PATH_TO_TOPLEVEL_STYLESHEETS_DIR> </command>
286 </para>
287 </sect2>
289 </sect1>
291 <!-- not realy worth a section
292 <sect1 id="whentousegtkdoc">
293 <title>When to Use GTK-Doc</title>
295 <para>
296 (What things GTK-Doc should, and shouldn't, be used for.)
297 (- ???)
298 (+ Tutorials)
299 </para>
301 </sect1>
302 -->
304 <sect1 id="aboutgtkdoc">
305 <title>About GTK-Doc</title>
307 <para>
308 (FIXME)
309 </para>
311 <para>
312 (History, authors, web pages, license, future plans,
313 comparison with other similar systems.)
314 </para>
316 </sect1>
318 <sect1 id="aboutthismanual">
319 <title>About this Manual</title>
321 <para>
322 (FIXME)
323 </para>
325 <para>
326 (who it is meant for, where you can get it, license)
327 </para>
329 </sect1>
331 </chapter>
333 <chapter id="settingup">
334 <title>Setting up your project</title>
336 <para>
337 The next sections describe what steps to perform to integrate GTK-Doc into
338 your project. Theses section assume we work on a project called 'meep'.
339 This project contains a library called 'libmeep' and
340 an end-user app called 'meeper'.
341 </para>
343 <sect1 id="settingup_docfiles">
344 <title>Setting up a skeleton documentation</title>
346 <para>
347 Under your top-level project directory create folders called docs/reference
348 (this way you can also have docs/help for end-user documentation).
349 It is recommended to create another subdirectory with the name of the doc-package.
350 For packages with just one library this step is not necessary.
351 </para>
353 <para>
354 This can then look as show below:
355 <example><title>Example directory structure</title>
356 <programlisting>
357 <![CDATA[
358 meep/
359 docs/
360 reference/
361 libmeep/
362 meeper/
363 src/
364 libmeep/
365 meeper/
366 ]]>
367 </programlisting>
368 </example>
369 </para>
370 </sect1>
372 <sect1 id="settingup_autoconf">
373 <title>Integration with autoconf</title>
375 <para>
376 Very easy! Just add one line to your <filename>configure.ac</filename> script.
377 </para>
379 <para>
380 <example><title>Integration with autoconf</title>
381 <programlisting>
382 <![CDATA[
383 # check for gtk-doc
384 GTK_DOC_CHECK(1.9)
385 ]]>
386 </programlisting>
387 </example>
388 </para>
390 <para>
391 Besides checking for the required Gtk-Doc version, this adds two configure
392 switches:
393 </para>
394 <orderedlist>
395 <listitem><para>--with-html-dir=PATH : path to installed docs</para></listitem>
396 <listitem><para>--enable-gtk-doc : use gtk-doc to build documentation</para></listitem>
397 </orderedlist>
399 <important>
400 <para>
401 Gtk-Doc is disabled by default! Remember to pass the option
402 <option>'--enable-gtk-doc'</option> to the next
403 <filename>configure</filename> run. Otherwise pregenerated documentation is installed
404 (which makes sense for users but not for developers).
405 </para>
406 </important>
408 <para>
409 Furthermore it is recommended that you have the following line inside
410 you <filename>configure.ac</filename> script.
411 This allows <filename>gtkdocize</filename> to automatically copy the
412 macro definition for <function>GTK_DOC_CHECK</function> to your project.
413 </para>
415 <para>
416 <example><title>Preparation for gtkdocize</title>
417 <programlisting>
418 <![CDATA[
419 AC_CONFIG_MACRO_DIR(m4)
420 ]]>
421 </programlisting>
422 </example>
423 </para>
424 </sect1>
426 <sect1 id="settingup_automake">
427 <title>Integration with automake</title>
429 <para>
430 First copy the <filename>Makefile.am</filename> from the examples subdirectory of the gtkdoc-sources
431 to your project's API documentation directory (
432 <filename class='directory'>./docs/reference/<package></filename>).
433 If you have multiple doc-packages repeat this for each one.
434 </para>
436 <para>
437 The next step is to edit the setting inside the <filename>Makefile.am</filename>.
438 All the settings have a comment above that describes their purpose.
439 Most settings are extra flags passed to the respective tools. Every tool
440 has a variable of the form <option><TOOLNAME>_OPTIONS</option>.
441 All the tools support <option>--help</option> to list the supported
442 parameters.
443 </para>
445 <!-- FIXME: explain options ? -->
447 <para>
448 You may also want to enable gtk-doc for the distcheckmake target. Just
449 add then one-liner show in the next example to you top-level
450 <filename>Makefile.am</filename>:
451 </para>
453 <para>
454 <example><title>Enable gtk-doc during make distcheck</title>
455 <programlisting>
456 <![CDATA[
457 DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc
458 ]]>
459 </programlisting>
460 </example>
461 </para>
463 </sect1>
465 <sect1 id="settingup_autogen">
466 <title>Integration with autogen</title>
468 <para>
469 Most projects will have an <filename>autogen.sh</filename> script to
470 setup the build infrastructure after a checkout from version control
471 system (such as cvs). Gtk-Doc comes with a tool called
472 <filename>gtkdocize</filename> which can be used in such a script.
473 It should be run before autoheader, automake or autoconf.
474 </para>
476 <para>
477 <example><title>Running gtkdocize from autogen.sh</title>
478 <programlisting>
479 <![CDATA[
480 gtkdocize || exit 1
481 ]]>
482 </programlisting>
483 </example>
484 </para>
486 <para>
487 When running <filename>gtkdocize</filename> it copies
488 <filename>gtk-doc.make</filename> to you project root (or any directory
489 specified by the --docdir option). If also check you configure script
490 for the <function>GTK_DOC_CHECK</function> invocation.
491 </para>
493 <para>
494 Historically gtk-doc was gerating template files where developers entered the docs.
495 this turned out to be not so good. Since a few version gtk-doc could also get all
496 the information from source comments.
497 Since gtk-doc 1.9 the templates can be avoided. We encourage people to keep
498 documentation in the code. <application>gtkdocize</application> supports now
499 a --flavour=no-tmpl option that chooses a makefile that skips tmpl usage totally.
500 If you have never changed file in tmpl by hand, please remove the dir once.
501 </para>
502 </sect1>
504 <sect1 id="settingup_firstrun">
505 <title>Running the doc build</title>
507 <para>
508 After the previous steps it's time to run the build. First we need to
509 rerun <filename>autogen.sh</filename>. If this script runs configure for
510 you, then give it the <option>--enable-gtk-doc</option> option.
511 Otherwise manually run <filename>configure</filename> with this option
512 afterwards.
513 </para>
514 <para>
515 The first make run generates several additional files in the doc-dirs.
516 The important ones are:
517 <filename><package>.types</filename>,
518 <filename><package>-docs.sgml</filename>,
519 <filename><package>-sections.txt</filename>.
520 </para>
521 <para>
522 <example><title>Running the doc build</title>
523 <programlisting>
524 <![CDATA[
525 ./autogen.sh --enable-gtk-doc
526 make
527 ]]>
528 </programlisting>
529 </example>
530 </para>
531 <para>
532 Now you can point your browser to <filename>docs/reference/<package>/index.html</filename>.
533 Yes, it's a bit disappointing still. But hang-on, during the next chapter we
534 tell you how to fill the pages with life.
535 </para>
536 </sect1>
538 <sect1 id="settingup_vcs">
539 <title>Integration with version control systems</title>
541 <para>
542 As a rule of the thumb, it's those files you edit, that should go under
543 version control. For typical projects it's these files:
544 <filename><package>.types</filename>
545 <filename><package>-docs.sgml</filename>
546 <filename><package>-sections.txt</filename>
547 <filename>Makefile.am</filename>
548 </para>
549 </sect1>
551 </chapter>
553 <chapter id="documenting">
554 <title>Documenting the code</title>
556 <para>
557 GTK-Doc uses source code comment with a special syntax for code documentation.
558 Further it retrieves information about your project structure from other
559 sources. During the next section you find all information about the syntax
560 of the comments.
561 </para>
563 <note>
564 <title>Documentation placement</title>
565 <para>
566 In the past most documentation had to be filled into files residing
567 inside the <filename>tmpl</filename> directory. This has the
568 disadvantages that the information is often not updated and also that
569 the file tend to cause conflicts with version control systems.
570 </para>
571 <para>
572 The avoid the aforementioned problems we suggest putting the
573 documentation inside the sources. This manual will only describe this
574 way of documenting code.
575 </para>
576 </note>
578 <!-- -->
580 <sect1 id="documenting_syntax">
581 <title>Documentation comments</title>
583 <para>
584 A multiline comment that starts with an additional '*' marks a
585 documentation block that will be processed by the Gtk-Doc tools.
586 <example><title>Gtk-Doc comment block</title>
587 <programlisting>
588 <![CDATA[
589 /**
590 * identifier:
591 * documentation ...
592 */
593 ]]>
594 </programlisting>
595 </example>
596 </para>
598 <para>
599 The 'identifier' is one line with the name of the item the comment is
600 related to. The syntax differs a little depending on the item.
601 (TODO add table showing identifiers)
602 </para>
604 <para>
605 The 'documentation' block is also different for each symbol type. Symbol
606 types that get parameters such as functions or macros have the parameter
607 description first followed by a blank line (just a '*').
608 Afterwards follows the detailed description. All lines (outside program-
609 listings and CDATA sections) just containing a ' *' (blank-asterisk) are
610 converted to paragraph breaks.
611 If you don't want a paragraph break, change that into ' * '
612 (blank-asterisk-blank-blank).
613 </para>
615 <para>
616 One advantage of hyper-text over plain-text is the ability to have links
617 in the document. Writing the correct markup for a link can be tedious
618 though. Gtk-Doc comes to help by providing several useful abbreviations.
619 <itemizedlist>
620 <listitem>
621 <para>
622 Use function() to refer to functions or macros which take arguments.
623 </para>
624 </listitem>
625 <listitem>
626 <para>
627 Use @param to refer to parameters. Also use this when referring to
628 parameters of other functions, related to the one being described.
629 </para>
630 </listitem>
631 <listitem>
632 <para>
633 Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS.
634 </para>
635 </listitem>
636 <listitem>
637 <para>
638 Use #symbol to refer to other types of symbol, e.g. structs and
639 enums and macros which don't take arguments.
640 </para>
641 </listitem>
642 <listitem>
643 <para>
644 Use #Object::signal to refer to a GObject signal
645 </para>
646 </listitem>
647 <listitem>
648 <para>
649 Use #Object:property to refer to a GObject property
650 </para>
651 </listitem>
652 <listitem>
653 <para>
654 Use #Struct.field to refer to a field inside a structure.
655 </para>
656 </listitem>
657 </itemizedlist>
658 </para>
660 <tip>
661 <para>
662 If you need to use the special characters '()', '@', '%', or '#'
663 in your documentation without gtk-doc changing them you can use the
664 XML entities
665 "&lpar;", "&rpar;", "&commat;", "&percnt;" and
666 "&num;" respectively or escape them with a backslash '\'.
667 </para>
668 </tip>
670 <para>
671 DocBook can do more that just links. One can also have lists, tables and
672 examples. To enable the usage of SGML/XML tags inside doc-comments you
673 need to have <option>--sgml-mode</option> in the variable
674 <symbol>MKDB_OPTIONS</symbol> inside <filename>Makefile.am</filename>.
675 </para>
677 <tip>
678 <para>
679 As already mentioned earlier Gtk-Doc is for documenting public API. Thus
680 one cannot write documentation for static symbols. Nevertheless it is good
681 to comment those symbols too. This helps other to understand you code.
682 Therefore we recommend to comment these using normal comments (without the
683 2nd '*' in the first line).
684 If later the function needs to be made public, all one needs to do is to
685 add another '*' in the comment block and insert the symbol name at the
686 right place inside the sections file.
687 </para>
688 </tip>
689 </sect1>
691 <sect1 id="documenting_sections">
692 <title>Documenting sections</title>
694 <para>
695 Each section of the documentation contains information about one class
696 or module. To introduce the component one can write a section block.
697 The short description is also used inside the table of contents.
698 </para>
700 <para>
701 <example><title>Section comment block</title>
702 <programlisting>
703 <![CDATA[
704 /**
705 * SECTION:meepapp
706 * @short_description: the application class
707 * @see_also: #MeepSettings
708 * @stability: Stable
709 * @include: meep/app.h
710 *
711 * The application class handles ...
712 */
713 ]]>
714 </programlisting>
715 </example>
716 </para>
718 <variablelist>
719 <varlistentry>
720 <term>SECTION:<name></term>
721 <listitem>
722 <para>
723 The name links the section documentation to the respective part in
724 the <filename><package>-sections.txt</filename> file. The
725 name give here should match the <FILE> tag in the
726 <filename><package>-sections.txt</filename> file.
727 </para>
728 </listitem>
729 </varlistentry>
730 <varlistentry>
731 <term>@short_description</term>
732 <listitem>
733 <para>
734 A one line description of the section, that later will appear after
735 the links in the TOC and at the top of the section page.
736 </para>
737 </listitem>
738 </varlistentry>
739 <varlistentry>
740 <term>@see_also</term>
741 <listitem>
742 <para>
743 A list of symbols that are related to this section..
744 </para>
745 </listitem>
746 </varlistentry>
747 <varlistentry>
748 <term>@stability</term>
749 <listitem>
750 <para>
751 A informal description of the stability level this API has.
752 We recommend the use of one of these terms:
753 <itemizedlist>
754 <listitem>
755 <para>
756 Stable
757 - The intention of a Stable interface is to enable arbitrary
758 third parties to develop applications to these interfaces,
759 release them, and have confidence that they will run on all
760 minor releases of the product (after the one in which the
761 interface was introduced, and within the same major release).
762 Even at a major release, incompatible changes are expected
763 to be rare, and to have strong justifications.
764 </para>
765 </listitem>
766 <listitem>
767 <para>
768 Unstable
769 - Unstable interfaces are experimental or transitional.
770 They are typically used to give outside developers early
771 access to new or rapidly changing technology, or to provide
772 an interim solution to a problem where a more general
773 solution is anticipated.
774 No claims are made about either source or binary
775 compatibility from one minor release to the next.
776 </para>
777 </listitem>
778 <listitem>
779 <para>
780 Private
781 - An interface that can be used within the GNOME stack
782 itself, but that is not documented for end-users. Such
783 functions should only be used in specified and documented
784 ways.
785 </para>
786 </listitem>
787 <listitem>
788 <para>
789 Internal
790 - An interface that is internal to a module and does not
791 require end-user documentation. Functions that are
792 undocumented are assumed to be Internal.
793 </para>
794 </listitem>
795 </itemizedlist>
796 </para>
797 </listitem>
798 </varlistentry>
799 <varlistentry>
800 <term>@include</term>
801 <listitem>
802 <para>
803 The <literal>#include</literal> files to show in the section
804 synopsis (a comma separated list), overriding the global
805 value from the <link linkend="metafiles_sections">section
806 file</link> or command line. This item is optional.
807 </para>
808 </listitem>
809 </varlistentry>
810 </variablelist>
812 <para>
813 FIXME
814 having @title here, would put this title into a newly generated section
815 file, but later would be obsolete (right?)
816 </para>
818 <tip>
819 <para>
820 To avoid unnecessary recompilation after doc-changes put the section
821 docs into the c-source where possible.
822 </para>
823 </tip>
825 </sect1>
827 <sect1 id="documenting_symbols">
828 <title>Documenting symbols</title>
830 <para>
831 Each symbol (function, macro, struct, enum, signal and property) is
832 documented in a separate block. The block is best placed close to the
833 definition of the symbols so that it is easy to keep them in sync.
834 Thus function are usually documented in the c-source and macros, struct
835 and enum in the header file.
836 </para>
838 <para>
839 <example><title>Function comment block</title>
840 <programlisting>
841 <![CDATA[
842 /**
843 * function_name:
844 * @par1: description of parameter 1. These can extend over more than
845 * one line.
846 * @par2: description of parameter 2
847 *
848 * The function description goes here. You can use @par1 to refer to parameters
849 * so that they are highlighted in the output. You can also use %constant
850 * for constants, function_name2() for functions and #GtkWidget for links to
851 * other declarations (which may be documented elsewhere).
852 *
853 * Returns: an integer.
854 */
855 ]]>
856 </programlisting>
857 </example>
858 </para>
860 <variablelist>
861 <varlistentry>
862 <term>Returns:</term>
863 <listitem>
864 <para>
865 Paragraph describing the returned result.
866 </para>
867 </listitem>
868 </varlistentry>
869 <varlistentry>
870 <term>Deprecated:</term>
871 <listitem>
872 <para>
873 Paragraph denoting that this function should no be used anymore.
874 The description should point the reader to the new API.
875 </para>
876 </listitem>
877 </varlistentry>
878 <varlistentry>
879 <term>Since:</term>
880 <listitem>
881 <para>
882 Description since which version of the code the API is available.
883 </para>
884 </listitem>
885 </varlistentry>
886 </variablelist>
888 <para>
889 Gtk-doc assumes all symbols (macros, functions) starting with '_' are
890 private. They are treated like static functions.
891 </para>
893 <para>
894 (FIXME)
895 (stability)
896 (glib-enums, ...)
897 </para>
899 <example><title>Property comment block</title>
900 <programlisting>
901 <![CDATA[
902 /**
903 * SomeWidget:some-property:
904 *
905 * Here you can document a property.
906 */
907 g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
908 ]]></programlisting>
909 </example>
911 <example><title>Signal comment block</title>
912 <programlisting>
913 <![CDATA[
914 /**
915 * FooWidget::foobarized:
916 * @widget: the widget that received the signal
917 * @foo: some foo
918 * @bar: some bar
919 *
920 * The ::foobarized signal is emitted each time someone tries to foobarize @widget.
921 */
922 foo_signals[FOOBARIZE] =
923 g_signal_new ("foobarize",
924 ...
925 ]]></programlisting>
926 </example>
928 <example><title>Struct comment block</title>
929 <programlisting>
930 <![CDATA[
931 /**
932 * FooWidget:
933 * @bar: some #gboolean
934 *
935 * This is the best widget, ever.
936 */
937 typedef struct _FooWidget {
938 GtkWidget parent;
939 /*< public >*/
940 gboolean bar;
941 } FooWidget;
942 ]]></programlisting>
943 </example>
944 </sect1>
946 <sect1 id="documenting_docbook">
947 <title>Useful DocBook tags</title>
949 <para>
950 Here are some DocBook tags which are most useful when documenting the
951 code.
952 </para>
954 <para>
955 To link to another section in the GTK docs:
957 <informalexample>
958 <programlisting>
959 <![CDATA[
960 <link linkend="glib-Hash-Tables">Hash Tables</link>
961 ]]>
962 </programlisting>
963 </informalexample>
964 The linkend is the SGML id on the top item of the page you want to link to.
965 For most pages this is currently the part ("gtk", "gdk", glib") and then
966 the page title ("Hash Tables"). For widgets it is just the class name.
967 Spaces and underscores are converted to '-' to conform to SGML.
968 </para>
970 <para>
971 To refer to an external function, e.g. a standard C function:
972 <informalexample>
973 <programlisting>
974 <![CDATA[
975 <function>...</function>
976 ]]>
977 </programlisting>
978 </informalexample>
979 </para>
981 <para>
982 To include example code:
983 <informalexample>
984 <programlisting>
985 <![CDATA[
986 <example>
987 <title>Using a GHashTable.</title>
988 <programlisting>
989 ...
990 </programlisting>
991 </example>
992 ]]>
993 </programlisting>
994 </informalexample>
995 or possibly this, for very short code fragments which don't need a title:
996 <informalexample>
997 <programlisting>
998 <![CDATA[
999 <informalexample>
1000 <programlisting>
1001 ...
1002 </programlisting>
1003 </informalexample>
1004 ]]>
1005 </programlisting>
1006 </informalexample>
1007 For the latter gtk-doc also supports an abbreviation:
1008 <![CDATA[
1009 |[
1010 ...
1011 ]|
1012 ]]>
1013 </para>
1015 <para>
1016 To include bulleted lists:
1017 <informalexample>
1018 <programlisting>
1019 <![CDATA[
1020 <itemizedlist>
1021 <listitem>
1022 <para>
1023 ...
1024 </para>
1025 </listitem>
1026 <listitem>
1027 <para>
1028 ...
1029 </para>
1030 </listitem>
1031 </itemizedlist>
1032 ]]>
1033 </programlisting>
1034 </informalexample>
1035 </para>
1037 <para>
1038 To include a note which stands out from the text:
1039 <informalexample>
1040 <programlisting>
1041 <![CDATA[
1042 <note>
1043 <para>
1044 Make sure you free the data after use.
1045 </para>
1046 </note>
1047 ]]>
1048 </programlisting>
1049 </informalexample>
1050 </para>
1052 <para>
1053 To refer to a type:
1054 <informalexample>
1055 <programlisting>
1056 <![CDATA[
1057 <type>unsigned char</type>
1058 ]]>
1059 </programlisting>
1060 </informalexample>
1061 </para>
1063 <para>
1064 To refer to an external structure (not one described in the GTK docs):
1065 <informalexample>
1066 <programlisting>
1067 <![CDATA[
1068 <structname>XFontStruct</structname>
1069 ]]>
1070 </programlisting>
1071 </informalexample>
1072 </para>
1074 <para>
1075 To refer to a field of a structure:
1076 <informalexample>
1077 <programlisting>
1078 <![CDATA[
1079 <structfield>len</structfield>
1080 ]]>
1081 </programlisting>
1082 </informalexample>
1083 </para>
1085 <para>
1086 To refer to a class name, we could possibly use:
1087 <informalexample>
1088 <programlisting>
1089 <![CDATA[
1090 <classname>GtkWidget</classname>
1091 ]]>
1092 </programlisting>
1093 </informalexample>
1094 but you'll probably be using #GtkWidget instead (to automatically create
1095 a link to the GtkWidget page - see <link linkend="documenting_syntax">the abbreviations</link>).
1096 </para>
1098 <para>
1099 To emphasize text:
1100 <informalexample>
1101 <programlisting>
1102 <![CDATA[
1103 <emphasis>This is important</emphasis>
1104 ]]>
1105 </programlisting>
1106 </informalexample>
1107 </para>
1109 <para>
1110 For filenames use:
1111 <informalexample>
1112 <programlisting>
1113 <![CDATA[
1114 <filename>/home/user/documents</filename>
1115 ]]>
1116 </programlisting>
1117 </informalexample>
1118 </para>
1120 </sect1>
1121 </chapter>
1123 <chapter id="metafiles">
1124 <title>Filling the extra files</title>
1126 <para>
1127 There are a couple of extra files, that need to be maintained along with
1128 the inline source code comments:
1129 <filename><package>.types</filename>,
1130 <filename><package>-docs.sgml</filename>,
1131 <filename><package>-sections.txt</filename>.
1132 </para>
1134 <sect1 id="metafiles_types">
1135 <title>Editing the types file</title>
1137 <para>
1138 If your library or application includes GtkObjects/GObjects, you want
1139 their signals, arguments/parameters and position in the hierarchy to be
1140 shown in the documentation. All you need to do, is to list the
1141 <function>xxx_get_type</function> functions together with their include
1142 inside the <filename><package>.types</filename> file.
1143 </para>
1145 <para>
1146 <example><title>Example types file snippet</title>
1147 <programlisting>
1148 <![CDATA[
1149 #include <gtk/gtk.h>
1151 gtk_accel_label_get_type
1152 gtk_adjustment_get_type
1153 gtk_alignment_get_type
1154 gtk_arrow_get_type
1155 ]]>
1156 </programlisting>
1157 </example>
1158 </para>
1160 <para>
1161 Since gtk-doc 1.8 <application>gtkdoc-scan</application> can generate this list for you.
1162 Just add "--rebuild-types" to SCAN_OPTIONS in <filename>Makefile.am</filename>. If you
1163 use this approach you should not dist the types file nor have it under version control.
1164 </para>
1166 </sect1>
1168 <sect1 id="metafiles_master">
1169 <title>Editing the master document</title>
1171 <para>
1172 Gtk-Doc produces documentation in DocBook SGML/XML. When processing the
1173 inline source comments, the Gtk-Doc tools generate one documentation
1174 page per class or module as a separate file. The master document
1175 includes them and place them in a order.
1176 </para>
1178 <para>
1179 While Gtk-Doc creates a template master document for you, later run will
1180 not touch it again. This means that one can freely structure the
1181 documentation. That includes grouping pages and adding extra pages.
1182 Gtk-doc has now a test suite, where also the master-document is recreated from scratch.
1183 Its a good idea to look at this from time to time to see if there are some new goodies
1184 introduced there.
1185 </para>
1187 <tip>
1188 <para>
1189 Do not create tutorials as extra documents. Just write extra chapters.
1190 The benefit of directly embedding the tutorial for your library into
1191 the API documentation is that it is easy to link for the tutorial to
1192 symbol documentation. Apart chances are higher that the tutorial gets
1193 updates along with the library.
1194 </para>
1195 </tip>
1197 <para>
1198 So what are the things to change inside the master document? For a start
1199 is only a little. There are some placeholders (text in square brackets)
1200 there which you should take care of.
1201 </para>
1203 <para>
1204 <example><title>Master document header</title>
1205 <programlisting>
1206 <![CDATA[
1207 <bookinfo>
1208 <title>MODULENAME Reference Manual</title>
1209 <releaseinfo>
1210 for MODULENAME [VERSION]
1211 The latest version of this documentation can be found on-line at
1212 <ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html">http://[SERVER]/MODULENAME/</ulink>.
1213 </releaseinfo>
1214 </bookinfo>
1216 <chapter>
1217 <title>[Insert title here]</title>
1218 ]]>
1219 </programlisting>
1220 </example>
1221 </para>
1223 </sect1>
1225 <sect1 id="metafiles_sections">
1226 <title>Editing the section file</title>
1228 <para>
1229 The section file is used to organise the documentation output by
1230 Gtk-Doc. Here one specifies which symbol belongs to which module or
1231 class and control the visibility (public or private).
1232 </para>
1234 <para>
1235 The section file is a plain test file with xml like syntax (using tags).
1236 Blank lines are ignored and lines starting with a '#' are treated as
1237 comment lines.
1238 </para>
1240 <para>
1241 The <FILE> ... </FILE> tag is used to specify the file name,
1242 without any suffix. For example, using '<FILE>gnome-config</FILE>'
1243 will result in the section declarations being output in the template
1244 file <filename>tmpl/gnome-config.sgml</filename>, which will be
1245 converted into the DocBook SGML file <filename>sgml/gnome-config.sgml</filename>
1246 or .DocBook XML file <filename>xml/gnome-config.xml</filename>.
1247 (The name of the html file is based on the module name and the section
1248 title, or for gobjects it is based on the gobjects class name converted
1249 to lower case).
1250 </para>
1252 <para>
1253 The <TITLE> ... </TITLE> tag is used to specify the title of
1254 the section. It is only useful before the templates are initially
1255 created, since the title set in the template file overrides this.
1256 </para>
1258 <para>
1259 You can group items in the section by using the <SUBSECTION> tag.
1260 Currently it outputs a blank line between subsections in the synopsis
1261 section.
1262 You can also use <SUBSECTION Standard> for standard GObject
1263 declarations (e.g. the functions like g_object_get_type and macros like
1264 G_OBJECT(), G_IS_OBJECT() etc.).
1265 Currently these are left out of the documentation.
1266 You can also use <SUBSECTION Private> for private declarations
1267 which will not be output (It is a handy way to avoid warning messages
1268 about unused declarations.).
1269 If your library contains private types which you don't want to appear in
1270 the object hierarchy and the list of implemented or required interfaces,
1271 add them to a Private subsection.
1272 </para>
1274 <para>
1275 You can also use <INCLUDE> ... </INCLUDE> to specify the
1276 #include files which are shown in the synopsis sections.
1277 It contains a comma-separate list of #include files, without the angle
1278 brackets. If you set it outside of any sections, it acts for all
1279 sections until the end of the file. If you set it within a section, it
1280 only applies to that section.
1281 </para>
1283 </sect1>
1285 </chapter>
1287 <chapter id="reports">
1288 <title>Controlling the result</title>
1290 <para>
1291 A Gtk-Doc run generates report files inside the documentation directory.
1292 The generated files are named:
1293 <filename><package>-undocumented.txt</filename>,
1294 <filename><package>-undeclared.txt</filename> and
1295 <filename><package>-unused.txt</filename>.
1296 All those are plain text files that can be viewed and postprocessed easily.
1297 </para>
1299 <para>
1300 The <filename><package>-undocumented.txt</filename> file starts with
1301 the documentation coverage summary. Below are two sections divided by
1302 blank lines. The first section lists undocumented or incomplete symbols.
1303 The second section does the same for section docs. Incomplete entries are
1304 those, which have documentation, but where e.g. a new parameter has been
1305 added.
1306 </para>
1308 <para>
1309 The <filename><package>-undeclared.txt</filename> file lists symbols
1310 given in the <filename><package>-sections.txt</filename> but not
1311 found in the sources. Check if they have been removed or if they are
1312 misspelled.
1313 </para>
1315 <para>
1316 The <filename><package>-unused.txt</filename> file lists symbol
1317 names, where the Gtk-Doc scanner has found documentation, but does not
1318 know where to put it. This means that the symbol has not yet been added to
1319 the <filename><package>-sections.txt</filename> file.
1320 </para>
1322 <tip>
1323 <para>
1324 Enable or add the <option>TESTS=$(GTKDOC_CHECK)</option> line in Makefile.am.
1325 If at least gtk-doc 1.9 is installed, this will run sanity checks during
1326 make check run.
1327 </para>
1328 </tip>
1330 </chapter>
1332 <chapter id="faq">
1333 <title>Frequently asked question</title>
1335 <segmentedlist>
1336 <?dbhtml list-presentation="list"?>
1337 <segtitle>Question</segtitle>
1338 <segtitle>Answer</segtitle>
1339 <seglistitem>
1340 <seg>No class hierarchy.</seg>
1341 <seg>The objects _get_type() function has not been entered into the <filename>.types</filename> file.</seg>
1342 </seglistitem>
1343 <seglistitem>
1344 <seg>Still no class hierarchy.</seg>
1345 <seg>Wrong naming in section file (see <ulink url="http://mail.gnome.org/archives/gtk-doc-list/2003-October/msg00006.html">explanation</ulink>)</seg>
1346 </seglistitem>
1347 <seglistitem>
1348 <seg>Damn, I have still no class hierarchy.</seg>
1349 <seg>Is the object name (name of the instance struct) part of the normal section (don't put this into Standard or Private).</seg>
1350 </seglistitem>
1351 <seglistitem>
1352 <seg>No symbol index.</seg>
1353 <seg>FIXME (<index> tag in main sgml file)</seg>
1354 </seglistitem>
1355 <seglistitem>
1356 <seg>Symbols are not linked to their doc-section.</seg>
1357 <seg>FIXME (added #,% or () ?)</seg>
1358 </seglistitem>
1359 <seglistitem>
1360 <seg>A new class does not appear in the docs.</seg>
1361 <seg>FIXME (section file, types file, main-sgml file)</seg>
1362 </seglistitem>
1363 <seglistitem>
1364 <seg>A new symbol does not appear in the docs.</seg>
1365 <seg>FIXME (section file, proper doc comment)</seg>
1366 </seglistitem>
1368 <!-- gtk-doc warnings: -->
1369 <seglistitem>
1370 <seg>Parameter described in source code comment block but does not exist</seg>
1371 <seg>Check if the prototype in the header has different parameter names as in the source.</seg>
1372 </seglistitem>
1373 <!-- docbook warnings: -->
1374 <seglistitem>
1375 <seg>multiple "IDs" for constraint linkend: XYZ</seg>
1376 <seg>Symbol XYZ appears twice in -sections.txt file.</seg>
1377 </seglistitem>
1378 <seglistitem>
1379 <seg>Element typename in namespace '' encountered in para, but no template matches.</seg>
1380 <seg />
1381 </seglistitem>
1382 </segmentedlist>
1383 </chapter>
1385 <!-- ======== Appendix: FDL ================================== -->
1386 &FDL;
1388 </book>