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 "" 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 "
", after a "" 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 - 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 subsections, with nothing after. e.g. Introduction to the section.... First Subsection This is the first subsection. Second Subsection This is the second subsection. 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: ----------------------------------------------------------------------- The #GtkFixedChild-struct struct contains the following fields. (These fields should be considered read-only. They should never be set by an application.) @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: ----------------------------------------------------------------------- The #GtkFontSelectionDialog-struct struct contains private data only, and should be accessed using the functions below. ----------------------------------------------------------------------- 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 patche 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: ----------------------------------------------------------------------- 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(). @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 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. ----------------------------------------------------------------------- #GtkFontSelection the underlying widget for selecting fonts. ----------------------------------------------------------------------- Including Hypertext Links ========================= Use the tag to include hypertext links, e.g. Gnome's home page is at www.gnome.org. Remember that the documentation may be printed, so it is probably best to repeat the URL within the link. Damon, 1 June 1999