/!\ Warning:
Before start working in a module, check that It's not already deprecated

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 than 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 themselves 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

{i} 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

done

arrays_byte.sgml

done

arrays_pointer.sgml

done

arrays.sgml

done

async_queues.sgml

done

atomic_operations.sgml

done

base64.sgml

done

bookmarkfile.sgml

done

byte_order.sgml

done

caches.sgml

done

checksum.sgml

done

completion.sgml

done

conversions.sgml

done

datalist.sgml

done

datasets.sgml

done

date.sgml

done

error_reporting.sgml

done

fileutils.sgml

done

glib-unused.sgml

done

gregex.sgml

done

gurifuncs.sgml

done

hash_tables.sgml

done

hooks.sgml

done

i18n.sgml

done

iochannels.sgml

done

keyfile.sgml

done

limits.sgml

done

linked_lists_double.sgml

done

linked_lists_single.sgml

done

macros_misc.sgml

done

macros.sgml

done

main.sgml

done

markup.sgml

done

memory_chunks.sgml

done

memory.sgml

JonNordby done

memory_slices.sgml

done

messages.sgml

done

misc_utils.sgml

done

modules.sgml

done

numerical.sgml

done

option.sgml

done

patterns.sgml

done

quarks.sgml

done

queue.sgml

done

random_numbers.sgml

done

relations.sgml

done

scanner.sgml

done

sequence.sgml

done

shell.sgml

done

spawn.sgml

done

string_chunks.sgml

done

strings.sgml

done

string_utils.sgml

done

testing.sgml

done

thread_pools.sgml

done

threads.sgml

done

timers.sgml

done

trash_stack.sgml

done

trees-binary.sgml

done

trees-nary.sgml

done

type_conversion.sgml

done

types.sgml

done

unicode.sgml

done

version.sgml

done

warnings.sgml

done

windows.sgml

done

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 done

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

{i} 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

done

colors.sgml

done

cursors.sgml

done

dnd.sgml

done

drawing.sgml

done

events.sgml

done

event_structs.sgml

done

fonts.sgml

not needed (deprecated)

gcs.sgml

not needed (deprecated)

gdkdisplaymanager.sgml

done

gdkdisplay.sgml

done

gdkscreen.sgml

done

general.sgml

done

images.sgml

not needed (deprecated)

input_devices.sgml

not needed (deprecated)

input.sgml

not needed (deprecated)

keys.sgml

done

pango_interaction.sgml

done

pixbufs.sgml

done

pixmaps.sgml

not needed (deprecated)

properties.sgml

done

regions.sgml

done

rgb.sgml

not needed (deprecated)

selections.sgml

done

threads.sgml

done

visuals.sgml

done

windows.sgml

done

x_interaction.sgml

done

gdk-pixbuf

gdk-pixbuf is no longer in gtk+ but was still needing the migration.

Template

Status

animation.sgml

JonNordby done

creating.sgml

JonNordby done

file-loading.sgml

JonNordby done

file-saving.sgml

JonNordby done

gdk-pixbuf-loader.sgml

JonNordby done

gdk-pixbuf.sgml

JonNordby done

gdk-pixbuf-xlib-from-drawables.sgml

JonNordby done

gdk-pixbuf-xlib-init.sgml

JonNordby done

gdk-pixbuf-xlib-rendering.sgml

JonNordby done

gdk-pixbuf-xlib-rgb.sgml

JonNordby done

inline.sgml

JonNordby done

module_interface.sgml

JonNordby done

refcounting.sgml

JonNordby done

scaling.sgml

JonNordby done

util.sgml

JonNordby done

gtk+/libgail-util

Template

Status

gail-libgail-util-unused.sgml

done

gailmisc.sgml

done

gailtextutil.sgml

done

gtk+/gtk+

Template

Status

gtkaboutdialog.sgml

done

gtkaccelgroup.sgml

done

gtkaccellabel.sgml

done

gtkaccelmap.sgml

done

gtkaccessible.sgml

done

gtkactiongroup.sgml

done

gtkaction.sgml

done

gtkactivatable.sgml

done

gtkadjustment.sgml

done

gtkalignment.sgml

done

gtkarrow.sgml

done

gtkaspectframe.sgml

done

gtkassistant.sgml

done

gtkbbox.sgml

done

gtkbindings.sgml

done

gtkbin.sgml

done

gtkbox.sgml

done

gtkbuildable.sgml

done

gtkbuilder.sgml

done

gtkbutton.sgml

done

gtkcalendar.sgml

done

gtkcelleditable.sgml

done

gtkcelllayout.sgml

done

gtkcellrendereraccel.sgml

done

gtkcellrenderercombo.sgml

