Monthly Archives: February 2010

gnome, gtk+

Help improve Glib/GTK+ documentation

1 Comment

Update: Before start working in a module, check that It’s not already deprecated (like CList or CTree): these modules will be removed in GTK+3 so the doc migration is not needed

One of the tasks to improve the GTK+/Glib docs maintenance is to convert the documentation from templates (*.sgml) files into source-comments. This is a easy tasks that everybody can do.

All the process is documented here: [1]

Here a step-by-step example to help new contributors 😉

  1. Download GTK+ and gtk-doc source code:

    cd ~/git
    git clone git://git.gnome.org/gtk-doc
    git clone git://git.gnome.org/gtk+

  2. Execute gtk-doc script to convert the documentation

    cd gtk+/docs/reference/gtk
    ~/git/gtk-doc/tools/migratetmpl.pl –module=gtk

    This creates a “src” directory containing “*.c” files with all the comments.

  3. Copy and paste them to the right place.

    The section docs are best placed in the *.c file. Put them below the copyright header and the main includes (if there is no *.c file use the appropriate *.h file).
    All other comment blocks should be put directly above the definition of the symbol.

    For example, for GtkAccelGroup, we’d move the comments from gtk+/docs/reference/gtk/src/gtkaccelgroup.c to gtk+/gtkaccelgroup.c and gtk+/gtkaccelgroup.h

  4. Remove the template file:

    git rm docs/reference/gtk/tmpl/gtkaccelgroup.sgml

  5. Check that the documentation is correctly generated with:

    ./autogen –enable-gtk-doc
    make

    then go with a browser to docs/reference/gtk/html

  6. Send a patch to bugzilla and make it block 599599 for GTK+ or 589775 for Glib documentation.
  7. Update the wiki page [1] to avoid duplicate work

When adding the source code comment, its a good opportunity to review it a bit. Have a look on spelling and style. Is it really giving a helpful explanation what the function does, etc. Also improve cross references. The gtk-doc syntax of the comments is described in the gtk-doc manual [2].

You can take a look to the gtkwidget.h [3] and gtkwidget.c [4] code as an example.

[1] http://live.gnome.org/GTK+/TaskAPIDocMigration

[2] http://library.gnome.org/devel/gtk-doc-manual/unstable/documenting_syntax.html.en

[3] http://git.gnome.org/browse/gtk+/tree/gtk/gtkwidget.h

[4] http://git.gnome.org/browse/gtk+/tree/gtk/gtkwidget.c