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