|
![/!\](/gnome/gnome-responsive/img/dialog-warning-symbolic.png "/!\"){kind=small}
Warning:
glib/gtk+ API doc migration
Contents
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
|
Tip: If you choose to work on a module, create the bug report on the
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 |
|
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 |
|
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 |
|
gboxed.sgml |
|
gclosure.sgml |
|
generic_values.sgml |
|
gobject-unused.sgml |
|
gparamspec.sgml |
|
gtypemodule.sgml |
|
gtypeplugin.sgml |
|
gtype.sgml |
|
objects.sgml |
|
param_value_types.sgml |
|
signals.sgml |
|
value_arrays.sgml |
|
value_collection.sgml |
GTK
|
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 |
|
properties.sgml |
done |
regions.sgml |
done |
rgb.sgml |
not needed (deprecated) |
selections.sgml |
done |
threads.sgml |
done |
visuals.sgml |
done |
windows.sgml |
|
x_interaction.sgml |
done |
gdk-pixbuf
gdk-pixbuf is no longer in gtk+ but was still needing the migration.
Template |
Status |
animation.sgml |
|
creating.sgml |
|
file-loading.sgml |
|
file-saving.sgml |
|
gdk-pixbuf-loader.sgml |
|
gdk-pixbuf.sgml |
|
gdk-pixbuf-xlib-from-drawables.sgml |
|
gdk-pixbuf-xlib-init.sgml |
|
gdk-pixbuf-xlib-rendering.sgml |
|
gdk-pixbuf-xlib-rgb.sgml |
|
inline.sgml |
|
module_interface.sgml |
|
refcounting.sgml |
|
scaling.sgml |
|
util.sgml |
gtk+/libgail-util
gtk+/gtk+
Template |
Status |
gtkaboutdialog.sgml |
|
gtkaccelgroup.sgml |
|
gtkaccellabel.sgml |
|
gtkaccelmap.sgml |
|
gtkaccessible.sgml |
|
gtkactiongroup.sgml |
|
gtkaction.sgml |
|
gtkactivatable.sgml |
|
gtkadjustment.sgml |
done |
gtkalignment.sgml |
|
gtkarrow.sgml |
|
gtkaspectframe.sgml |
|
gtkassistant.sgml |
|
gtkbbox.sgml |
|
gtkbindings.sgml |
|
gtkbin.sgml |
|
gtkbox.sgml |
|
gtkbuildable.sgml |
|
gtkbuilder.sgml |
|
gtkbutton.sgml |
|
gtkcalendar.sgml |
|
gtkcelleditable.sgml |
|
gtkcelllayout.sgml |
|
gtkcellrendereraccel.sgml |
|
gtkcellrenderercombo.sgml |
|
gtkcellrendererpixbuf.sgml |
|
gtkcellrendererprogress.sgml |
|
gtkcellrenderer.sgml |
|
gtkcellrendererspin.sgml |
|
gtkcellrenderertext.sgml |
|
gtkcellrenderertoggle.sgml |
|
gtkcellview.sgml |
|
gtkcheckbutton.sgml |
|
gtkcheckmenuitem.sgml |
|
gtkclipboard.sgml |
|
gtkclist.sgml |
not needed (deprecated) |
gtkcolorbutton.sgml |
|
gtkcolorseldlg.sgml |
|
gtkcolorsel.sgml |
|
gtkcomboboxentry.sgml |
|
gtkcombobox.sgml |
|
gtkcombo.sgml |
not needed (deprecated) |
gtkcontainer.sgml |
|
gtkctree.sgml |
not needed (deprecated) |
gtkcurve.sgml |
not needed (deprecated) |
gtkdialog.sgml |
|
gtkdnd.sgml |
|
gtkdrawingarea.sgml |
|
gtkeditable.sgml |
|
gtkentry.sgml |
|
gtkentrybuffer.sgml |
|
gtkentrycompletion.sgml |
|
gtkenums.sgml |
|
gtkeventbox.sgml |
|
gtkexpander.sgml |
|
gtkfeatures.sgml |
|
gtkfilechooserbutton.sgml |
|
gtkfilechooserdialog.sgml |
|
gtkfilechooser.sgml |
|
gtkfilechooserwidget.sgml |
|
gtkfilefilter.sgml |
|
gtkfilesel.sgml |
not needed (deprecated) |
gtkfixed.sgml |
|
gtkfontbutton.sgml |
|
gtkfontseldlg.sgml |
|
gtkfontsel.sgml |
|
gtkframe.sgml |
|
gtkgamma.sgml |
not needed (deprecated) |
gtkgc.sgml |
|
gtkhandlebox.sgml |
|
gtkhbbox.sgml |
|
gtkhbox.sgml |
|
gtkhpaned.sgml |
|
gtkhruler.sgml |
|
gtkhscale.sgml |
|
gtkhscrollbar.sgml |
|
gtkhseparator.sgml |
|
gtkiconfactory.sgml |
|
gtkicontheme.sgml |
|
gtkiconview.sgml |
|
gtkimagemenuitem.sgml |
|
gtkimage.sgml |
|
gtkimcontext.sgml |
|
gtkimcontextsimple.sgml |
done |
gtkimmulticontext.sgml |
done |
gtkinputdialog.sgml |
not needed (deprecated) |
gtkinvisible.sgml |
|
gtkitemfactory.sgml |
not needed (deprecated) |
gtkitem.sgml |
|
gtklabel.sgml |
|
gtklayout.sgml |
|
gtklinkbutton.sgml |
|
gtklistitem.sgml |
not needed (deprecated) |
gtklist.sgml |
|
gtkliststore.sgml |
|
gtkmain.sgml |
|
gtkmenubar.sgml |
|
gtkmenuitem.sgml |
|
gtkmenu.sgml |
|
gtkmenushell.sgml |
|
gtkmenutoolbutton.sgml |
|
gtkmessagedialog.sgml |
|
gtkmisc.sgml |
|
gtkmountoperation.sgml |
|
gtknotebook.sgml |
|
gtkobject.sgml |
|
gtkoldeditable.sgml |
not needed (deprecated) |
gtkoptionmenu.sgml |
not needed (deprecated) |
gtkorientable.sgml |
done |
gtkpagesetup.sgml |
|
gtkpagesetupunixdialog.sgml |
done |
gtkpaned.sgml |
|
gtkpapersize.sgml |
done |
gtkpixmap.sgml |
not needed (deprecated) |
gtkplug.sgml |
|
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 |
|
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 |
|
gtkspinbutton.sgml |
done |
gtkstatusbar.sgml |
done |
gtkstatusicon.sgml |
done |
gtkstock.sgml |
|
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 |
|
gtkvbox.sgml |
|
gtkviewport.sgml |
|
gtkvolumebutton.sgml |
|
gtkvpaned.sgml |
|
gtkvruler.sgml |
|
gtkvscale.sgml |
|
gtkvscrollbar.sgml |
|
gtkvseparator.sgml |
|
gtkwidget.sgml |
|
gtkwindowgroup.sgml |
done |
gtkwindow.sgml |
|
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