forked from openkylin/gimp
129 lines
4.7 KiB
Plaintext
129 lines
4.7 KiB
Plaintext
|
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/.
|