Changes to authors.html, part II



Malcolm, Matthias, thank you for your input!

I've got what I think is pretty accurate, with the proviso that I'm not sure that adding that single line to your configure.in will really work.

Anyway, this seems like a reasonable overview of the docs process... I'm CC'ing the jeff waugh for his opinion on the commitability of this page (and the elisp it links to).

a.


Title: Writing Developer Documentation

Writing API Documentation

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.

File Formats and Requirements

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.

How to Set Up your Module to Use gtk-doc

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.

  1. Install the gtk-doc package. Depending on your distribution, this will be called gtk-doc, gtkdoc, or gtk-doc-tools.
  2. Create a directory in which you want your documentation to be built. The most commonly used directory is "docs/reference/".
  3. Edit Makefile.am files:
    • You will need one Makefile.am for each directory you have created.
    • List all subdirectories in the SUBDIRS section.
    • List all extra files in the EXTRA_DIST section.
    • Your toplevel Makefile.am file should contain the line MKDB_OPTIONS= output-mode=xml. If you want to use XML tags in your code comment blocks, add the--sgml-mode flag as well.
  4. Edit your configure.in:
    • Add the line GTK_DOC_CHECK([1.0]) to call the gtk-doc.m4 macro.
    • Make sure to add the Makefile.am files to your configure.in, so that the autotools will find them during the build.

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.

Commenting your Code to Produce Automated Docs

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.

Syntax in Comments and XML

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.

Organizing Your Documentation

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.

XML Syntax in the Template Files

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 "&gt;" and "&lt;" 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.



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]