HACKING

   1 Formatting
   2 ==========
   3
   4 All parts of Pango other than modules should use the following formatting
   5 style; for modules, it is up to the discretion of the module
   6 author / maintainer, though they are encouraged to follow the following.
   7
   8 The Pango formatting style is basically the GNU style of formatting
   9 (see http://www.gnu.org/prep/standards.html), with a few additions.
  10 In brief overview:
  11
  12  - Two character indents are used; braces go on a separate line, and
  13    get a separate indentation level, so the total indent for an
  14    enclosed block is 4 characters.
  15
  16     if (x < foo (y, z))
  17       haha = bar[4] + 5;
  18     else
  19       {
  20         while (z)
  21           {
  22             haha += foo (z, z);
  23             z--;
  24           }
  25         return abc (haha);
  26       }
  27
  28  - Spaces should be present between function name and argument block,
  29    and after commas.
  30
  31      foo (z, z)
  32
  33  - In pointer types, the '*' is grouped with the variable name,
  34    not with the base type.
  35
  36     int *a;
  37
  38    NOT: 'int* a'.
  39
  40    In cases where there is no variable name, for instance, return
  41    values, there should be a single space between the base type
  42    and the '*'.
  43
  44  - function and variable names are lower_case_with_underscores
  45    type names are StudlyCaps, macro names are UPPER_CASE_WITH_UNDERSCORES
  46
  47
  48 Documentation comments
  49 ======================
  50
  51 All public API functions should have inline documentation headers
  52 in the gtk-doc / gnome-doc style. For instance:
  53
  54 /**
  55  * pango_layout_get_line:
  56  * @layout: a #PangoLayout
  57  * @line: the index of a line, which must be between 0 and
  58  *        pango_layout_get_line_count(layout) - 1, inclusive.
  59  *
  60  * Retrieves a particular line from a #PangoLayout (or @layout.)
  61  *
  62  * Return value: the requested #PangoLayoutLine, or %NULL if the
  63  *               index is out of range. This layout line can
  64  *               be ref'ed and retained, but will become invalid
  65  *               if changes are made to the #PangoLayout.
  66  *
  67  * Since: 1.6
  68  **/
  69 PangoLayoutLine *
  70 pango_layout_get_line (PangoLayout *layout,
  71                        int          line)
  72 [...]
  73
  74
  75 Choosing Function Names
  76 =======================
  77
  78 - Don't abbreviate in unexpected ways:
  79
  80     pango_layout_get_line_count ()
  81
  82   Not:
  83
  84     pango_layout_ln_cnt ()
  85
  86 - function that retrieve a value in a side-effect free fashion, should
  87   include "get" in the name.
  88
  89     int pango_layout_get_line_count (PangoLayout *layout)
  90
  91   not
  92
  93     pango_layout_line_count ()
  94
  95
  96 - functions that set a single parameter in a side-effect free fashion
  97   should include "set" in the name, for instance:
  98
  99   void pango_layout_set_width (PangoLayout    *layout,
 100                                int             width);
 101
 102 Other comments
 103 ==============
 104
 105 - Avoid unsigned values for all but flags fields. This is because
 106   the way C handles unsigned values generates bugs like crazy:
 107
 108   If width is unsigned and 10, then:
 109
 110    int new_width = MAX (width - 15, 1);
 111
 112   produces 4294967291, not 1.
 113