glib/gtk+ API doc migration

Contents

glib/gtk+ API doc migration

Summary

Both glib and gtk+ have their api docs partially inline and partially in separate template files. The latter was the only way to do the documentation initially. Unfortunately is has several drawbacks:

documentation is often incomplete and outdated, as not all developers are aware of those files
the files are updates by gtk-doc, which leads to merge conflicts when developers use different tool versions
managing the template files is slower that extracting the docs directly

Tasks

The task is to convert the documentation from templates files into source-comments and remove the template file upon completion. Once a whole module is done the tmpl directory can be removed from vcs.

How To

Volunteers should assign files to themself, by adding their name and a timestamp to the module tables. Color should be used as shown below to indicate the progress.

State	Markup
todo	`<: #ff8080> todo`
assigned	`<: #ffc849> name and date`
done	`<: #80ff80> name (and link to revision)`
not needed	`<: #80ff80> not needed`

It is a good idea to also tell people on #gtk+ on gimpnet that one plans to move some docs, so that they avoid touching those files. Ideally also get one of the maintainers to approve and apply the changes.

Template docs are located under <project>/docs/reference/<module>/tmpl/*.sgml in the source tree. For each template one need to indentify what sources contain the code for the documentation in the template.

To ease the work, StefanKost has done a tool in gtk-doc that converts template files to the sourcecode comment format.

> cd glib/docs/reference/gobject
> ~/projects/gtk-doc/tools/migratetmpl.pl --module=gobject

This creates a "src" directory containing "*.c" files with all the comments. 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.

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.

Once all documentation from a template has been moved, the template should be removed from svn and the file added to the ignore list.

svn delete --force tmpl/xxx.sgml
svn propedit svn:ignore tmpl
<add "xxx.sgml" to the list>
<svn commit>

Things to watch out for: If a function allocates memory, please check the documentation and be sure to mention how to release said memory. Most of the time this will be using gtk_widget_destroy() or g_object_unref() or g_free(), but this may not always be the case. Gtk+ may need special attention on this regard. Functionality that is deprecated should be clearly marked as such.

Modules

# create initial tables
for file in `ls -1 gio/tmpl/*.sgml | sed 's/\w*\/tmpl\///' | sort`; do printf "||%-30s||<bgcolor="#ff8080">todo                    ||\n" $file; done

GLIB

Tip: If you choose to work on a module, create the bug report on the GNOME bugzilla, and make it block bug 589775.
This way people will know someone already works on it, and won't duplicate the work you're doing.

glib/glib

Template	Status
allocators.sgml	DavidKing bug 589351
arrays_byte.sgml	DavidKing bug 589351
arrays_pointer.sgml	DavidKing bug 589706
arrays.sgml	AndrewWalton 22.07.2008
async_queues.sgml	AndrewWalton 22.07.2008
atomic_operations.sgml	AndrewWalton 22.07.2008
base64.sgml	CraigLoftus bug 589649 commit a4655...
bookmarkfile.sgml	DavidKing bug 589774
byte_order.sgml	todo
caches.sgml	todo
checksum.sgml	AndrewWalton 22.07.2008
completion.sgml	todo
conversions.sgml	todo
datalist.sgml	todo
datasets.sgml	todo
date.sgml	todo
error_reporting.sgml	todo
fileutils.sgml	todo
glib-unused.sgml	todo
gregex.sgml	todo
gurifuncs.sgml	todo
hash_tables.sgml	todo
hooks.sgml	todo
i18n.sgml	todo
iochannels.sgml	todo
keyfile.sgml	todo
limits.sgml	todo
linked_lists_double.sgml	AndrewWalton 22.07.2008
linked_lists_single.sgml	AndrewWalton 22.07.2008
macros_misc.sgml	todo
macros.sgml	todo
main.sgml	todo
markup.sgml	todo
memory_chunks.sgml	todo
memory.sgml	todo
memory_slices.sgml	todo
messages.sgml	todo
misc_utils.sgml	todo
modules.sgml	todo
numerical.sgml	todo
option.sgml	todo
patterns.sgml	todo
quarks.sgml	todo
queue.sgml	todo
random_numbers.sgml	todo
relations.sgml	todo
scanner.sgml	todo
sequence.sgml	todo
shell.sgml	todo
spawn.sgml	todo
string_chunks.sgml	todo
strings.sgml	todo
string_utils.sgml	todo
testing.sgml	todo
thread_pools.sgml	todo
threads.sgml	todo
timers.sgml	todo
trash_stack.sgml	todo
trees-binary.sgml	todo
trees-nary.sgml	todo
type_conversion.sgml	todo
types.sgml	todo
unicode.sgml	todo
version.sgml	todo
warnings.sgml	todo
windows.sgml	todo

glib/gobject

Template	Status
enumerations_flags.sgml	StefanKost rev 7066
gboxed.sgml	StefanKost rev 7065
gclosure.sgml	StefanKost rev 7069
generic_values.sgml	StefanKost rev 7071
gobject-unused.sgml	DavidKing bug 589351
gparamspec.sgml	StefanKost rev 7073
gtypemodule.sgml	StefanKost rev 7077
gtypeplugin.sgml	StefanKost rev 7079
gtype.sgml	StefanKost rev 7075
objects.sgml	StefanKost rev 7080
param_value_types.sgml	StefanKost rev 7081
signals.sgml	StefanKost rev 7083
value_arrays.sgml	StefanKost rev 7085
value_collection.sgml	StefanKost rev 7086

GTK

Tip: If you choose to work on a module, create the bug report on the GNOME bugzilla, and make it block bug 599599.
This way people will know someone already works on it, and won't duplicate the work you're doing.

gtk+/gdk

Template	Status
cairo_interaction.sgml	todo
colors.sgml	todo
cursors.sgml	todo
dnd.sgml	todo
drawing.sgml	todo
events.sgml	todo
event_structs.sgml	todo
fonts.sgml	todo
gcs.sgml	todo
gdkdisplaymanager.sgml	todo
gdkdisplay.sgml	todo
gdkscreen.sgml	todo
general.sgml	todo
images.sgml	todo
input_devices.sgml	todo
input.sgml	todo
keys.sgml	todo
pango_interaction.sgml	todo
pixbufs.sgml	todo
pixmaps.sgml	todo
properties.sgml	todo
regions.sgml	todo
rgb.sgml	todo
selections.sgml	todo
threads.sgml	todo
visuals.sgml	todo
windows.sgml	todo
x_interaction.sgml	todo

gtk+/gdk-pixbuf

Template	Status
animation.sgml	todo
creating.sgml	todo
file-loading.sgml	todo
file-saving.sgml	todo
gdk-pixbuf-loader.sgml	todo
gdk-pixbuf.sgml	todo
gdk-pixbuf-xlib-from-drawables.sgml	todo
gdk-pixbuf-xlib-init.sgml	todo
gdk-pixbuf-xlib-rendering.sgml	todo
gdk-pixbuf-xlib-rgb.sgml	todo
inline.sgml	todo
module_interface.sgml	todo
refcounting.sgml	todo
scaling.sgml	todo
util.sgml	todo

gtk+/libgail-util

Template	Status
gail-libgail-util-unused.sgml	todo
gailmisc.sgml	todo
gailtextutil.sgml	todo

gtk+/gtk+

Template	Status
gtkaboutdialog.sgml	done
gtkaccelgroup.sgml	done
gtkaccellabel.sgml	todo
gtkaccelmap.sgml	todo
gtkaccessible.sgml	done
gtkactiongroup.sgml	todo
gtkaction.sgml	todo
gtkactivatable.sgml	done
gtkadjustment.sgml	todo
gtkalignment.sgml	todo
gtkarrow.sgml	todo
gtkaspectframe.sgml	todo
gtkassistant.sgml	todo
gtkbbox.sgml	todo
gtkbindings.sgml	todo
gtkbin.sgml	todo
gtkbox.sgml	todo
gtkbuildable.sgml	todo
gtkbuilder.sgml	todo
gtkbutton.sgml	todo
gtkcalendar.sgml	todo
gtkcelleditable.sgml	todo
gtkcelllayout.sgml	todo
gtkcellrendereraccel.sgml	todo
gtkcellrenderercombo.sgml	todo
gtkcellrendererpixbuf.sgml	todo
gtkcellrendererprogress.sgml	todo
gtkcellrenderer.sgml	todo
gtkcellrendererspin.sgml	todo
gtkcellrenderertext.sgml	todo
gtkcellrenderertoggle.sgml	todo
gtkcellview.sgml	todo
gtkcheckbutton.sgml	todo
gtkcheckmenuitem.sgml	todo
gtkclipboard.sgml	todo
gtkclist.sgml	todo
gtkcolorbutton.sgml	todo
gtkcolorseldlg.sgml	todo
gtkcolorsel.sgml	todo
gtkcomboboxentry.sgml	todo
gtkcombobox.sgml	todo
gtkcombo.sgml	todo
gtkcontainer.sgml	todo
gtkctree.sgml	todo
gtkcurve.sgml	todo
gtkdialog.sgml	todo
gtkdnd.sgml	todo
gtkdrawingarea.sgml	todo
gtkeditable.sgml	todo
gtkentrycompletion.sgml	todo
gtkentry.sgml	todo
gtkenums.sgml	todo
gtkeventbox.sgml	todo
gtkexpander.sgml	todo
gtkfeatures.sgml	todo
gtkfilechooserbutton.sgml	todo
gtkfilechooserdialog.sgml	todo
gtkfilechooser.sgml	patch
gtkfilechooserwidget.sgml	todo
gtkfilefilter.sgml	todo
gtkfilesel.sgml	todo
gtkfixed.sgml	todo
gtkfontbutton.sgml	todo
gtkfontseldlg.sgml	todo
gtkfontsel.sgml	todo
gtkframe.sgml	todo
gtkgamma.sgml	todo
gtkgc.sgml	todo
gtkhandlebox.sgml	todo
gtkhbbox.sgml	todo
gtkhbox.sgml	todo
gtkhpaned.sgml	todo
gtkhruler.sgml	todo
gtkhscale.sgml	todo
gtkhscrollbar.sgml	todo
gtkhseparator.sgml	todo
gtkiconfactory.sgml	todo
gtkicontheme.sgml	todo
gtkiconview.sgml	todo
gtkimagemenuitem.sgml	todo
gtkimage.sgml	todo
gtkimcontext.sgml	todo
gtkimcontextsimple.sgml	todo
gtkimmulticontext.sgml	todo
gtkinputdialog.sgml	todo
gtkinvisible.sgml	todo
gtkitemfactory.sgml	todo
gtkitem.sgml	todo
gtklabel.sgml	todo
gtklayout.sgml	todo
gtklinkbutton.sgml	todo
gtklistitem.sgml	todo
gtklist.sgml	todo
gtkliststore.sgml	todo
gtkmain.sgml	todo
gtkmenubar.sgml	todo
gtkmenuitem.sgml	todo
gtkmenu.sgml	todo
gtkmenushell.sgml	todo
gtkmenutoolbutton.sgml	todo
gtkmessagedialog.sgml	todo
gtkmisc.sgml	todo
gtkmountoperation.sgml	patch
gtknotebook.sgml	todo
gtkobject.sgml	todo
gtkoldeditable.sgml	todo
gtkoptionmenu.sgml	todo
gtkpagesetup.sgml	todo
gtkpagesetupunixdialog.sgml	todo
gtkpaned.sgml	todo
gtkpapersize.sgml	todo
gtkpixmap.sgml	todo
gtkplug.sgml	todo
gtkpreview.sgml	todo
gtkprintcontext.sgml	todo
gtkprinter.sgml	todo
gtkprintjob.sgml	todo
gtkprintoperation.sgml	todo
gtkprintsettings.sgml	todo
gtkprintunixdialog.sgml	todo
gtkprogressbar.sgml	todo
gtkprogress.sgml	todo
gtkradioaction.sgml	todo
gtkradiobutton.sgml	todo
gtkradiomenuitem.sgml	todo
gtkradiotoolbutton.sgml	todo
gtkrange.sgml	todo
gtkrc.sgml	todo
gtkrecentaction.sgml	todo
gtkrecentchooserdialog.sgml	todo
gtkrecentchoosermenu.sgml	todo
gtkrecentchooser.sgml	todo
gtkrecentchooserwidget.sgml	todo
gtkrecentfilter.sgml	todo
gtkrecentmanager.sgml	todo
gtkruler.sgml	todo
gtkscalebutton.sgml	todo
gtkscale.sgml	todo
gtkscrollbar.sgml	todo
gtkscrolledwindow.sgml	todo
gtkselection.sgml	todo
gtkseparatormenuitem.sgml	todo
gtkseparator.sgml	todo
gtkseparatortoolitem.sgml	todo
gtksettings.sgml	todo
gtksignal.sgml	todo
gtksizegroup.sgml	todo
gtksocket.sgml	todo
gtkspinbutton.sgml	todo
gtkstatusbar.sgml	todo
gtkstatusicon.sgml	todo
gtkstock.sgml	patch
gtkstyle.sgml	todo
gtktable.sgml	todo
gtktearoffmenuitem.sgml	todo
gtktextbuffer.sgml	todo
gtktextiter.sgml	todo
gtktextmark.sgml	todo
gtktext.sgml	todo
gtktexttag.sgml	todo
gtktexttagtable.sgml	todo
gtktextview.sgml	todo
gtkthemes.sgml	todo
gtktipsquery.sgml	todo
gtktoggleaction.sgml	todo
gtktogglebutton.sgml	todo
gtktoggletoolbutton.sgml	todo
gtktoolbar.sgml	todo
gtktoolbutton.sgml	todo
gtktoolitem.sgml	todo
gtktoolshell.sgml	done
gtktooltip.sgml	todo
gtktooltips.sgml	todo
gtktreednd.sgml	todo
gtktreeitem.sgml	todo
gtktreemodelfilter.sgml	todo
gtktreemodel.sgml	todo
gtktreemodelsort.sgml	todo
gtktreeselection.sgml	todo
gtktree.sgml	todo
gtktreesortable.sgml	todo
gtktreestore.sgml	todo
gtktreeviewcolumn.sgml	todo
gtktreeview.sgml	todo
gtktypeutils.sgml	todo
gtkuimanager.sgml	todo
gtk-unused.sgml	todo
gtkvbbox.sgml	todo
gtkvbox.sgml	todo
gtkviewport.sgml	todo
gtkvolumebutton.sgml	todo
gtkvpaned.sgml	todo
gtkvruler.sgml	todo
gtkvscale.sgml	todo
gtkvscrollbar.sgml	todo
gtkvseparator.sgml	todo
gtkwidget.sgml	patch
gtkwindowgroup.sgml	todo
gtkwindow.sgml	patch

Comments & Questions

Patch for migrating documentation for most of GLib can be found here. May need some updates and/or breaking into pieces for committing: gtk-docify-some-stuff.diff -A. Walton

live.gnome.org