GNOME API documentation is done using the gtk-doc package, which performs two basic tasks. First, it automates the creation of basic API documentation from source code and comments. Second, it provides an easy way for people to change and add to the auto-generated documentation without having to edit the source code itself.
The gtk-doc tools are not run by hand: you simply paste a few lines into your Makefiles, and then when you run a make install, a set of templates and documents are created. If you edit the templates, the tools will incorporate those changes into the documents the next time you build.
Tip:
The libglade and gtk+ modules in GNOME CVS are excellent examples of GNOME development methods, including gtk-doc usage.
Final document output is in DocBook XML, just like user documents. The intermediate templates are XML-like but are not well-formed or valid XML documents.
The gtk-doc package requires the DocBook stylesheets and the opensp XML/SGML parsing tools, as well as Perl. Emacs users may find it helpful to use the XSL major mode provided by the xslide package.
These instructions are the same as the ones in the file "setting-up.txt" from the gtk-doc module in GNOME CVS. They assume that you will be using automake and autoconf.
That's it. When you build the software, the API docs will be generated in the docs/reference directory.
Tip:
In GNOME projects, general developer documentation is usually stored in the "docs" directory of the project, and API documentation in the "docs/reference" directory. User documentation typically goes into the "help" directory.
When you build your project with gtk-doc, specially formatted comments are read and converted to documentation. What's the special format?
To document a function:
If you use emacs, you can add this elisp macro to your .emacs file, and use the shortcuts C-x4h or M-x gnome-doc-insert to put the right comment structure in for you.
The comment block will look like this:
/** * function_name: * @par1: description of parameter 1. These can extend over more than * one line. * @par2: description of parameter 2 * * The function description goes here. * * Returns: an integer. */
Changes to the template files are recognized every time you rebuild the documentation, but changes to the comment blocks in code are not. To force gtk-doc to rescan the code, remove the *.stamp files in the directory where gtk-doc was called, then rebuild.
In the XML templates and in the comment blocks, you can use special syntax to highlight important pieces of information and link to other sections of the document.
The final output docs will highlight the words denoted with the syntax, and if possible link to the portions of the document where they are covered.
By default, gtk-doc structures the documentation it produces using the .h and .c files in your project: each file gets its own section in the document. To adjust the structure to fit your needs, edit the file myproject-sections.txt (the name will vary with your project name, of course).
To begin a new section or subsection of your document, place a <SECTION> and <SUBSECTION> tag on its own line. Each section or subsection should contain a set of related enums, declarations, functions, or macros. In general, place enums after the first function that uses them.If you have private objects that you do not wish to cover in your documentation, add a <SUBSECTION_private> at the end of the section where they appear. The final output will not include those declarations. In addition, the next time you run the make templates command, the declarations will be removed from the template files as well.
DocBook XML allows you a lot of flexibility. A complete DocBook reference is available at docbook.org, but for the most part, you won't need more than a few tags.
Tip:
The XML template files can be found in the tmpl/ directory. If you followed the GNOME default, that will be myproject/docs/reference/tmpl/.
Some of the most commonly used tags are:
Tip:
Normally, greater-than and less-than symbols in comment blocks are converted to ">" and "<" in the XML, for display as > and < in the final, human-readable display. To use XML tags in your comment blocks, use the --sgml-mode flag in your Makefiles. For example, gtk+ uses the line MKDB_OPTIONS=--sgml-mode --output-format=xml, denoting that when generating DocBook, its output format is XML (the default) and that it expects to find tags in the comment blocks inside the code.