80
<revnumber>1.16</revnumber>
81
<date>14 Jan 2011</date>
82
<authorinitials>sk</authorinitials>
83
<revremark>bugfixes, layout improvements</revremark>
80
86
<revnumber>1.15</revnumber>
81
87
<date>21 May 2010</date>
82
88
<authorinitials>sk</authorinitials>
169
175
code looking for declarations of functions, macros, enums, structs, and unions.
170
176
It creates the file <filename><module>-decl-list.txt</filename> containg a list of the
171
177
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>
178
are in. On the first run this file is copied to <filename><module>-sections.txt</filename>.
173
179
The author can rearrange the sections, and the order of the
174
180
declarations within them, to produce the final desired order.
175
181
The second file it generates is <filename><module>-decl.txt</filename>.
176
182
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
183
some reason one would like some symbols to show up in the docs, where
184
the full declaration cannot be found by the scanner or the declaration
179
185
should appear differently, one can place enties similar to the ones in
180
186
<filename><module>-decl.txt</filename> into <filename><module>-overrides.txt</filename>.
216
222
or <filename class='directory'>xml/</filename> subdirectory.
217
223
If the source code contains documentation on functions, using the
218
224
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.
225
it only reads docs from sources and introspection data. We recommend
222
229
<application>gtkdoc-mkhtml</application> turns the SGML/XML files into HTML
223
230
files in the <filename class='directory'>html/</filename> subdirectory.
224
231
Likewise <application>gtkdoc-mkpdf</application> turns the SGML/XML files into a PDF
225
docuemnt called <filename><package>.pdf</filename>.
232
document called <filename><package>.pdf</filename>.
228
235
Files in <filename class='directory'>sgml/</filename> or
360
367
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'.
368
your project. Theses sections assume we work on a project called 'meep'.
362
369
This project contains a library called 'libmeep' and
363
370
an end-user app called 'meeper'.
421
This will require all developers to have gtk-doc installed. If it is
422
okay for your project to have optional api-doc build setup, you can
423
solve this as below. Keep it as is, as gtkdocize is looking for
424
<function>GTK_DOC_CHECK</function> at the start of a line.
425
<example><title>Keep gtk-doc optional</title>
429
m4_ifdef([GTK_DOC_CHECK], [
430
GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
432
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
414
440
The first argument is used to check for the gtkdocversion at configure time.
415
441
The 2nd, optional argument is used by <application>gtkdocize</application>.
416
442
The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure switches:
463
The next step is to edit the setting inside the <filename>Makefile.am</filename>.
489
The next step is to edit the settings inside the <filename>Makefile.am</filename>.
464
490
All the settings have a comment above that describes their purpose.
465
491
Most settings are extra flags passed to the respective tools. Every tool
466
492
has a variable of the form <option><TOOLNAME>_OPTIONS</option>.
471
497
<!-- FIXME: explain options ? -->
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
500
You may also want to enable GTK-Doc for the distcheck make target. Just
501
add the one line shown in the next example to your top-level
476
502
<filename>Makefile.am</filename>:
513
539
When running <application>gtkdocize</application> it copies
514
<filename>gtk-doc.make</filename> to you project root (or any directory
540
<filename>gtk-doc.make</filename> to your project root (or any directory
515
541
specified by the <option>--docdir</option> option).
516
If also check you configure script for the <function>GTK_DOC_CHECK</function>
542
It also checks you configure script for the <function>GTK_DOC_CHECK</function>
543
invocation. This macro can be used to pass extra parameters to
544
<application>gtkdocize</application>.
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
548
Historically GTK-Doc was generating template files where developers entered the docs.
549
This turned out to be not so good (e.g. the need for having generated
550
files under version control).
551
Since GTK-Doc 1.9 the tools can get all the information from source comments
552
and thus the templates can be avoided. We encourage people to keep
525
553
documentation in the code. <application>gtkdocize</application> supports now
526
554
a <option>--flavour no-tmpl</option> option that chooses a makefile that skips
527
555
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>
556
invocation, they can be added also to an environment variable called <symbol>GTKDOCIZE_FLAGS</symbol>
529
557
or set as a 2nd parameter in <symbol>GTK_DOC_CHECK</symbol> macro in the configure script.
530
558
If you have never changed file in tmpl by hand and migrating from older gtkdoc versions,
531
559
please remove the dir (e.g. from version control system).
605
633
way of documenting code.
638
The scanner can handle the majority of c headers fine. In the case of
639
receiving warnings from the scanner that look like a special case, one can
640
hint GTK-Doc to skip over them.
641
<example><title>GTK-Doc comment block</title>
644
#ifndef __GTK_DOC_IGNORE__
645
/* unparseable code here */
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 '\'.
736
If you need to use the special characters '<', '>', '()', '@',
737
'%', or '#' in your documentation without GTK-Doc changing them you
738
can use the XML entities "&lt;", "&gt;", "&lpar;",
739
"&rpar;", "&commat;", "&percnt;" and "&num;"
740
respectively or escape them with a backslash '\'.
702
745
DocBook can do more that just links. One can also have lists, tables and
703
746
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>.
747
need to have <option>--xml-mode</option> or <option>--sgml-mode</option>
748
in the variable <symbol>MKDB_OPTIONS</symbol> inside
749
<filename>Makefile.am</filename>.
787
831
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>.
832
the <title> is used as a section_id and for other sections
833
it is <MODULE>-<title>.
890
934
Each symbol (function, macro, struct, enum, signal and property) is
891
935
documented in a separate block. The block is best placed close to the
892
936
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.
937
Thus functions are usually documented in the c-source and macros,
938
structs and enums in the header file.
897
941
<sect2><title>General tags</title>
1107
1151
Use <code>/*< private >*/</code> before the private struct fields
1108
1152
you want to hide. Use <code>/*< public >*/</code> for the reverse
1157
Struct comment blocks can also be used for GObjects and GObjectClasses.
1158
It is usualy a good idea to add a comment blco for a class, if it has
1159
vmethods (as this is how they can be documented). For the GObject
1160
itself one can use the related section docs, having a separate block
1161
for the instance struct would be useful if the instance has public
1162
fields. One disadvantage here is that this creates two index entries
1163
of the same name (the structure and the section).
1382
1436
GTK-Doc produces documentation in DocBook SGML/XML. When processing the
1383
1437
inline source comments, the GTK-Doc tools generate one documentation
1384
1438
page per class or module as a separate file. The master document
1385
includes them and place them in a order.
1439
includes them and place them in an order.
1480
1534
If your library contains private types which you don't want to appear in
1481
1535
the object hierarchy and the list of implemented or required interfaces,
1482
1536
add them to a Private subsection.
1537
Wheter you would place GObject and GObjectClass like structs in public
1538
or Standard section depends if they have public entries (variables,
1542
1599
One can also look at the files produced by the source code scanner:
1543
1600
<filename><package>-decl-list.txt</filename> and
1544
<filename><package>-decl.txt</filename>. The first and can be
1601
<filename><package>-decl.txt</filename>. The first one can be
1545
1602
compared with the section file if that is manualy maintained. The second
1546
1603
lists all declarations fromt he headers If a symbol is missing one could
1547
1604
check if this file contains it.
1560
1617
<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
1621
<chapter id="documenting-others">
1622
<title>Documenting other interfaces</title>
1625
So far we have been using GTK-Doc to document the API of code. The next
1626
sections contain suggestions how the tools can be used to document other
1630
<sect1 id="commandline-interfaces">
1631
<title>Commandline options and man pages</title>
1634
As one can generate man pages for a docbook refentry as well, it sounds
1635
like a good idea to use it for that purpose. This way the interface is
1636
part of the reference and one gets the man-page for free.
1639
<sect2 id="commandline-interfaces-file">
1640
<title>Document the tool</title>
1643
Create one refentry file per tool. Following
1644
<link linkend="settingup_docfiles">our example</link> we would call it
1645
<filename>meep/docs/reference/meeper/meep.xml</filename>. For the xml
1646
tags that should be used and can look at generated file in the xml
1647
subdirectory as well as examples e.g. in glib.
1651
<sect2 id="commandline-interfaces-configure">
1652
<title>Adding the extra configure check</title>
1655
<example><title>Extra configure checks</title>
1659
[AC_HELP_STRING([--enable-man],
1660
[regenerate man pages from Docbook [default=no]])],enable_man=yes,
1663
AC_PATH_PROG([XSLTPROC], [xsltproc])
1664
AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)
1671
<sect2 id="commandline-interfaces-make">
1672
<title>Adding the extra makefile rules</title>
1675
<example><title>Extra configure checks</title>
1685
@XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
1690
BUILT_EXTRA_DIST = $(man_MANS)
1691
EXTRA_DIST += meep.xml
1699
<sect1 id="dbus-interfaces">
1700
<title>DBus interfaces</title>
1703
(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html,
1704
http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)
1564
1710
<chapter id="faq">
1565
<title>Frequently asked question</title>
1711
<title>Frequently asked questions</title>
1567
1713
<segmentedlist>
1568
1714
<?dbhtml list-presentation="list"?>
added
removed
help/manual/C/gtk-doc-manual.xml