done

gtkcellrendererpixbuf.sgml

done

gtkcellrendererprogress.sgml

done

gtkcellrenderer.sgml

done

gtkcellrendererspin.sgml

done

gtkcellrenderertext.sgml

done

gtkcellrenderertoggle.sgml

done

gtkcellview.sgml

done

gtkcheckbutton.sgml

done

gtkcheckmenuitem.sgml

done

gtkclipboard.sgml

done

gtkclist.sgml

not needed (deprecated)

gtkcolorbutton.sgml

done

gtkcolorseldlg.sgml

done

gtkcolorsel.sgml

done

gtkcomboboxentry.sgml

done

gtkcombobox.sgml

done

gtkcombo.sgml

not needed (deprecated)

gtkcontainer.sgml

done

gtkctree.sgml

not needed (deprecated)

gtkcurve.sgml

not needed (deprecated)

gtkdialog.sgml

done

gtkdnd.sgml

done

gtkdrawingarea.sgml

done

gtkeditable.sgml

done

gtkentry.sgml

done

gtkentrybuffer.sgml

done

gtkentrycompletion.sgml

done

gtkenums.sgml

done

gtkeventbox.sgml

done

gtkexpander.sgml

done

gtkfeatures.sgml

done

gtkfilechooserbutton.sgml

done

gtkfilechooserdialog.sgml

done

gtkfilechooser.sgml

done

gtkfilechooserwidget.sgml

done

gtkfilefilter.sgml

done

gtkfilesel.sgml

not needed (deprecated)

gtkfixed.sgml

done

gtkfontbutton.sgml

done

gtkfontseldlg.sgml

done

gtkfontsel.sgml

done

gtkframe.sgml

done

gtkgamma.sgml

not needed (deprecated)

gtkgc.sgml

done

gtkhandlebox.sgml

done

gtkhbbox.sgml

done

gtkhbox.sgml

done

gtkhpaned.sgml

done

gtkhruler.sgml

done

gtkhscale.sgml

done

gtkhscrollbar.sgml

done

gtkhseparator.sgml

done

gtkiconfactory.sgml

done

gtkicontheme.sgml

done

gtkiconview.sgml

done

gtkimagemenuitem.sgml

done

gtkimage.sgml

done

gtkimcontext.sgml

done

gtkimcontextsimple.sgml

done

gtkimmulticontext.sgml

done

gtkinputdialog.sgml

not needed (deprecated)

gtkinvisible.sgml

done

gtkitemfactory.sgml

not needed (deprecated)

gtkitem.sgml

done

gtklabel.sgml

done

gtklayout.sgml

done

gtklinkbutton.sgml

done

gtklistitem.sgml

not needed (deprecated)

gtklist.sgml

not needed (deprecated)

gtkliststore.sgml

done

gtkmain.sgml

done

gtkmenubar.sgml

done

gtkmenuitem.sgml

done

gtkmenu.sgml

done

gtkmenushell.sgml

done

gtkmenutoolbutton.sgml

done

gtkmessagedialog.sgml

done

gtkmisc.sgml

done

gtkmountoperation.sgml

done

gtknotebook.sgml

done

gtkobject.sgml

done

gtkoldeditable.sgml

not needed (deprecated)

gtkoptionmenu.sgml

not needed (deprecated)

gtkorientable.sgml

done

gtkpagesetup.sgml

done

gtkpagesetupunixdialog.sgml

done

gtkpaned.sgml

done

gtkpapersize.sgml

done

gtkpixmap.sgml

not needed (deprecated)

gtkplug.sgml

done

gtkpreview.sgml

not needed (deprecated)

gtkprintcontext.sgml

done

gtkprinter.sgml

done

gtkprintjob.sgml

done

gtkprintoperation.sgml

done

gtkprintsettings.sgml

done

gtkprintunixdialog.sgml

done

gtkprogressbar.sgml

done

gtkprogress.sgml

not needed (deprecated)

gtkradioaction.sgml

done

gtkradiobutton.sgml

done

gtkradiomenuitem.sgml

done

gtkradiotoolbutton.sgml

done

gtkrange.sgml

done

gtkrc.sgml

done

gtkrecentaction.sgml

done

gtkrecentchooserdialog.sgml

done

gtkrecentchoosermenu.sgml

done

gtkrecentchooser.sgml

done

gtkrecentchooserwidget.sgml

done

gtkrecentfilter.sgml

done

gtkrecentmanager.sgml

done

gtkruler.sgml

not needed (deprecated)

gtkscalebutton.sgml

done

gtkscale.sgml

done

gtkscrollbar.sgml

done

gtkscrolledwindow.sgml

done

