source: trunk/third/gtk-doc/doc/style-guide.txt @ 20745

NOTE: This is only a draft version. Don't make major changes to your
      documentation until we've agreed on all this.


GTK+ Reference Documentation Style Guide
========================================

This file describes the way the GTK+ reference documentation should be written,
so that we produce consistent documentation.

We will also designate one or two of the template files as 'model' templates,
i.e. they are to be taken as the 'correct' way to write the documentation:

  GtkFontSelectionDialog - contains example code and descriptions of enums.
  GtkMisc - contains description of fields in a widget struct.


Language
========

Use American spelling rather than British, i.e. color rather than colour,
organize rather than organise etc.

End all descriptions of functions & parameters with a period '.'.


Organizing Sections
===================

The organization of the sections is determined by the glib-sections.txt,
gdk-sections.txt and gtk-sections.txt files.

Group related functions/macros/enums etc. and place a "<SUBSECTION>" tag
(on its own line) between groups. This results in a blank line in the synopsis
between the groups, which makes it a bit easier to read.

Order the groups sections by placing the most important/commonly-used
functions/macros etc. first. For pairs of accessor functions place them
together with the 'get' function first and then the 'set' function.

Private functions etc. should be placed at the end of the "<SECTION>",
after a "<SUBSECTION Private>" line. They will not appear in the HTML output
and they do not have to be documented (they will disappear form the template
files the next time 'make templates' is run).

Enumerations should appear after the first function which uses them.


Section Descriptions
===================

For widgets, start the main description with -

<!-- ##### SECTION Long_Description ##### -->
<para>
The #GtkFontSelectionDialog widget ...


If you want to include subsections in the main description, to conform to
DocBook SGML you must have 0 or more leading paragraphs (or possibly other
DocBook tags - see the DTD), then 1 or more <refsect2> subsections, with
nothing after. e.g.

<!-- ##### SECTION Long_Description ##### -->
<para>
Introduction to the section....
</para>
<refsect2>
  <title>First Subsection</title>
  <para>
    This is the first subsection.
  </para>
</refsect2>
<refsect2>
  <title>Second Subsection</title>
  <para>
    This is the second subsection.
  </para>
</refsect2>


Functions & Macro Descriptions
==============================

Start the description with a phrase like this:
  'Looks up a key in a GHashTable'.
i.e. assume that 'This function' (or 'This macro') precedes it.


Function Parameters
===================

For object-oriented code, denote the object parameter with 'a',
e.g. 'a #GHashTable'.

Use 'the' for the rest of the parameters.


Widget Structs
==============

Some widget structs have fields which are useful to the developer, since
there are currently no accessor functions to retrieve the particular field.

These fields should be documented as follows:

-----------------------------------------------------------------------
<!-- ##### STRUCT GtkFixedChild ##### -->
<para>
The #GtkFixedChild-struct struct contains the following fields.
(These fields should be considered read-only. They should never be set by
an application.)
</para>

@widget: the child #GtkWidget.
@x: the horizontal position of the widget within the #GtkFixed
    container.
@y: the vertical position of the widget within the #GtkFixed
    container.
-----------------------------------------------------------------------


If a widget struct is completely private, use this:

-----------------------------------------------------------------------
<!-- ##### STRUCT GtkFontSelectionDialog ##### -->
<para>
The #GtkFontSelectionDialog-struct struct contains private data only, and
should be accessed using the functions below.
</para>
-----------------------------------------------------------------------

Note that the links to the widget names go to the top of the page,
e.g. links to #GtkAccelLabel result in a link to the GtkAccelLabel page.
If you want to link to the widget struct, you must append '-struct',
e.g. #GtkAccelLabel-struct

Whether a particular field in a structure is output in the 
documentation is determined by adding /*< public >*/ and
/*< private >*/ comments into the header files. For instance,
GtkEditable looks like:

-----------------------------------------------------------------------
struct _GtkEditable
{
  GtkWidget widget;

  /*< public >*/
  guint      current_pos;

  guint      selection_start_pos;
  guint      selection_end_pos;
  guint      has_selection : 1;

  /*< private >*/
  guint      editable : 1;
  guint      visible : 1;
  GdkIC     *ic;
  GdkICAttr *ic_attr;
  
  gchar *clipboard_text;
};
-----------------------------------------------------------------------

You should add these as you go along. Please send these changes
in along with your patches for the reference docs. Widget structures
are by default all private, other structures are by default all public.


Enumerations
============

A lot of the enumerations in GTK+ are currently placed in the "Standard
Enumerations" section. However, some of these are specific to a particular
widget and so should be moved to the widget's section and documented there.

The enumeration values should be documented as follows:

-----------------------------------------------------------------------
<!-- ##### ENUM GtkFontFilterType ##### -->
<para>
A set of bit flags used to specify the filter being set
when calling gtk_font_selection_dialog_set_filter() or
gtk_font_selection_set_filter().
</para>

@GTK_FONT_FILTER_BASE: the base filter, which can't be changed by the user.
@GTK_FONT_FILTER_USER: the user filter, which can be changed from within the 'Filter' page
                       of the #GtkFontSelection widget.
-----------------------------------------------------------------------


See Also
========

To link to related widgets/pages, use a <variablelist> like below.
If there aren't any related pages, simply leave the See_Also section as it is,
and it will not be output.
Note that ancestors of widgets may automatically be added here, so
don't add them yourself.

-----------------------------------------------------------------------
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>

<varlistentry>
<term>#GtkFontSelection</term>
<listitem><para>the underlying widget for selecting fonts.</para></listitem>
</varlistentry>

</variablelist>
</para>
-----------------------------------------------------------------------


Including Hypertext Links
=========================

Use the <ulink> tag to include hypertext links, e.g.

Gnome's home page is at <ulink url="www.gnome.org">www.gnome.org</ulink>.

Remember that the documentation may be printed, so it is probably best
to repeat the URL within the link.

Damon, 1 June 1999