Developers documentation using gtk-doc
--------------------------------------

The goal is to provide useful source documentation. Right now this is
limited to libgimp since that is the part that is used by third-party
coders (plug-in developers). Other parts of the code may follow later,
but not before libgimp is properly documented.


Principle
---------

The documentation is extracted out of the source using gtk-doc (see
http://www.gtk.org/gtk-doc/). We use a combination of comment blocks
embedded into the source and additional information added manually
into SGML template files.


Requirements
------------

GIMP release tarballs contain a complete set of precompiled HTML files
as well as DocBook XML files to create other formats. You only need
gtk-doc if you want to work on the documentation itself.  In that case
you will need the following utilities:

Perl v5 - Most of the scripts used are written in Perl.

libxslt & libxml2 (version >= 2.3.6)
    This is used to convert the XML templates to HTML.
    http://xmlsoft.org/

DocBook XML DTD v4.1.2
    http://www.docbook.org/

gtk-doc (version >= 1.0)
    This package automatically generates DocBook documentation from
    source and is able to convert it into HTML (and other formats).
    ftp://ftp.gtk.org/pub/gtk-doc/


You need to have all this properly setup. This includes the
availability of an XML catalog (/etc/xml/catalog) that tells the
XSLT processor where to look for locally installed DTDs. If that
file is missing, the XSLT processor will try to access the DTDs
online which will either fail or take forever. For this reason,
the docs are not built by default. If you think you have a working
setup, pass '--enable-gtk-doc' to configure.


How it works
------------

The following lines will only give you hints about how our system
works. You should have understood the principles of gtk-doc before you
touch it.

The system is already set up, so unless there are substantial changes
to the source e.g. new files were added, functions were added, renamed
or removed or parameters changed, there is no need to touch the
Makefile or any other files in the toplevel directory.

In most cases you will work on the documentation by adding or editing
comment blocks in the C source and by editing the template XML files
in the tmpl directory.

After you've done any changes to the documentation, running 'make'
should rebuild the documentation. This will however only work if
configure was called with the option '--enable-gtk-doc' and gtk-doc
was successfully found. If everything was set up correctly, running
'make' should do the trick and generate the XML and HTML files for
you. Since the dependencies are not perfect, you sometimes need to
call 'make clean; make' to force regeneration.


How to write proper gtk-doc comments
------------------------------------

Here are some hints on writing proper gtk-doc comments. They are based
on the gtk-doc documentation which comes with the gtk-doc source tree:

These are the comment blocks used in GIMP source files to document
functions (and macros, signals and properties, if you want).

/**
 * 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. You can use @par1 to refer to
 * parameters so that they are highlighted in the output. You can also
 * use %constant for constants, function_name2() for functions and
 * #GtkWidget for links to other declarations (which may be documented
 * elsewhere).
 * 
 * Return value: an integer.
 **/

The block starts with '/**'.
Each line starts with ' * '.

The second line is the function name, followed by a ':'. In order to
document signals in inline comments, use a name of the form
class::signal, e.g. GtkWidget::notify-child. For properties, use a
name of the form class:property, e.g. GtkAlignment:top-padding. Note
that gtk-doc expects the signal and property names to be spelled with
hyphens, not underlines.

Following the function name are the parameters, e.g. '@par1:' above.

A blank line MUST be used to separate parameter descriptions from the
main description (otherwise it is assumed to be a continuation of the
parameter description.)

After the main description is a 'Return value:' line to describe the
returned value of the function (if it is not void).


More information
----------------

Using the system as described above, you can write documentation
without any knowledge of DocBook XML, but when editing the templates
you will sometimes want to do a little extra structuring or
markup. The best source for information about DocBook seems to be
"DocBook: The Definitive Guide" which is available online at
http://www.docbook.org/tdg/html/.