gtkselection.sgml

done

gtkseparatormenuitem.sgml

done

gtkseparator.sgml

done

gtkseparatortoolitem.sgml

done

gtksettings.sgml

done

gtksignal.sgml

not needed (deprecated)

gtksizegroup.sgml

done

gtksocket.sgml

done

gtkspinbutton.sgml

done

gtkstatusbar.sgml

done

gtkstatusicon.sgml

done

gtkstock.sgml

done

gtkstyle.sgml

done

gtktable.sgml

done

gtktearoffmenuitem.sgml

done

gtktextbuffer.sgml

done

gtktextiter.sgml

done

gtktextmark.sgml

done

gtktext.sgml

not needed (deprecated)

gtktexttag.sgml

done

gtktexttagtable.sgml

done

gtktextview.sgml

done

gtkthemes.sgml

not needed (deprecated)

gtktipsquery.sgml

not needed (deprecated)

gtktoggleaction.sgml

done

gtktogglebutton.sgml

done

gtktoggletoolbutton.sgml

done

gtktoolbar.sgml

done

gtktoolbutton.sgml

done

gtktoolitem.sgml

done

gtktoolshell.sgml

done

gtktooltip.sgml

done

gtktooltips.sgml

not needed (deprecated)

gtktreednd.sgml

done

gtktreeitem.sgml

not needed (deprecated)

gtktreemodelfilter.sgml

done

gtktreemodel.sgml

done

gtktreemodelsort.sgml

done

gtktreeselection.sgml

done

gtktree.sgml

not needed (deprecated)

gtktreesortable.sgml

done

gtktreestore.sgml

done

gtktreeviewcolumn.sgml

done

gtktreeview.sgml

done

gtktypeutils.sgml

not needed (deprecated)

gtkuimanager.sgml

done

gtk-unused.sgml

not needed

gtkvbbox.sgml

done

gtkvbox.sgml

done

gtkviewport.sgml

done

gtkvolumebutton.sgml

done

gtkvpaned.sgml

done

gtkvruler.sgml

done

gtkvscale.sgml

done

gtkvscrollbar.sgml

done

gtkvseparator.sgml

done

gtkwidget.sgml

done

gtkwindowgroup.sgml

done

gtkwindow.sgml

done

testing.sgml

done

How to properly write SECTION documentation

Since gtk-doc doesn't check validity of produced DocBook XML markup, it's documentation writer's responsibility to ensure that produced XML is valid. Thankfully, all you need to is to stick to next simple rules:

  • Delimit paragraphs of text with empty lines.
  • Insert empty line before first <refsect2> tag.

  • First paragraph in subsection should be started using <para>

  • Last paragraph in subsection should be ended with </para>

Sample documentation section with quite a few different elements would look like this:

/**
 * SECTION:samplesection
 * @Short_description: Short description of SampleSection
 * @Title: SampleSection
 * See_also: #OtherDocumentedSymbol
 *
 * This is first sample paragraph. It's preceded by empty line and also empty
 * line follows it.
 *
 * This is second paragraph that will be followed by subsection. And since
 * subsection will be first refsect2 tag, we need to insert empty line here.
 *
 * <refsec2 id="myrefsect">
 * <title>No empty line before or after title</title>
 * <para>
 * First paragraph inside subsection is preceded by opening para tag.
 *
 * Second paragraph inside subsection is nothing special and is enclosed with
 * empty lines.
 *
 * Third paragraph is followed by another subsection. And since this subsection
 * is not refsect2, this paragraph needs to be endeded with closing para.
 * </para>
 * <refsect3 id="mysubsubsection">
 * <title>Again, no empty lines around title</title>
 * <para>
 * Remember, first and last paragraph need to be enclosed with para!!
 * </para>
 * </refsect3>
 * </refsect2>
 * <refsect2 id="secondrefsect">
 * <title>No space around title</title>
 * <para>
 * Did you notice that refsect2 is not preceded with empty line? This is
 * required or XML validation will fail. Remember, only fist refsect2 needs to
 * be preceded by empty line!!
 *
 * This paragraph is ended by closing para, since we're starting new subsection
 * (in this case, program listing, but the same things goes for notes, variable
 * lists, tables).
 * </para>
 * <example id="dummyexample">
 * <title>No spaces around title (but you know that already;)</title>
 * <programlisting>
 * #!/usr/bin/env perl
 *
 * use strict;
 * use warnings;
 * use Gtk2 qw{ -init };
 *
 * ...
 * </programlisting>
 * </example>
 * </refsect2>
 */

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

Projects/GTK+/TaskAPIDocMigration (last edited 2013-11-22 15:36:49 by WilliamJonMcCann)