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