doc/style-guide.txt

   1 Note
   2 ====
   3
   4 There is now a user manual which can be read using yelp and can be found under
   5 'development'. Please refer to this documentation for up-to-date information.
   6
   7
   8 NOTE: This is only a draft version. Don't make major changes to your
   9       documentation until we've agreed on all this.
  10
  11
  12 GTK+ Reference Documentation Style Guide
  13 ========================================
  14
  15 This file describes the way the GTK+ reference documentation should be written,
  16 so that we produce consistent documentation.
  17
  18 We will also designate one or two of the template files as 'model' templates,
  19 i.e. they are to be taken as the 'correct' way to write the documentation:
  20
  21   GtkFontSelectionDialog - contains example code and descriptions of enums.
  22   GtkMisc - contains description of fields in a widget struct.
  23
  24
  25 Language
  26 ========
  27
  28 Use American spelling rather than British, i.e. color rather than colour,
  29 organize rather than organise etc.
  30
  31 End all descriptions of functions & parameters with a period '.'.
  32
  33
  34 Organizing Sections
  35 ===================
  36
  37 The organization of the sections is determined by the glib-sections.txt,
  38 gdk-sections.txt and gtk-sections.txt files.
  39
  40 Group related functions/macros/enums etc. and place a "<SUBSECTION>" tag
  41 (on its own line) between groups. This results in a blank line in the synopsis
  42 between the groups, which makes it a bit easier to read.
  43
  44 Order the groups sections by placing the most important/commonly-used
  45 functions/macros etc. first. For pairs of accessor functions place them
  46 together with the 'get' function first and then the 'set' function.
  47
  48 Private functions etc. should be placed at the end of the "<SECTION>",
  49 after a "<SUBSECTION Private>" line. They will not appear in the HTML output
  50 and they do not have to be documented (they will disappear form the template
  51 files the next time 'make templates' is run).
  52
  53 Enumerations should appear after the first function which uses them.
  54
  55
  56 Section Descriptions
  57 ===================
  58
  59 For widgets, start the main description with -
  60
  61 <!-- ##### SECTION Long_Description ##### -->
  62 <para>
  63 The #GtkFontSelectionDialog widget ...
  64
  65
  66 If you want to include subsections in the main description, to conform to
  67 DocBook SGML you must have 0 or more leading paragraphs (or possibly other
  68 DocBook tags - see the DTD), then 1 or more <refsect2> subsections, with
  69 nothing after. e.g.
  70
  71 <!-- ##### SECTION Long_Description ##### -->
  72 <para>
  73 Introduction to the section....
  74 </para>
  75 <refsect2>
  76   <title>First Subsection</title>
  77   <para>
  78     This is the first subsection.
  79   </para>
  80 </refsect2>
  81 <refsect2>
  82   <title>Second Subsection</title>
  83   <para>
  84     This is the second subsection.
  85   </para>
  86 </refsect2>
  87
  88
  89 Functions & Macro Descriptions
  90 ==============================
  91
  92 Start the description with a phrase like this:
  93   'Looks up a key in a GHashTable'.
  94 i.e. assume that 'This function' (or 'This macro') precedes it.
  95
  96
  97 Function Parameters
  98 ===================
  99
 100 For object-oriented code, denote the object parameter with 'a',
 101 e.g. 'a #GHashTable'.
 102
 103 Use 'the' for the rest of the parameters.
 104
 105
 106 Widget Structs
 107 ==============
 108
 109 Some widget structs have fields which are useful to the developer, since
 110 there are currently no accessor functions to retrieve the particular field.
 111
 112 These fields should be documented as follows:
 113
 114 -----------------------------------------------------------------------
 115 <!-- ##### STRUCT GtkFixedChild ##### -->
 116 <para>
 117 The #GtkFixedChild-struct struct contains the following fields.
 118 (These fields should be considered read-only. They should never be set by
 119 an application.)
 120 </para>
 121
 122 @widget: the child #GtkWidget.
 123 @x: the horizontal position of the widget within the #GtkFixed
 124     container.
 125 @y: the vertical position of the widget within the #GtkFixed
 126     container.
 127 -----------------------------------------------------------------------
 128
 129
 130 If a widget struct is completely private, use this:
 131
 132 -----------------------------------------------------------------------
 133 <!-- ##### STRUCT GtkFontSelectionDialog ##### -->
 134 <para>
 135 The #GtkFontSelectionDialog-struct struct contains private data only, and
 136 should be accessed using the functions below.
 137 </para>
 138 -----------------------------------------------------------------------
 139
 140 Note that the links to the widget names go to the top of the page,
 141 e.g. links to #GtkAccelLabel result in a link to the GtkAccelLabel page.
 142 If you want to link to the widget struct, you must append '-struct',
 143 e.g. #GtkAccelLabel-struct
 144
 145 Whether a particular field in a structure is output in the
 146 documentation is determined by adding /*< public >*/ and
 147 /*< private >*/ comments into the header files. For instance,
 148 GtkEditable looks like:
 149
 150 -----------------------------------------------------------------------
 151 struct _GtkEditable
 152 {
 153   GtkWidget widget;
 154
 155   /*< public >*/
 156   guint      current_pos;
 157
 158   guint      selection_start_pos;
 159   guint      selection_end_pos;
 160   guint      has_selection : 1;
 161
 162   /*< private >*/
 163   guint      editable : 1;
 164   guint      visible : 1;
 165   GdkIC     *ic;
 166   GdkICAttr *ic_attr;
 167
 168   gchar *clipboard_text;
 169 };
 170 -----------------------------------------------------------------------
 171
 172 You should add these as you go along. Please send these changes
 173 in along with your patches for the reference docs. Widget structures
 174 are by default all private, other structures are by default all public.
 175
 176
 177 Enumerations
 178 ============
 179
 180 A lot of the enumerations in GTK+ are currently placed in the "Standard
 181 Enumerations" section. However, some of these are specific to a particular
 182 widget and so should be moved to the widget's section and documented there.
 183
 184 The enumeration values should be documented as follows:
 185
 186 -----------------------------------------------------------------------
 187 <!-- ##### ENUM GtkFontFilterType ##### -->
 188 <para>
 189 A set of bit flags used to specify the filter being set
 190 when calling gtk_font_selection_dialog_set_filter() or
 191 gtk_font_selection_set_filter().
 192 </para>
 193
 194 @GTK_FONT_FILTER_BASE: the base filter, which can't be changed by the user.
 195 @GTK_FONT_FILTER_USER: the user filter, which can be changed from within the 'Filter' page
 196                        of the #GtkFontSelection widget.
 197 -----------------------------------------------------------------------
 198
 199
 200 See Also
 201 ========
 202
 203 To link to related widgets/pages, use a <variablelist> like below.
 204 If there aren't any related pages, simply leave the See_Also section as it is,
 205 and it will not be output.
 206 Note that ancestors of widgets may automatically be added here, so
 207 don't add them yourself.
 208
 209 -----------------------------------------------------------------------
 210 <!-- ##### SECTION See_Also ##### -->
 211 <para>
 212 <variablelist>
 213
 214 <varlistentry>
 215 <term>#GtkFontSelection</term>
 216 <listitem><para>the underlying widget for selecting fonts.</para></listitem>
 217 </varlistentry>
 218
 219 </variablelist>
 220 </para>
 221 -----------------------------------------------------------------------
 222
 223
 224 Including Hypertext Links
 225 =========================
 226
 227 Use the <ulink> tag to include hypertext links, e.g.
 228
 229 Gnome's home page is at <ulink url="www.gnome.org">www.gnome.org</ulink>.
 230
 231 Remember that the documentation may be printed, so it is probably best
 232 to repeat the URL within the link.
 233
 234 Damon, 1 June 1999