Bug 685167 - migrate docs to no-tmpl flavour

Patch from Rafał Mużyło.

56 files changed, 1973 insertions, 33 deletions

diff --git a/pango/fonts.c b/pango/fonts.c
index f3fa2350..4a72d327 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -19,6 +19,19 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:fonts
+ * @short_description:Structures representing abstract fonts
+ * @title: Fonts
+ *
+ * Pango supports a flexible architecture where a
+ * particular rendering architecture can supply an
+ * implementation of fonts. The #PangoFont structure
+ * represents an abstract rendering-system-independent font.
+ * Pango provides routines to list available fonts, and
+ * to load a font of a given description.
+ */
+
 #include "config.h"
 #include <stdlib.h>
 #include <math.h>
diff --git a/pango/modules.c b/pango/modules.c
index ca8d4885..73935bdc 100644
--- a/pango/modules.c
+++ b/pango/modules.c
@@ -19,6 +19,14 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:modules
+ * @short_description:Support for loadable modules
+ * @title:Modules
+ *
+ * Functions and macros in this section are used to support loading dynamic
+ * modules that add engines to Pango at run time.
+ */
 #include "config.h"
 
 #include <string.h>
@@ -44,11 +52,24 @@ typedef struct _PangoMapInfo PangoMapInfo;
 typedef struct _PangoEnginePair PangoEnginePair;
 typedef struct _PangoSubmap PangoSubmap;
 
+/**
+ * PangoMap:
+ *
+ * A #PangoMap structure can be used to determine the engine to
+ * use for each character.
+ */
 struct _PangoMap
 {
   GArray *entries;
 };
 
+/**
+ * PangoMapEntry:
+ *
+ * A #PangoMapEntry contains information about the engine that should be used
+ * for the codepoint to which this entry belongs and also whether the engine
+ * matches the language tag for this entry's map exactly or just approximately.
+ */
 struct _PangoMapEntry
 {
   GSList *exact;
diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c
index 9551eb60..9059b1de 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -19,6 +19,17 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:text-attributes
+ * @short_description:Font and other attributes for annotating text
+ * @title:Text Attributes
+ *
+ * Attributed text is used in a number of places in Pango. It
+ * is used as the input to the itemization process and also when
+ * creating a #PangoLayout. The data types and functions in
+ * this section are used to represent and manipulate sets
+ * of attributes applied to a portion of text.
+ */
 #include "config.h"
 #include <string.h>
 
@@ -122,7 +133,7 @@ pango_attr_type_get_name (PangoAttrType type)
 /**
  * pango_attribute_init:
  * @attr: a #PangoAttribute
- * @klass: a #PangoAttributeClass
+ * @klass: a #PangoAttrClass
  *
  * Initializes @attr's klass to @klass,
  * it's start_index to %PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING
diff --git a/pango/pango-attributes.h b/pango/pango-attributes.h
index 897d07dd..1e0feb7c 100644
--- a/pango/pango-attributes.h
+++ b/pango/pango-attributes.h
@@ -31,6 +31,15 @@ G_BEGIN_DECLS
 
 typedef struct _PangoColor PangoColor;
 
+/**
+ * PangoColor:
+ * @red: value of red component
+ * @green: value of green component
+ * @blue: value of blue component
+ *
+ * The #PangoColor structure is used to
+ * represent a color in an uncalibrated RGB color-space.
+ */
 struct _PangoColor
 {
   guint16 red;
@@ -38,6 +47,11 @@ struct _PangoColor
   guint16 blue;
 };
 
+/**
+ * PANGO_TYPE_COLOR:
+ *
+ * The #GObject type for #PangoColor.
+ */
 #define PANGO_TYPE_COLOR pango_color_get_type ()
 GType       pango_color_get_type (void) G_GNUC_CONST;
 
@@ -62,10 +76,73 @@ typedef struct _PangoAttrColor    PangoAttrColor;
 typedef struct _PangoAttrFontDesc PangoAttrFontDesc;
 typedef struct _PangoAttrShape    PangoAttrShape;
 
+/**
+ * PANGO_TYPE_ATTR_LIST:
+ *
+ * The #GObject type for #PangoAttrList.
+ */
 #define PANGO_TYPE_ATTR_LIST pango_attr_list_get_type ()
+/**
+ * PangoAttrIterator:
+ *
+ * The #PangoAttrIterator structure is used to represent an
+ * iterator through a #PangoAttrList. A new iterator is created
+ * with pango_attr_list_get_iterator(). Once the iterator
+ * is created, it can be advanced through the style changes
+ * in the text using pango_attr_iterator_next(). At each
+ * style change, the range of the current style segment and the
+ * attributes currently in effect can be queried.
+ */
+/**
+ * PangoAttrList:
+ *
+ * The #PangoAttrList structure represents a list of attributes
+ * that apply to a section of text. The attributes are, in general,
+ * allowed to overlap in an arbitrary fashion, however, if the
+ * attributes are manipulated only through pango_attr_list_change(),
+ * the overlap between properties will meet stricter criteria.
+ *
+ * Since the #PangoAttrList structure is stored as a linear list,
+ * it is not suitable for storing attributes for large amounts
+ * of text. In general, you should not use a single #PangoAttrList
+ * for more than one paragraph of text.
+ */
 typedef struct _PangoAttrList     PangoAttrList;
 typedef struct _PangoAttrIterator PangoAttrIterator;
 
+/**
+ * PangoAttrType:
+ * @PANGO_ATTR_INVALID: does not happen
+ * @PANGO_ATTR_LANGUAGE: language (#PangoAttrLanguage)
+ * @PANGO_ATTR_FAMILY: font family name list (#PangoAttrString)
+ * @PANGO_ATTR_STYLE: font slant style (#PangoAttrInt)
+ * @PANGO_ATTR_WEIGHT: font weight (#PangoAttrInt)
+ * @PANGO_ATTR_VARIANT: font variant (normal or small caps) (#PangoAttrInt)
+ * @PANGO_ATTR_STRETCH: font stretch (#PangoAttrInt)
+ * @PANGO_ATTR_SIZE: font size in points scaled by %PANGO_SCALE (#PangoAttrInt)
+ * @PANGO_ATTR_FONT_DESC: font description (#PangoAttrFontDesc)
+ * @PANGO_ATTR_FOREGROUND: foreground color (#PangoAttrColor)
+ * @PANGO_ATTR_BACKGROUND: background color (#PangoAttrColor)
+ * @PANGO_ATTR_UNDERLINE: whether the text has an underline (#PangoAttrInt)
+ * @PANGO_ATTR_STRIKETHROUGH: whether the text is struck-through (#PangoAttrInt)
+ * @PANGO_ATTR_RISE: baseline displacement (#PangoAttrInt)
+ * @PANGO_ATTR_SHAPE: shape (#PangoAttrShape)
+ * @PANGO_ATTR_SCALE: font size scale factor (#PangoAttrFloat)
+ * @PANGO_ATTR_FALLBACK: whether fallback is enabled (#PangoAttrInt)
+ * @PANGO_ATTR_LETTER_SPACING: letter spacing (#PangoAttrInt)
+ * @PANGO_ATTR_UNDERLINE_COLOR: underline color (#PangoAttrColor)
+ * @PANGO_ATTR_STRIKETHROUGH_COLOR: strikethrough color (#PangoAttrColor)
+ * @PANGO_ATTR_ABSOLUTE_SIZE: font size in pixels scaled by %PANGO_SCALE (#PangoAttrInt)
+ * @PANGO_ATTR_GRAVITY: base text gravity (#PangoAttrInt)
+ * @PANGO_ATTR_GRAVITY_HINT: gravity hint (#PangoAttrInt)
+ *
+ * The #PangoAttrType
+ * distinguishes between different types of attributes. Along with the
+ * predefined values, it is possible to allocate additional values
+ * for custom attributes using pango_attr_type_register(). The predefined
+ * values are given below. The type of structure used to store the
+ * attribute is listed in parentheses after the description.
+ */
 typedef enum
 {
   PANGO_ATTR_INVALID,           /* 0 is an invalid attribute type */
@@ -93,6 +170,27 @@ typedef enum
   PANGO_ATTR_GRAVITY_HINT	/* PangoAttrInt */
 } PangoAttrType;
 
+/**
+ * PangoUnderline:
+ * @PANGO_UNDERLINE_NONE: no underline should be drawn
+ * @PANGO_UNDERLINE_SINGLE: a single underline should be drawn
+ * @PANGO_UNDERLINE_DOUBLE: a double underline should be drawn
+ * @PANGO_UNDERLINE_LOW: a single underline should be drawn at a position
+ * beneath the ink extents of the text being
+ * underlined. This should be used only for underlining
+ * single characters, such as for keyboard
+ * accelerators. %PANGO_UNDERLINE_SINGLE should
+ * be used for extended portions of text.
+ * @PANGO_UNDERLINE_ERROR: a wavy underline should be drawn below.
+ * This underline is typically used to indicate
+ * an error such as a possilble mispelling; in some
+ * cases a contrasting color may automatically
+ * be used. This type of underlining is available since Pango 1.4.
+ *
+ * The #PangoUnderline enumeration is used to specify
+ * whether text should be underlined, and if so, the type
+ * of underlining.
+ */
 typedef enum {
   PANGO_UNDERLINE_NONE,
   PANGO_UNDERLINE_SINGLE,
@@ -101,9 +199,39 @@ typedef enum {
   PANGO_UNDERLINE_ERROR
 } PangoUnderline;
 
+/**
+ * PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING:
+ *
+ * This value can be used to set the start_index member of a #PangoAttribute
+ * such that the attribute covers from the beginning of the text.
+ *
+ * Since: 1.24
+ */
+/**
+ * PANGO_ATTR_INDEX_TO_TEXT_END:
+ *
+ * This value can be used to set the end_index member of a #PangoAttribute
+ * such that the attribute covers to the end of the text.
+ *
+ * Since: 1.24
+ */
 #define PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING	0
 #define PANGO_ATTR_INDEX_TO_TEXT_END		G_MAXUINT
 
+/**
+ * PangoAttribute:
+ * @klass: the class structure holding information about the type of the attribute
+ * @start_index: the start index of the range (in bytes).
+ * @end_index: end index of the range (in bytes). The character at this index
+ * is not included in the range.
+ *
+ * The #PangoAttribute structure represents the common portions of all
+ * attributes. Particular types of attributes include this structure
+ * as their initial portion. The common portion of the attribute holds
+ * the range to which the value in the type-specific part of the attribute
+ * applies and should be initialized using pango_attribute_init().
+ * By default an attribute will have an all-inclusive range of [0,%G_MAXUINT].
+ */
 struct _PangoAttribute
 {
   const PangoAttrClass *klass;
@@ -134,6 +262,18 @@ typedef gboolean (*PangoAttrFilterFunc) (PangoAttribute *attribute,
  **/
 typedef gpointer (*PangoAttrDataCopyFunc) (gconstpointer user_data);
 
+/**
+ * PangoAttrClass:
+ * @type: the type ID for this attribute
+ * @copy: function to duplicate an attribute of this type (see pango_attribute_copy())
+ * @destroy: function to free an attribute of this type (see pango_attribute_destroy())
+ * @equal: function to check two attributes of this type for equality (see pango_attribute_equal())
+ *
+ * The #PangoAttrClass structure stores the type and operations for
+ * a particular type of attribute. The functions in this structure should
+ * not be called directly. Instead, one should use the wrapper functions
+ * provided for #PangoAttribute.
+ */
 struct _PangoAttrClass
 {
   /*< public >*/
@@ -143,36 +283,85 @@ struct _PangoAttrClass
   gboolean         (*equal) (const PangoAttribute *attr1, const PangoAttribute *attr2);
 };
 
+/**
+ * PangoAttrString:
+ * @attr: the common portion of the attribute
+ * @value: the string which is the value of the attribute
+ *
+ * The #PangoAttrString structure is used to represent attributes with
+ * a string value.
+ */
 struct _PangoAttrString
 {
   PangoAttribute attr;
   char *value;
 };
-
+/**
+ * PangoAttrLanguage:
+ * @attr: the common portion of the attribute
+ * @value: the #PangoLanguage which is the value of the attribute
+ *
+ * The #PangoAttrLanguage structure is used to represent attributes that
+ * are languages.
+ */
 struct _PangoAttrLanguage
 {
   PangoAttribute attr;
   PangoLanguage *value;
 };
-
+/**
+ * PangoAttrInt:
+ * @attr: the common portion of the attribute
+ * @value: the value of the attribute
+ *
+ * The #PangoAttrInt structure is used to represent attributes with
+ * an integer or enumeration value.
+ */
 struct _PangoAttrInt
 {
   PangoAttribute attr;
   int value;
 };
-
+/**
+ * PangoAttrFloat:
+ * @attr: the common portion of the attribute
+ * @value: the value of the attribute
+ *
+ * The #PangoAttrFloat structure is used to represent attributes with
+ * a float or double value.
+ */
 struct _PangoAttrFloat
 {
   PangoAttribute attr;
   double value;
 };
-
+/**
+ * PangoAttrColor:
+ * @attr: the common portion of the attribute
+ * @color: the #PangoColor which is the value of the attribute
+ *
+ * The #PangoAttrColor structure is used to represent attributes that
+ * are colors.
+ */
 struct _PangoAttrColor
 {
   PangoAttribute attr;
   PangoColor color;
 };
 
+/**
+ * PangoAttrSize:
+ * @attr: the common portion of the attribute
+ * @size: size of font, in units of 1/%PANGO_SCALE of a point (for
+ * %PANGO_ATTR_SIZE) or of a device uni (for %PANGO_ATTR_ABSOLUTE_SIZE)
+ * @absolute: whether the font size is in device units or points.
+ * This field is only present for compatibility with Pango-1.8.0
+ * (%PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will
+ * be %FALSE for %PANGO_ATTR_SIZE and %TRUE for %PANGO_ATTR_ABSOLUTE_SIZE.
+ *
+ * The #PangoAttrSize structure is used to represent attributes which
+ * set font size.
+ */
 struct _PangoAttrSize
 {
   PangoAttribute attr;
@@ -180,6 +369,18 @@ struct _PangoAttrSize
   guint absolute : 1;
 };
 
+/**
+ * PangoAttrShape:
+ * @attr: the common portion of the attribute
+ * @ink_rect: the ink rectangle to restrict to
+ * @logical_rect: the logical rectangle to restrict to
+ * @data: user data set (see pango_attr_shape_new_with_data())
+ * @copy_func: copy function for the user data
+ * @destroy_func: destroy function for the user data
+ *
+ * The #PangoAttrShape structure is used to represent attributes which
+ * impose shape restrictions.
+ */
 struct _PangoAttrShape
 {
   PangoAttribute attr;
@@ -191,6 +392,14 @@ struct _PangoAttrShape
   GDestroyNotify        destroy_func;
 };
 
+/**
+ * PangoAttrFontDesc:
+ * @attr: the common portion of the attribute
+ * @desc: the font description which is the value of this attribute
+ *
+ * The #PangoAttrFontDesc structure is used to store an attribute that
+ * sets all aspects of the font description at once.
+ */
 struct _PangoAttrFontDesc
 {
   PangoAttribute attr;
diff --git a/pango/pango-bidi-type.c b/pango/pango-bidi-type.c
index a61e255f..462e7b00 100644
--- a/pango/pango-bidi-type.c
+++ b/pango/pango-bidi-type.c
@@ -19,6 +19,24 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:bidi
+ * @short_description:Types and functions to help with handling bidirectional text
+ * @title:Bidirectional Text
+ * @see_also:
+ * pango_context_get_base_dir(),
+ * pango_context_set_base_dir(),
+ * pango_itemize_with_base_dir()
+ *
+ * Pango supports bidirectional text (like Arabic and Hebrew) automatically.
+ * Some applications however, need some help to correctly handle bidirectional text.
+ *
+ * The #PangoDirection type can be used with pango_context_set_base_dir() to
+ * instruct Pango about direction of text, though in most cases Pango detects
+ * that correctly and automatically.  The rest of the facilities in this section
+ * are used internally by Pango already, and are provided to help applications
+ * that need more direct control over bidirectional setting of text.
+ */
 #include "config.h"
 
 #include <string.h>
@@ -38,7 +56,7 @@
  * character, as specified in the Unicode Character Database.
  *
  * A simplified version of this function is available as
- * pango_unichar_get_direction().
+ * pango_unichar_direction().
  *
  * Return value: the bidirectional character type, as used in the
  * Unicode bidirectional algorithm.
@@ -162,7 +180,7 @@ pango_log2vis_get_embedding_levels (const gchar    *text,
  * This function is useful to categorize characters into left-to-right
  * letters, right-to-left letters, and everything else.  If full
  * Unicode bidirectional type of a character is needed,
- * pango_bidi_type_for_gunichar() can be used instead.
+ * pango_bidi_type_for_unichar() can be used instead.
  *
  * Return value: the direction of the character.
  */
diff --git a/pango/pango-break.h b/pango/pango-break.h
index 5c326dd4..70f8aedf 100644
--- a/pango/pango-break.h
+++ b/pango/pango-break.h
@@ -30,6 +30,59 @@ G_BEGIN_DECLS
 
 /* Logical attributes of a character.
  */
+/**
+ * PangoLogAttr:
+ * @is_line_break: if set, can break line in front of character
+ * @is_mandatory_break: if set, must break line in front of character
+ * @is_char_break: if set, can break here when doing character wrapping
+ * @is_white: is whitespace character
+ * @is_cursor_position: if set, cursor can appear in front of character.
+ * i.e. this is a grapheme boundary, or the first character
+ * in the text.
+ * This flag implements Unicode's
+ * <ulink url="http://www.unicode.org/reports/tr29/">Grapheme
+ * Cluster Boundaries</ulink> semantics.
+ * @is_word_start: is first character in a word
+ * @is_word_end: is first non-word char after a word
+ * Note that in degenerate cases, you could have both @is_word_start
+ * and @is_word_end set for some character.
+ * @is_sentence_boundary: is a sentence boundary.
+ * There are two ways to divide sentences. The first assigns all
+ * inter-sentence whitespace/control/format chars to some sentence,
+ * so all chars are in some sentence; @is_sentence_boundary denotes
+ * the boundaries there. The second way doesn't assign
+ * between-sentence spaces, etc. to any sentence, so
+ * @is_sentence_start/@is_sentence_end mark the boundaries of those sentences.
+ * @is_sentence_start: is first character in a sentence
+ * @is_sentence_end: is first char after a sentence.
+ * Note that in degenerate cases, you could have both @is_sentence_start
+ * and @is_sentence_end set for some character. (e.g. no space after a
+ * period, so the next sentence starts right away)
+ * @backspace_deletes_character: if set, backspace deletes one character
+ * rather than the entire grapheme cluster. This
+ * field is only meaningful on grapheme
+ * boundaries (where @is_cursor_position is
+ * set).  In some languages, the full grapheme
+ * (e.g.  letter + diacritics) is considered a
+ * unit, while in others, each decomposed
+ * character in the grapheme is a unit. In the
+ * default implementation of pango_break(), this
+ * bit is set on all grapheme boundaries except
+ * those following Latin, Cyrillic or Greek base characters.
+ * @is_expandable_space: is a whitespace character that can possibly be
+ * expanded for justification purposes. (Since: 1.18)
+ * @is_word_boundary: is a word boundary.
+ * More specifically, means that this is not a position in the middle
+ * of a word.  For example, both sides of a punctuation mark are
+ * considered word boundaries.  This flag is particularly useful when
+ * selecting text word-by-word.
+ * This flag implements Unicode's
+ * <ulink url="http://www.unicode.org/reports/tr29/">Word
+ * Boundaries</ulink> semantics. (Since: 1.22)
+ *
+ * The #PangoLogAttr structure stores information
+ * about the attributes of a single character.
+ */
 struct _PangoLogAttr
 {
   guint is_line_break : 1;      /* Can break line in front of character */
diff --git a/pango/pango-context.c b/pango/pango-context.c
index 8bb6a86e..4e1fb1fa 100644
--- a/pango/pango-context.c
+++ b/pango/pango-context.c
@@ -19,6 +19,16 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:main
+ * @title:Rendering
+ * @short_description:Functions to run the rendering pipeline
+ *
+ * The Pango rendering pipeline takes a string of
+ * Unicode characters and converts it into glyphs.
+ * The functions described in this section accomplish
+ * various steps of this process.
+ */
 #include "config.h"
 #include <string.h>
 #include <stdlib.h>
@@ -31,6 +41,12 @@
 #include "pango-modules.h"
 #include "pango-script-private.h"
 
+/**
+ * PangoContext:
+ *
+ * The #PangoContext structure stores global information
+ * used to control the itemization process.
+ */
 struct _PangoContext
 {
   GObject parent_instance;
@@ -237,7 +253,7 @@ pango_context_set_font_map (PangoContext *context,
  * pango_context_get_font_map:
  * @context: a #PangoContext
  *
- * Gets the #PangoFontmap used to look up fonts for this context.
+ * Gets the #PangoFontMap used to look up fonts for this context.
  *
  * Return value: (transfer none): the font map for the #PangoContext.
  *               This value is owned by Pango and should not be unreferenced.
diff --git a/pango/pango-coverage.c b/pango/pango-coverage.c
index d84a5cd3..eccd4f99 100644
--- a/pango/pango-coverage.c
+++ b/pango/pango-coverage.c
@@ -19,6 +19,16 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:coverage-maps
+ * @short_description:Unicode character range coverage storage
+ * @title:Coverage Maps
+ *
+ * It is often necessary in Pango to determine if a particular font can
+ * represent a particular character, and also how well it can represent
+ * that character. The #PangoCoverage is a data structure that is used
+ * to represent that information.
+ */
 #include "config.h"
 #include <string.h>
 
@@ -444,7 +454,7 @@ pango_coverage_get_uint32 (guchar **ptr)
  *   representing a #PangoCoverage
  * @n_bytes: the size of @bytes in bytes
  *
- * Convert data generated from pango_converage_to_bytes() back
+ * Convert data generated from pango_coverage_to_bytes() back
  * to a #PangoCoverage
  *
  * Return value: (transfer full): a newly allocated #PangoCoverage, or
diff --git a/pango/pango-coverage.h b/pango/pango-coverage.h
index e1e8d133..592d2b1c 100644
--- a/pango/pango-coverage.h
+++ b/pango/pango-coverage.h
@@ -26,8 +26,29 @@
 
 G_BEGIN_DECLS
 
+/**
+ * PangoCoverage:
+ *
+ * The #PangoCoverage structure represents a map from Unicode characters
+ * to #PangoCoverageLevel. It is an opaque structure with no public fields.
+ */
 typedef struct _PangoCoverage PangoCoverage;
 
+/**
+ * PangoCoverageLevel:
+ * @PANGO_COVERAGE_NONE: The character is not representable with the font.
+ * @PANGO_COVERAGE_FALLBACK: The character is represented in a way that may be
+ * comprehensible but is not the correct graphical form.
+ * For instance, a Hangul character represented as a
+ * a sequence of Jamos, or a Latin transliteration of a Cyrillic word.
+ * @PANGO_COVERAGE_APPROXIMATE: The character is represented as basically the correct
+ * graphical form, but with a stylistic variant inappropriate for
+ * the current script.
+ * @PANGO_COVERAGE_EXACT: The character is represented as the correct graphical form.
+ *
+ * Used to indicate how well a font can represent a particular Unicode
+ * character point for a particular script.
+ */
 typedef enum {
   PANGO_COVERAGE_NONE,
   PANGO_COVERAGE_FALLBACK,
diff --git a/pango/pango-engine.c b/pango/pango-engine.c
index 04de3df7..6634ff04 100644
--- a/pango/pango-engine.c
+++ b/pango/pango-engine.c
@@ -19,6 +19,45 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:engines
+ * @short_description:Language-specific and rendering-system-specific processing
+ * @title:Engines
+ *
+ * Pango utilizes a module architecture in which the language-specific
+ * and render-system-specific components are provided by loadable
+ * modules. Each loadable module supplies one or more
+ * <firstterm>engines</firstterm>.  Each <firstterm>engine</firstterm>
+ * has an associated <firstterm>engine type</firstterm> and
+ * <firstterm>render type</firstterm>. These two types are represented by strings.
+ *
+ * Each dynamically-loaded module exports several functions which provide
+ * the public API. These functions are script_engine_list(),
+ * script_engine_init() and script_engine_exit, and
+ * script_engine_create(). The latter three functions are used when
+ * creating engines from the module at run time, while the first
+ * function is used when building a catalog of all available modules.
+ */
+/**
+ * SECTION:pango-engine-lang
+ * @short_description:Rendering-system independent script engines
+ * @title:PangoEngineLang
+ * @stability:Unstable
+ *
+ * The <firstterm>language engines</firstterm> are rendering-system independent
+ * engines that determine line, word, and character breaks for character strings.
+ * These engines are used in pango_break().
+ */
+/**
+ * SECTION:pango-engine-shape
+ * @short_description:Rendering-system dependent script engines
+ * @title:PangoEngineShape
+ * @stability:Unstable
+ *
+ * The <firstterm>shape engines</firstterm> are rendering-system dependent
+ * engines that convert character strings into glyph strings.
+ * These engines are used in pango_shape().
+ */
 #include "config.h"
 
 #include "pango-engine.h"
diff --git a/pango/pango-engine.h b/pango/pango-engine.h
index 51ac8c2e..0b8abbe3 100644
--- a/pango/pango-engine.h
+++ b/pango/pango-engine.h
@@ -36,6 +36,12 @@ G_BEGIN_DECLS
 
 #include <gmodule.h>
 
+/**
+ * PANGO_RENDER_TYPE_NONE:
+ *
+ * A string constant defining the render type
+ * for engines that are not rendering-system specific.
+ */
 #define PANGO_RENDER_TYPE_NONE "PangoRenderNone"
 
 #define PANGO_TYPE_ENGINE              (pango_engine_get_type ())
@@ -73,6 +79,12 @@ struct _PangoEngineClass
 
 GType pango_engine_get_type (void) G_GNUC_CONST;
 
+/**
+ * PANGO_ENGINE_TYPE_LANG:
+ *
+ * A string constant defining the engine type for language engines.
+ * These engines derive from #PangoEngineLang.
+ */
 #define PANGO_ENGINE_TYPE_LANG "PangoEngineLang"
 
 #define PANGO_TYPE_ENGINE_LANG              (pango_engine_lang_get_type ())
@@ -127,6 +139,12 @@ struct _PangoEngineLangClass
 
 GType pango_engine_lang_get_type (void) G_GNUC_CONST;
 
+/**
+ * PANGO_ENGINE_TYPE_SHAPE:
+ *
+ * A string constant defining the engine type for shaping engines.
+ * These engines derive from #PangoEngineShape.
+ */
 #define PANGO_ENGINE_TYPE_SHAPE "PangoEngineShape"
 
 #define PANGO_TYPE_ENGINE_SHAPE              (pango_engine_shape_get_type ())
@@ -205,12 +223,40 @@ GType pango_engine_shape_get_type (void) G_GNUC_CONST;
 typedef struct _PangoEngineInfo PangoEngineInfo;
 typedef struct _PangoEngineScriptInfo PangoEngineScriptInfo;
 
+/**
+ * PangoEngineScriptInfo
+ * @script: a #PangoScript. The value %PANGO_SCRIPT_COMMON has
+ * the special meaning here of "all scripts"
+ * @langs: a semicolon separated list of languages that this
+ * engine handles for this script. This may be empty,
+ * in which case the engine is saying that it is a
+ * fallback choice for all languages for this range,
+ * but should not be used if another engine
+ * indicates that it is specific for the language for
+ * a given code point. An entry in this list of "*"
+ * indicates that this engine is specific to all
+ * languages for this range.
+ *
+ * The #PangoEngineScriptInfo structure contains
+ * information about how the shaper covers a particular script.
+ */
 struct _PangoEngineScriptInfo
 {
   PangoScript script;
   const gchar *langs;
 };
 
+/**
+ * PangoEngineInfo:
+ * @id: a unique string ID for the engine.
+ * @engine_type: a string identifying the engine type.
+ * @render_type: a string identifying the render type.
+ * @scripts: array of scripts this engine supports.
+ * @n_scripts: number of items in @scripts.
+ *
+ * The #PangoEngineInfo structure contains information about a particular
+ * engine. It contains the following fields:
+ */
 struct _PangoEngineInfo
 {
   const gchar *id;
diff --git a/pango/pango-font.h b/pango/pango-font.h
index eea27b4e..e4ed4e0f 100644
--- a/pango/pango-font.h
+++ b/pango/pango-font.h
@@ -29,7 +29,24 @@
 
 G_BEGIN_DECLS
 
+/**
+ * PangoFontDescription:
+ *
+ * The #PangoFontDescription structure represents the description
+ * of an ideal font. These structures are used both to list
+ * what fonts are available on the system and also for specifying
+ * the characteristics of a font to load.
+ */
 typedef struct _PangoFontDescription PangoFontDescription;
+/**
+ * PangoFontMetrics:
+ *
+ * A #PangoFontMetrics structure holds the overall metric information
+ * for a font (possibly restricted to a script). The fields of this
+ * structure are private to implementations of a font backend. See
+ * the documentation of the corresponding getters for documentation
+ * of their meaning.
+ */
 typedef struct _PangoFontMetrics PangoFontMetrics;
 
 /**
@@ -46,11 +63,36 @@ typedef enum {
   PANGO_STYLE_ITALIC
 } PangoStyle;
 
+/**
+ * PangoVariant:
+ * @PANGO_VARIANT_NORMAL: A normal font.
+ * @PANGO_VARIANT_SMALL_CAPS: A font with the lower case characters
+ * replaced by smaller variants of the capital characters.
+ *
+ * An enumeration specifying capitalization variant of the font.
+ */
 typedef enum {
   PANGO_VARIANT_NORMAL,
   PANGO_VARIANT_SMALL_CAPS
 } PangoVariant;
 
+/**
+ * PangoWeight:
+ * @PANGO_WEIGHT_THIN: the thin weight (= 100; Since: 1.24)
+ * @PANGO_WEIGHT_ULTRALIGHT: the ultralight weight (= 200)
+ * @PANGO_WEIGHT_LIGHT: the light weight (= 300)
+ * @PANGO_WEIGHT_BOOK: the book weight (= 380; Since: 1.24)
+ * @PANGO_WEIGHT_NORMAL: the default weight (= 400)
+ * @PANGO_WEIGHT_MEDIUM: the normal weight (= 500; Since: 1.24)
+ * @PANGO_WEIGHT_SEMIBOLD: the semibold weight (= 600)
+ * @PANGO_WEIGHT_BOLD: the bold weight (= 700)
+ * @PANGO_WEIGHT_ULTRABOLD: the ultrabold weight (= 800)
+ * @PANGO_WEIGHT_HEAVY: the heavy weight (= 900)
+ * @PANGO_WEIGHT_ULTRAHEAVY: the ultraheavy weight (= 1000; Since: 1.24)
+ *
+ * An enumeration specifying the weight (boldness) of a font. This is a numerical
+ * value ranging from 100 to 900, but there are some predefined values:
+ */
 typedef enum {
   PANGO_WEIGHT_THIN = 100,
   PANGO_WEIGHT_ULTRALIGHT = 200,
@@ -65,6 +107,21 @@ typedef enum {
   PANGO_WEIGHT_ULTRAHEAVY = 1000
 } PangoWeight;
 
+/**
+ * PangoStretch:
+ * @PANGO_STRETCH_ULTRA_CONDENSED: ultra condensed width
+ * @PANGO_STRETCH_EXTRA_CONDENSED: extra condensed width
+ * @PANGO_STRETCH_CONDENSED: condensed width
+ * @PANGO_STRETCH_SEMI_CONDENSED: semi condensed width
+ * @PANGO_STRETCH_NORMAL: the normal width
+ * @PANGO_STRETCH_SEMI_EXPANDED: semi expanded width
+ * @PANGO_STRETCH_EXPANDED: expanded width
+ * @PANGO_STRETCH_EXTRA_EXPANDED: extra expanded width
+ * @PANGO_STRETCH_ULTRA_EXPANDED: ultra expanded width
+ *
+ * An enumeration specifying the width of the font relative to other designs
+ * within a family.
+ */
 typedef enum {
   PANGO_STRETCH_ULTRA_CONDENSED,
   PANGO_STRETCH_EXTRA_CONDENSED,
@@ -77,6 +134,19 @@ typedef enum {
   PANGO_STRETCH_ULTRA_EXPANDED
 } PangoStretch;
 
+/**
+ * PangoFontMask:
+ * @PANGO_FONT_MASK_FAMILY: the font family is specified.
+ * @PANGO_FONT_MASK_STYLE: the font style is specified.
+ * @PANGO_FONT_MASK_VARIANT: the font variant is specified.
+ * @PANGO_FONT_MASK_WEIGHT: the font weight is specified.
+ * @PANGO_FONT_MASK_STRETCH: the font stretch is specified.
+ * @PANGO_FONT_MASK_SIZE: the font size is specified.
+ * @PANGO_FONT_MASK_GRAVITY: the font gravity is specified (Since: 1.16.)
+ *
+ * The bits in a #PangoFontMask correspond to fields in a
+ * #PangoFontDescription that have been set.
+ */
 typedef enum {
   PANGO_FONT_MASK_FAMILY  = 1 << 0,
   PANGO_FONT_MASK_STYLE   = 1 << 1,
@@ -88,6 +158,41 @@ typedef enum {
 } PangoFontMask;
 
 /* CSS scale factors (1.2 factor between each size) */
+/**
+ * PANGO_SCALE_XX_SMALL:
+ *
+ * The scale factor for three shrinking steps (1 / (1.2 * 1.2 * 1.2)).
+ */
+/**
+ * PANGO_SCALE_X_SMALL:
+ *
+ * The scale factor for two shrinking steps (1 / (1.2 * 1.2)).
+ */
+/**
+ * PANGO_SCALE_SMALL:
+ *
+ * The scale factor for one shrinking step (1 / 1.2).
+ */
+/**
+ * PANGO_SCALE_MEDIUM:
+ *
+ * The scale factor for normal size (1.0).
+ */
+/**
+ * PANGO_SCALE_LARGE:
+ *
+ * The scale factor for one magnification step (1.2).
+ */
+/**
+ * PANGO_SCALE_X_LARGE:
+ *
+ * The scale factor for two magnification steps (1.2 * 1.2).
+ */
+/**
+ * PANGO_SCALE_XX_LARGE:
+ *
+ * The scale factor for three magnification steps (1.2 * 1.2 * 1.2).
+ */
 #define PANGO_SCALE_XX_SMALL ((double)0.5787037037037)
 #define PANGO_SCALE_X_SMALL  ((double)0.6444444444444)
 #define PANGO_SCALE_SMALL    ((double)0.8333333333333)
@@ -100,6 +205,11 @@ typedef enum {
  * PangoFontDescription
  */
 
+/**
+ * PANGO_TYPE_FONT_DESCRIPTION:
+ *
+ * The #GObject type for #PangoFontDescription.
+ */
 #define PANGO_TYPE_FONT_DESCRIPTION (pango_font_description_get_type ())
 
 GType                 pango_font_description_get_type    (void) G_GNUC_CONST;
@@ -163,6 +273,11 @@ char *                pango_font_description_to_filename (const PangoFontDescrip
  * PangoFontMetrics
  */
 
+/**
+ * PANGO_TYPE_FONT_METRICS:
+ *
+ * The #GObject type for #PangoFontMetrics.
+ */
 #define PANGO_TYPE_FONT_METRICS  (pango_font_metrics_get_type ())
 GType             pango_font_metrics_get_type                    (void) G_GNUC_CONST;
 PangoFontMetrics *pango_font_metrics_ref                         (PangoFontMetrics *metrics);
@@ -200,6 +315,23 @@ struct _PangoFontMetrics
  * PangoFontFamily
  */
 
+/**
+ * PANGO_TYPE_FONT_FAMILY:
+ *
+ * The #GObject type for #PangoFontFamily.
+ */
+/**
+ * PANGO_FONT_FAMILY:
+ * @object: a #GObject.
+ *
+ * Casts a #GObject to a #PangoFontFamily.
+ */
+/**
+ * PANGO_IS_FONT_FAMILY:
+ * @object: a #GObject.
+ *
+ * Returns: %TRUE if @object is a #PangoFontFamily.
+ */
 #define PANGO_TYPE_FONT_FAMILY              (pango_font_family_get_type ())
 #define PANGO_FONT_FAMILY(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_FAMILY, PangoFontFamily))
 #define PANGO_IS_FONT_FAMILY(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_FAMILY))
@@ -223,6 +355,14 @@ gboolean   pango_font_family_is_monospace         (PangoFontFamily  *family) G_G
 
 typedef struct _PangoFontFamilyClass PangoFontFamilyClass;
 
+
+/**
+ * PangoFontFamily:
+ *
+ * The #PangoFontFamily structure is used to represent a family of related
+ * font faces. The faces in a family share a common design, but differ in
+ * slant, weight, width and other aspects.
+ */
 struct _PangoFontFamily
 {
   GObject parent_instance;
@@ -254,6 +394,23 @@ struct _PangoFontFamilyClass
  * PangoFontFace
  */
 
+/**
+ * PANGO_TYPE_FONT_FACE:
+ *
+ * The #GObject type for #PangoFontFace.
+ */
+/**
+ * PANGO_FONT_FACE:
+ * @object: a #GObject.
+ *
+ * Casts a #GObject to a #PangoFontFace.
+ */
+/**
+ * PANGO_IS_FONT_FACE:
+ * @object: a #GObject.
+ *
+ * Returns: %TRUE if @object is a #PangoFontFace.
+ */
 #define PANGO_TYPE_FONT_FACE              (pango_font_face_get_type ())
 #define PANGO_FONT_FACE(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_FACE, PangoFontFace))
 #define PANGO_IS_FONT_FACE(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_FACE))
@@ -275,6 +432,12 @@ gboolean              pango_font_face_is_synthesized (PangoFontFace  *face) G_GN
 
 typedef struct _PangoFontFaceClass   PangoFontFaceClass;
 
+/**
+ * PangoFontFace:
+ *
+ * The #PangoFontFace structure is used to represent a group of fonts with
+ * the same family, slant, weight, width, but varying sizes.
+ */
 struct _PangoFontFace
 {
   GObject parent_instance;
@@ -306,6 +469,23 @@ struct _PangoFontFaceClass
  * PangoFont
  */
 
+/**
+ * PANGO_TYPE_FONT:
+ *
+ * The #GObject type for #PangoFont.
+ */
+/**
+ * PANGO_FONT:
+ * @object: a #GObject.
+ *
+ * Casts a #GObject to a #PangoFont.
+ */
+/**
+ * PANGO_IS_FONT:
+ * @object: a #GObject.
+ *
+ * Returns: %TRUE if @object is a #PangoFont.
+ */
 #define PANGO_TYPE_FONT              (pango_font_get_type ())
 #define PANGO_FONT(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT, PangoFont))
 #define PANGO_IS_FONT(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT))
@@ -335,6 +515,22 @@ PangoFontMap         *pango_font_get_font_map      (PangoFont        *font);
 
 typedef struct _PangoFontClass       PangoFontClass;
 
+/**
+ * PangoFont:
+ *
+ * The #PangoFont structure is used to represent
+ * a font in a rendering-system-independent matter.
+ * To create an implementation of a #PangoFont,
+ * the rendering-system specific code should allocate
+ * a larger structure that contains a nested
+ * #PangoFont, fill in the <structfield>klass</structfield> member of
+ * the nested #PangoFont with a pointer to
+ * a appropriate #PangoFontClass, then call
+ * pango_font_init() on the structure.
+ *
+ * The #PangoFont structure contains one member
+ * which the implementation fills in.
+ */
 struct _PangoFont
 {
   GObject parent_instance;
@@ -375,6 +571,44 @@ struct _PangoFontClass
 
 #endif /* PANGO_ENABLE_BACKEND */
 
+/**
+ * PANGO_GLYPH_EMPTY:
+ *
+ * The %PANGO_GLYPH_EMPTY macro represents a #PangoGlyph value that has a
+ *  special meaning, which is a zero-width empty glyph.  This is useful for
+ * example in shaper modules, to use as the glyph for various zero-width
+ * Unicode characters (those passing pango_is_zero_width()).
+ */
+/**
+ * PANGO_GLYPH_INVALID_INPUT:
+ *
+ * The %PANGO_GLYPH_INVALID_INPUT macro represents a #PangoGlyph value that has a
+ * special meaning of invalid input.  #PangoLayout produces one such glyph
+ * per invalid input UTF-8 byte and such a glyph is rendered as a crossed
+ * box.
+ *
+ * Note that this value is defined such that it has the %PANGO_GLYPH_UNKNOWN_FLAG
+ * on.
+ *
+ * Since: 1.20
+ */
+/**
+ * PANGO_GLYPH_UNKNOWN_FLAG:
+ *
+ * The %PANGO_GLYPH_UNKNOWN_FLAG macro is a flag value that can be added to
+ * a #gunichar value of a valid Unicode character, to produce a #PangoGlyph
+ * value, representing an unknown-character glyph for the respective #gunichar.
+ */
+/**
+ * PANGO_GET_UNKNOWN_GLYPH:
+ * @wc: a Unicode character
+ *
+ * The way this unknown glyphs are rendered is backend specific.  For example,
+ * a box with the hexadecimal Unicode code-point of the character written in it
+ * is what is done in the most common backends.
+ *
+ * Returns: a #PangoGlyph value that means no glyph was found for @wc.
+ */
 #define PANGO_GLYPH_EMPTY           ((PangoGlyph)0x0FFFFFFF)
 #define PANGO_GLYPH_INVALID_INPUT   ((PangoGlyph)0xFFFFFFFF)
 #define PANGO_GLYPH_UNKNOWN_FLAG    ((PangoGlyph)0x10000000)
diff --git a/pango/pango-fontmap.h b/pango/pango-fontmap.h
index 9f31801c..207bac77 100644
--- a/pango/pango-fontmap.h
+++ b/pango/pango-fontmap.h
@@ -27,6 +27,23 @@
 
 G_BEGIN_DECLS
 
+/**
+ * PANGO_TYPE_FONT_MAP:
+ *
+ * The #GObject type for #PangoFontMap.
+ */
+/**
+ * PANGO_FONT_MAP:
+ * @object: a #GObject.
+ *
+ * Casts a #GObject to a #PangoFontMap.
+ */
+/**
+ * PANGO_IS_FONT_MAP:
+ * @object: a #GObject.
+ *
+ * Returns: %TRUE if @object is a #PangoFontMap.
+ */
 #define PANGO_TYPE_FONT_MAP              (pango_font_map_get_type ())
 #define PANGO_FONT_MAP(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_MAP, PangoFontMap))
 #define PANGO_IS_FONT_MAP(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_MAP))
@@ -50,17 +67,68 @@ void          pango_font_map_changed       (PangoFontMap                 *fontma
 
 #ifdef PANGO_ENABLE_BACKEND
 
+/**
+ * PANGO_FONT_MAP_CLASS:
+ * @klass: a #GObject.
+ *
+ * Casts a #GObject to a #PangoFontMapClass.
+ */
+/**
+ * PANGO_IS_FONT_MAP_CLASS:
+ * @klass: a #GObject.
+ *
+ * Returns: %TRUE if @klass is a subtype of #PangoFontMapClass.
+ */
+/**
+ * PANGO_FONT_MAP_GET_CLASS:
+ * @obj: a #PangoFontMap.
+ *
+ * Returns: class of @obj
+ */
 #define PANGO_FONT_MAP_CLASS(klass)      (G_TYPE_CHECK_CLASS_CAST ((klass), PANGO_TYPE_FONT_MAP, PangoFontMapClass))
 #define PANGO_IS_FONT_MAP_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_FONT_MAP))
 #define PANGO_FONT_MAP_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_FONT_MAP, PangoFontMapClass))
 
 typedef struct _PangoFontMapClass PangoFontMapClass;
 
+/**
+ * PangoFontMap:
+ *
+ * The #PangoFontMap represents the set of fonts available for a
+ * particular rendering system. This is a virtual object with
+ * implementations being specific to particular rendering systems.  To
+ * create an implementation of a #PangoFontMap, the rendering-system
+ * specific code should allocate a larger structure that contains a nested
+ * #PangoFontMap, fill in the <structfield>klass</structfield> member of the nested #PangoFontMap with a
+ * pointer to a appropriate #PangoFontMapClass, then call
+ * pango_font_map_init() on the structure.
+ *
+ * The #PangoFontMap structure contains one member which the implementation
+ * fills in.
+ */
 struct _PangoFontMap
 {
   GObject parent_instance;
 };
 
+/**
+ * PangoFontMapClass:
+ * @parent_class: parent #GObjectClass.
+ * @load_font: a function to load a font with a given description. See
+ * pango_font_map_load_font().
+ * @list_families: A function to list available font families. See
+ * pango_font_map_list_families().
+ * @load_fontset: a function to load a fontset with a given given description
+ * suitable for a particular language. See pango_font_map_load_fontset().
+ * @shape_engine_type: the type of rendering-system-dependent engines that
+ * can handle fonts of this fonts loaded with this fontmap.
+ * @get_serial: a function to get the serial number of the fontmap.
+ * See pango_font_map_get_serial().
+ * @changed: See pango_font_map_changed()
+ *
+ * The #PangoFontMapClass structure holds the virtual functions for
+ * a particular #PangoFontMap implementation.
+ */
 struct _PangoFontMapClass
 {
   GObjectClass parent_class;
diff --git a/pango/pango-fontset.h b/pango/pango-fontset.h
index 282c2cd9..7aa7d30e 100644
--- a/pango/pango-fontset.h
+++ b/pango/pango-fontset.h
@@ -33,6 +33,11 @@ G_BEGIN_DECLS
  * PangoFontset
  */
 
+/**
+ * PANGO_TYPE_FONTSET:
+ *
+ * The #GObject type for #PangoFontset.
+ */
 #define PANGO_TYPE_FONTSET              (pango_fontset_get_type ())
 #define PANGO_FONTSET(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONTSET, PangoFontset))
 #define PANGO_IS_FONTSET(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONTSET))
@@ -73,11 +78,35 @@ typedef struct _PangoFontsetClass   PangoFontsetClass;
 #define PANGO_IS_FONTSET_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_FONTSET))
 #define PANGO_FONTSET_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_FONTSET, PangoFontsetClass))
 
+/**
+ * PangoFontset:
+ *
+ * A #PangoFontset represents a set of #PangoFont to use
+ * when rendering text. It is the result of resolving a
+ * #PangoFontDescription against a particular #PangoContext.
+ * It has operations for finding the component font for
+ * a particular Unicode character, and for finding a composite
+ * set of metrics for the entire fontset.
+ */
 struct _PangoFontset
 {
   GObject parent_instance;
 };
 
+/**
+ * PangoFontsetClass:
+ * @parent_class: parent #GObjectClass.
+ * @get_font: a function to get the font in the fontset that contains the
+ * best glyph for the given Unicode character; see pango_fontset_get_font().
+ * @get_metrics: a function to get overall metric information for the fonts
+ * in the fontset; see pango_fontset_get_metrics().
+ * @get_language: a function to get the language of the fontset.
+ * @foreach: a function to loop over the fonts in the fontset. See
+ * pango_fontset_foreach().
+ *
+ * The #PangoFontsetClass structure holds the virtual functions for
+ * a particular #PangoFontset implementation.
+ */
 struct _PangoFontsetClass
 {
   GObjectClass parent_class;
@@ -106,6 +135,19 @@ struct _PangoFontsetClass
  * PangoFontsetSimple
  */
 
+/**
+ * PANGO_TYPE_FONTSET_SIMPLE:
+ *
+ * The #GObject type for #PangoFontsetSimple.
+ */
+/**
+ * PangoFontsetSimple:
+ *
+ * #PangoFontsetSimple is a implementation of the abstract
+ * #PangoFontset base class in terms of an array of fonts,
+ * which the creator provides when constructing the
+ * #PangoFontsetSimple.
+ */
 #define PANGO_TYPE_FONTSET_SIMPLE       (pango_fontset_simple_get_type ())
 #define PANGO_FONTSET_SIMPLE(object)    (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONTSET_SIMPLE, PangoFontsetSimple))
 #define PANGO_IS_FONTSET_SIMPLE(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONTSET_SIMPLE))
diff --git a/pango/pango-glyph-item.h b/pango/pango-glyph-item.h
index 71c4ab31..61b5ec47 100644
--- a/pango/pango-glyph-item.h
+++ b/pango/pango-glyph-item.h
@@ -29,6 +29,15 @@
 
 G_BEGIN_DECLS
 
+/**
+ * PangoGlyphItem:
+ *
+ * A #PangoGlyphItem is a pair of a #PangoItem and the glyphs
+ * resulting from shaping the text corresponding to an item.
+ * As an example of the usage of #PangoGlyphItem, the results
+ * of shaping text with #PangoLayout is a list of #PangoLayoutLine,
+ * each of which contains a list of #PangoGlyphItem.
+ */
 typedef struct _PangoGlyphItem PangoGlyphItem;
 
 struct _PangoGlyphItem
@@ -37,6 +46,11 @@ struct _PangoGlyphItem
   PangoGlyphString *glyphs;
 };
 
+/**
+ * PANGO_TYPE_GLYPH_ITEM:
+ *
+ * The #GObject type for #PangoGlyphItem.
+ */
 #define PANGO_TYPE_GLYPH_ITEM (pango_glyph_item_get_type ())
 
 GType pango_glyph_item_get_type (void) G_GNUC_CONST;
@@ -58,6 +72,49 @@ void 	  pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item,
 					       int            *logical_widths);
 
 
+/**
+ * PangoGlyphItemIter:
+ *
+ * A #PangoGlyphItemIter is an iterator over the clusters in a
+ * #PangoGlyphItem.  The <firstterm>forward direction</firstterm> of the
+ * iterator is the logical direction of text.  That is, with increasing
+ * @start_index and @start_char values.  If @glyph_item is right-to-left
+ * (that is, if <literal>@glyph_item->item->analysis.level</literal> is odd),
+ * then @start_glyph decreases as the iterator moves forward.  Moreover,
+ * in right-to-left cases, @start_glyph is greater than @end_glyph.
+ *
+ * An iterator should be initialized using either of
+ * pango_glyph_item_iter_init_start() and
+ * pango_glyph_item_iter_init_end(), for forward and backward iteration
+ * respectively, and walked over using any desired mixture of
+ * pango_glyph_item_iter_next_cluster() and
+ * pango_glyph_item_iter_prev_cluster().  A common idiom for doing a
+ * forward iteration over the clusters is:
+ * <programlisting>
+ * PangoGlyphItemIter cluster_iter;
+ * gboolean have_cluster;
+ *
+ * for (have_cluster = pango_glyph_item_iter_init_start (&amp;cluster_iter,
+ *                                                       glyph_item, text);
+ *      have_cluster;
+ *      have_cluster = pango_glyph_item_iter_next_cluster (&amp;cluster_iter))
+ * {
+ *   ...
+ * }
+ * </programlisting>
+ *
+ * Note that @text is the start of the text for layout, which is then
+ * indexed by <literal>@glyph_item->item->offset</literal> to get to the
+ * text of @glyph_item.  The @start_index and @end_index values can directly
+ * index into @text.  The @start_glyph, @end_glyph, @start_char, and @end_char
+ * values however are zero-based for the @glyph_item.  For each cluster, the
+ * item pointed at by the start variables is included in the cluster while
+ * the one pointed at by end variables is not.
+ *
+ * None of the members of a #PangoGlyphItemIter should be modified manually.
+ *
+ * Since: 1.22
+ */
 typedef struct _PangoGlyphItemIter PangoGlyphItemIter;
 
 struct _PangoGlyphItemIter
@@ -74,6 +131,13 @@ struct _PangoGlyphItemIter
   int end_char;
 };
 
+/**
+ * PANGO_TYPE_GLYPH_ITEM_ITER:
+ *
+ * The #GObject type for #PangoGlyphItemIter.
+ *
+ * Since: 1.22
+ */
 #define PANGO_TYPE_GLYPH_ITEM_ITER (pango_glyph_item_iter_get_type ())
 
 GType               pango_glyph_item_iter_get_type (void) G_GNUC_CONST;
diff --git a/pango/pango-glyph.h b/pango/pango-glyph.h
index 91bae32a..4b25d084 100644
--- a/pango/pango-glyph.h
+++ b/pango/pango-glyph.h
@@ -33,10 +33,30 @@ typedef struct _PangoGlyphInfo PangoGlyphInfo;
 typedef struct _PangoGlyphString PangoGlyphString;
 
 /* 1024ths of a device unit */
+/**
+ * PangoGlyphUnit:
+ *
+ * The #PangoGlyphUnit type is used to store dimensions within
+ * Pango. Dimensions are stored in 1/%PANGO_SCALE of a device unit.
+ * (A device unit might be a pixel for screen display, or
+ * a point on a printer.) %PANGO_SCALE is currently 1024, and
+ * may change in the future (unlikely though), but you should not
+ * depend on its exact value. The PANGO_PIXELS() macro can be used
+ * to convert from glyph units into device units with correct rounding.
+ */
 typedef gint32 PangoGlyphUnit;
 
 /* Positioning information about a glyph
  */
+/**
+ * PangoGlyphGeometry:
+ * @width: the logical width to use for the the character.
+ * @x_offset: horizontal offset from nominal character position.
+ * @y_offset: vertical offset from nominal character position.
+ *
+ * The #PangoGlyphGeometry structure contains width and positioning
+ * information for a single glyph.
+ */
 struct _PangoGlyphGeometry
 {
   PangoGlyphUnit width;
@@ -46,6 +66,18 @@ struct _PangoGlyphGeometry
 
 /* Visual attributes of a glyph
  */
+/**
+ * PangoGlyphVisAttr:
+ * @is_cluster_start: set for the first logical glyph in each cluster. (Clusters
+ * are stored in visual order, within the cluster, glyphs
+ * are always ordered in logical order, since visual
+ * order is meaningless; that is, in Arabic text, accent glyphs
+ * follow the glyphs for the base character.)
+ *
+ * The PangoGlyphVisAttr is used to communicate information between
+ * the shaping phase and the rendering phase.  More attributes may be
+ * added in the future.
+ */
 struct _PangoGlyphVisAttr
 {
   guint is_cluster_start : 1;
@@ -53,6 +85,16 @@ struct _PangoGlyphVisAttr
 
 /* A single glyph
  */
+/**
+ * PangoGlyphInfo:
+ * @glyph: the glyph itself.
+ * @geometry: the positional information about the glyph.
+ * @attr: the visual attributes of the glyph.
+ *
+ * The #PangoGlyphInfo structure represents a single glyph together with
+ * positioning information and visual attributes.
+ * It contains the following fields.
+ */
 struct _PangoGlyphInfo
 {
   PangoGlyph    glyph;
@@ -63,6 +105,14 @@ struct _PangoGlyphInfo
 /* A string of glyphs with positional information and visual attributes -
  * ready for drawing
  */
+/**
+ * PangoGlyphString:
+ *
+ * The #PangoGlyphString structure is used to store strings
+ * of glyphs with geometry and visual attribute information.
+ * The storage for the glyph information is owned
+ * by the structure which simplifies memory management.
+ */
 struct _PangoGlyphString {
   gint num_glyphs;
 
@@ -79,6 +129,11 @@ struct _PangoGlyphString {
   gint space;
 };
 
+/**
+ * PANGO_TYPE_GLYPH_STRING:
+ *
+ * The #GObject type for #PangoGlyphString.
+ */
 #define PANGO_TYPE_GLYPH_STRING (pango_glyph_string_get_type ())
 
 PangoGlyphString *pango_glyph_string_new      (void);
diff --git a/pango/pango-gravity.c b/pango/pango-gravity.c
index 603c3776..a72b67bc 100644
--- a/pango/pango-gravity.c
+++ b/pango/pango-gravity.c
@@ -19,6 +19,64 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:vertical
+ * @short_description:Laying text out in vertical directions
+ * @title:Vertical Text
+ * @see_also: pango_context_get_base_gravity(),
+ * pango_context_set_base_gravity(),
+ * pango_context_get_gravity(),
+ * pango_context_get_gravity_hint(),
+ * pango_context_set_gravity_hint(),
+ * pango_font_description_set_gravity(),
+ * pango_font_description_get_gravity(),
+ * pango_attr_gravity_new(),
+ * pango_attr_gravity_hint_new()
+ *
+ * Since 1.16, Pango is able to correctly lay vertical text out.  In fact, it can
+ * set layouts of mixed vertical and non-vertical text.  This section describes
+ * the types used for setting vertical text parameters.
+ *
+ * The way this is implemented is through the concept of
+ * <firstterm>gravity</firstterm>.  Gravity of normal Latin text is south.  A
+ * gravity value of east means that glyphs will be rotated ninety degrees
+ * counterclockwise.  So, to render vertical text one needs to set the gravity
+ * and rotate the layout using the matrix machinery already in place.  This has
+ * the huge advantage that most algorithms working on a #PangoLayout do not need
+ * any change as the assumption that lines run in the X direction and stack in
+ * the Y direction holds even for vertical text layouts.
+ *
+ * Applications should only need to set base gravity on #PangoContext in use, and
+ * let Pango decide the gravity assigned to each run of text.  This automatically
+ * handles text with mixed scripts.  A very common use is to set the context base
+ * gravity to auto using pango_context_set_base_gravity()
+ * and rotate the layout normally.  Pango will make sure that
+ * Asian languages take the right form, while other scripts are rotated normally.
+ *
+ * The correct way to set gravity on a layout is to set it on the context
+ * associated with it using pango_context_set_base_gravity().  The context
+ * of a layout can be accessed using pango_layout_get_context().  The currently
+ * set base gravity of the context can be accessed using
+ * pango_context_get_base_gravity() and the <firstterm>resolved</firstterm>
+ * gravity of it using pango_context_get_gravity().  The resolved gravity is
+ * the same as the base gravity for the most part, except that if the base
+ * gravity is set to %PANGO_GRAVITY_AUTO, the resolved gravity will depend
+ * on the current matrix set on context, and is derived using
+ * pango_gravity_get_for_matrix().
+ *
+ * The next thing an application may want to set on the context is the
+ * <firstterm>gravity hint</firstterm>.  A #PangoGravityHint instructs how
+ * different scripts should react to the set base gravity.
+ *
+ * Font descriptions have a gravity property too, that can be set using
+ * pango_font_description_set_gravity() and accessed using
+ * pango_font_description_get_gravity().  However, those are rarely useful
+ * from application code and are mainly used by #PangoLayout internally.
+ *
+ * Last but not least, one can create #PangoAttribute<!---->s for gravity
+ * and gravity hint using pango_attr_gravity_new() and
+ * pango_attr_gravity_hint_new().
+ */
 #include "config.h"
 
 #include "pango-gravity.h"
@@ -278,7 +336,7 @@ pango_gravity_get_for_script (PangoScript      script,
  * This function is similar to pango_gravity_get_for_script() except
  * that this function makes a distinction between narrow/half-width and
  * wide/full-width characters also.  Wide/full-width characters always
- * stand <emph>upright</emph>, that is, they always take the base gravity,
+ * stand <emphasis>upright</emphasis>, that is, they always take the base gravity,
  * whereas narrow/full-width characters are always rotated in vertical
  * context.
  *
diff --git a/pango/pango-item.h b/pango/pango-item.h
index 0775003c..b8e8ab67 100644
--- a/pango/pango-item.h
+++ b/pango/pango-item.h
@@ -30,8 +30,31 @@ typedef struct _PangoAnalysis PangoAnalysis;
 typedef struct _PangoItem PangoItem;
 
 /* TODO: if more flags are needed, turn this into a real PangoAnalysisFlags enum */
+/**
+ * PANGO_ANALYSIS_FLAG_CENTERED_BASELINE:
+ *
+ * Whether the segment should be shifted to center around the baseline.
+ * Used in vertical writing directions mostly.
+ *
+ * Since: 1.16
+ */
 #define PANGO_ANALYSIS_FLAG_CENTERED_BASELINE (1 << 0)
 
+/**
+ * PangoAnalysis:
+ * @shape_engine: the engine for doing rendering-system-dependent processing.
+ * @lang_engine: the engine for doing rendering-system-independent processing.
+ * @font: the font for this segment.
+ * @level: the bidirectional level for this segment.
+ * @gravity: the glyph orientation for this segment (A #PangoGravity).
+ * @flags: boolean flags for this segment (currently only one) (Since: 1.16).
+ * @script: the detected script for this segment (A #PangoScript) (Since: 1.18).
+ * @language: the detected language for this segment.
+ * @extra_attrs: extra attributes for this segment.
+ *
+ * The #PangoAnalysis structure stores information about
+ * the properties of a segment of text.
+ */
 struct _PangoAnalysis
 {
   PangoEngineShape *shape_engine;
@@ -48,6 +71,11 @@ struct _PangoAnalysis
   GSList *extra_attrs;
 };
 
+/**
+ * PangoItem:
+ *
+ * The #PangoItem structure stores information abouta segment of text.
+ */
 struct _PangoItem
 {
   gint offset;
diff --git a/pango/pango-language.c b/pango/pango-language.c
index 7fc7078e..15d5fb64 100644
--- a/pango/pango-language.c
+++ b/pango/pango-language.c
@@ -133,6 +133,15 @@ pango_language_free (PangoLanguage *language G_GNUC_UNUSED)
   return; /* nothing */
 }
 
+/**
+ * PangoLanguage:
+ *
+ * The #PangoLanguage structure is used to
+ * represent a language.
+ *
+ * #PangoLanguage pointers can be efficiently
+ * copied and compared with each other.
+ */
 G_DEFINE_BOXED_TYPE (PangoLanguage, pango_language,
                      pango_language_copy,
                      pango_language_free);
diff --git a/pango/pango-language.h b/pango/pango-language.h
index 31660ca3..8648a3a6 100644
--- a/pango/pango-language.h
+++ b/pango/pango-language.h
@@ -29,6 +29,11 @@ G_BEGIN_DECLS
 
 typedef struct _PangoLanguage PangoLanguage;
 
+/**
+ * PANGO_TYPE_LANGUAGE:
+ *
+ * The #GObject type for #PangoLanguage.
+ */
 #define PANGO_TYPE_LANGUAGE (pango_language_get_type ())
 
 GType          pango_language_get_type    (void) G_GNUC_CONST;
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 82a3283c..a024d11b 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -19,6 +19,54 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:layout
+ * @short_description:High-level layout driver objects
+ * @title:Layout Objects
+ *
+ * While complete access to the layout capabilities of Pango is provided
+ * using the detailed interfaces for itemization and shaping, using
+ * that functionality directly involves writing a fairly large amount
+ * of code. The objects and functions in this section provide a
+ * high-level driver for formatting entire paragraphs of text
+ * at once.
+ */
+
+/**
+ * PangoLayout:
+ *
+ * The #PangoLayout structure represents an entire paragraph
+ * of text. It is initialized with a #PangoContext, UTF-8 string
+ * and set of attributes for that string. Once that is done, the
+ * set of formatted lines can be extracted from the object,
+ * the layout can be rendered, and conversion between logical
+ * character positions within the layout's text, and the physical
+ * position of the resulting glyphs can be made.
+ *
+ * There are also a number of parameters to adjust the formatting
+ * of a #PangoLayout, which are illustrated in <xref linkend="parameters"/>.
+ * It is possible, as well, to ignore the 2-D setup, and simply
+ * treat the results of a #PangoLayout as a list of lines.
+ *
+ * <figure id="parameters">
+ * <title>Adjustable parameters for a PangoLayout</title>
+ * <graphic fileref="layout.gif" format="GIF"></graphic>
+ * </figure>
+ *
+ * The #PangoLayout structure is opaque, and has no user-visible
+ * fields.
+ */
+
+/**
+ * PangoLayoutIter:
+ *
+ * A #PangoLayoutIter structure can be used to
+ * iterate over the visual extents of a #PangoLayout.
+ *
+ * The #PangoLayoutIter structure is opaque, and
+ * has no user-visible fields.
+ */
+
 #include "config.h"
 #include "pango-glyph.h"		/* For pango_shape() */
 #include "pango-break.h"
@@ -1967,7 +2015,7 @@ pango_layout_move_cursor_visually (PangoLayout *layout,
  * Y position is not inside the layout, the closest position is chosen
  * (the position will be clamped inside the layout). If the
  * X position is not within the layout, then the start or the
- * end of the line is chosen as  described for pango_layout_x_to_index().
+ * end of the line is chosen as  described for pango_layout_xy_to_index().
  * If either the X or Y positions were not inside the layout, then the
  * function returns %FALSE; on an exact hit, it returns %TRUE.
  *
diff --git a/pango/pango-layout.h b/pango/pango-layout.h
index 8177612c..25ce9cf4 100644
--- a/pango/pango-layout.h
+++ b/pango/pango-layout.h
@@ -33,14 +33,41 @@ typedef struct _PangoLayout      PangoLayout;
 typedef struct _PangoLayoutClass PangoLayoutClass;
 typedef struct _PangoLayoutLine  PangoLayoutLine;
 
+/**
+ * PangoLayoutRun:
+ *
+ * The #PangoLayoutRun structure represents a single run within
+ * a #PangoLayoutLine; it is simply an alternate name for
+ * #PangoGlyphItem.
+ * See the #PangoGlyphItem docs for details on the fields.
+ */
 typedef PangoGlyphItem PangoLayoutRun;
 
+/**
+ * PangoAlignment:
+ * @PANGO_ALIGN_LEFT: Put all available space on the right
+ * @PANGO_ALIGN_CENTER: Center the line within the available space
+ * @PANGO_ALIGN_RIGHT: Put all available space on the left
+ *
+ * A #PangoAlignment describes how to align the lines of a #PangoLayout within the
+ * available space. If the #PangoLayout is set to justify
+ * using pango_layout_set_justify(), this only has effect for partial lines.
+ */
 typedef enum {
   PANGO_ALIGN_LEFT,
   PANGO_ALIGN_CENTER,
   PANGO_ALIGN_RIGHT
 } PangoAlignment;
 
+/**
+ * PangoWrapMode:
+ * @PANGO_WRAP_WORD: wrap lines at word boundaries.
+ * @PANGO_WRAP_CHAR: wrap lines at character boundaries.
+ * @PANGO_WRAP_WORD_CHAR: wrap lines at word boundaries, but fall back to character boundaries if there is not
+ * enough space for a full word.
+ *
+ * A #PangoWrapMode describes how to wrap the lines of a #PangoLayout to the desired width.
+ */
 typedef enum {
   PANGO_WRAP_WORD,
   PANGO_WRAP_CHAR,
@@ -67,6 +94,22 @@ typedef enum {
   PANGO_ELLIPSIZE_END
 } PangoEllipsizeMode;
 
+/**
+ * PangoLayoutLine:
+ * @start_index: start of line as byte index into layout->text
+ * @length: length of line in bytes
+ * @is_paragraph_start: #TRUE if this is the first line of the paragraph
+ * @resolved_dir: #Resolved PangoDirection of line
+ *
+ * The #PangoLayoutLine structure represents one of the lines resulting
+ * from laying out a paragraph via #PangoLayout. #PangoLayoutLine
+ * structures are obtained by calling pango_layout_get_line() and
+ * are only valid until the text, attributes, or settings of the
+ * parent #PangoLayout are modified.
+ *
+ * Routines for rendering PangoLayout objects are provided in
+ * code specific to each rendering system.
+ */
 struct _PangoLayoutLine
 {
   PangoLayout *layout;
diff --git a/pango/pango-modules.h b/pango/pango-modules.h
index 5dbcfe9f..aec79e76 100644
--- a/pango/pango-modules.h
+++ b/pango/pango-modules.h
@@ -33,6 +33,17 @@ typedef struct _PangoMapEntry PangoMapEntry;
 
 typedef struct _PangoIncludedModule PangoIncludedModule;
 
+/**
+ * PangoIncludedModule:
+ * @list: a function that lists the engines defined in this module.
+ * @init: a function to initialize the module.
+ * @exit: a function to finalize the module.
+ * @create: a function to create an engine, given the engine name.
+ *
+ * The #PangoIncludedModule structure for a statically linked module
+ * contains the functions that would otherwise be loaded from a dynamically
+ * loaded module.
+ */
 struct _PangoIncludedModule
 {
   void (*list) (PangoEngineInfo **engines,
diff --git a/pango/pango-ot-buffer.c b/pango/pango-ot-buffer.c
index 11637306..35d66bce 100644
--- a/pango/pango-ot-buffer.c
+++ b/pango/pango-ot-buffer.c
@@ -82,7 +82,7 @@ pango_ot_buffer_clear (PangoOTBuffer *buffer)
  * @cluster: the cluster that this glyph belongs to
  *
  * Appends a glyph to a #PangoOTBuffer, with @properties identifying which
- * features should be applied on this glyph.  See pango_ruleset_add_feature().
+ * features should be applied on this glyph.  See pango_ot_ruleset_add_feature().
  *
  * Since: 1.4
  **/
diff --git a/pango/pango-ot-info.c b/pango/pango-ot-info.c
index cd1778df..f6dc1ac0 100644
--- a/pango/pango-ot-info.c
+++ b/pango/pango-ot-info.c
@@ -19,6 +19,16 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:opentype
+ * @short_description:Obtaining information from OpenType tables
+ * @title:OpenType Font Handling
+ * @stability:Unstable
+ *
+ * Functions and macros in this section are used to implement the OpenType Layout
+ * features and algorithms.  These are mostly useful when writing Fontconfig-based
+ * shaping engines
+ */
 #include "config.h"
 
 #include "pango-ot-private.h"
diff --git a/pango/pango-ot-private.h b/pango/pango-ot-private.h
index 81ae7e84..0d803ec1 100644
--- a/pango/pango-ot-private.h
+++ b/pango/pango-ot-private.h
@@ -35,6 +35,15 @@ G_BEGIN_DECLS
 
 typedef struct _PangoOTInfoClass PangoOTInfoClass;
 
+/**
+ * PangoOTInfo:
+ *
+ * The #PangoOTInfo struct contains the various
+ * tables associated with an OpenType font. It contains only private fields and
+ * should only be accessed via the <function>pango_ot_info_*</function> functions
+ * which are documented below. To obtain a #PangoOTInfo,
+ * use pango_ot_info_get().
+ */
 struct _PangoOTInfo
 {
   GObject parent_instance;
@@ -61,6 +70,15 @@ struct _PangoOTRulesetClass
   GObjectClass parent_class;
 };
 
+/**
+ * PangoOTBuffer:
+ *
+ * The #PangoOTBuffer structure is used to store strings of glyphs associated
+ * with a #PangoFcFont, suitable for OpenType layout processing.  It contains
+ * only private fields and should only be accessed via the
+ * <function>pango_ot_buffer_*</function> functions which are documented below.
+ * To obtain a #PangoOTBuffer, use pango_ot_buffer_new().
+ */
 struct _PangoOTBuffer
 {
   hb_buffer_t *buffer;
diff --git a/pango/pango-ot-ruleset.c b/pango/pango-ot-ruleset.c
index 93ba6174..2d8f1503 100644
--- a/pango/pango-ot-ruleset.c
+++ b/pango/pango-ot-ruleset.c
@@ -25,6 +25,18 @@
 
 static void pango_ot_ruleset_finalize   (GObject        *object);
 
+/**
+ * PangoOTRuleset:
+ *
+ * The #PangoOTRuleset structure holds a
+ * set of features selected from the tables in an OpenType font.
+ * (A feature is an operation such as adjusting glyph positioning
+ * that should be applied to a text feature such as a certain
+ * type of accent.) A #PangoOTRuleset
+ * is created with pango_ot_ruleset_new(), features are added
+ * to it with pango_ot_ruleset_add_feature(), then it is
+ * applied to a #PangoGlyphString with pango_ot_ruleset_shape().
+ */
 G_DEFINE_TYPE (PangoOTRuleset, pango_ot_ruleset, G_TYPE_OBJECT);
 
 static void
diff --git a/pango/pango-ot.h b/pango/pango-ot.h
index cca5ef51..a27ed201 100644
--- a/pango/pango-ot.h
+++ b/pango/pango-ot.h
@@ -34,8 +34,35 @@ G_BEGIN_DECLS
 
 #ifdef PANGO_ENABLE_ENGINE
 
+/**
+ * PangoOTTag:
+ *
+ * The #PangoOTTag typedef is used to represent TrueType and OpenType
+ * four letter tags inside Pango. Use PANGO_OT_TAG_MAKE()
+ * or PANGO_OT_TAG_MAKE_FROM_STRING() macros to create <type>PangoOTTag</type>s manually.
+ */
 typedef guint32 PangoOTTag;
 
+/**
+ * PANGO_OT_TAG_MAKE:
+ * @c1: First character.
+ * @c2: Second character.
+ * @c3: Third character.
+ * @c4: Fourth character.
+ *
+ * Creates a #PangoOTTag from four characters.  This is similar and
+ * compatible with the <function>FT_MAKE_TAG()</function> macro from FreeType.
+ */
+/**
+ * PANGO_OT_TAG_MAKE_FROM_STRING:
+ * @s: The string representation of the tag.
+ *
+ * Creates a #PangoOTTag from a string. The string should be at least
+ * four characters long (pad with space characters if needed), and need
+ * not be nul-terminated.  This is a convenience wrapper around
+ * PANGO_OT_TAG_MAKE(), but cannot be used in certain situations, for
+ * example, as a switch expression, as it dereferences pointers.
+ */
 #define PANGO_OT_TAG_MAKE(c1,c2,c3,c4)		((PangoOTTag) FT_MAKE_TAG (c1, c2, c3, c4))
 #define PANGO_OT_TAG_MAKE_FROM_STRING(s)	(PANGO_OT_TAG_MAKE(((const char *) s)[0], \
 								   ((const char *) s)[1], \
@@ -49,21 +76,109 @@ typedef struct _PangoOTRuleset    PangoOTRuleset;
 typedef struct _PangoOTFeatureMap PangoOTFeatureMap;
 typedef struct _PangoOTRulesetDescription PangoOTRulesetDescription;
 
+/**
+ * PangoOTTableType:
+ * @PANGO_OT_TABLE_GSUB: The GSUB table.
+ * @PANGO_OT_TABLE_GPOS: The GPOS table.
+ *
+ * The <type>PangoOTTableType</type> enumeration values are used to
+ * identify the various OpenType tables in the
+ * <function>pango_ot_info_*</function> functions.
+ */
 typedef enum
 {
   PANGO_OT_TABLE_GSUB,
   PANGO_OT_TABLE_GPOS
 } PangoOTTableType;
 
+/**
+ * PANGO_OT_ALL_GLYPHS:
+ *
+ * This is used as the property bit in pango_ot_ruleset_add_feature() when a
+ * feature should be applied to all glyphs.
+ *
+ * Since: 1.16
+ */
+/**
+ * PANGO_OT_NO_FEATURE:
+ *
+ * This is used as a feature index that represent no feature, that is, should be
+ * skipped.  It may be returned as feature index by pango_ot_info_find_feature()
+ * if the feature is not found, and pango_ot_ruleset_add_feature() function
+ * automatically skips this value, so no special handling is required by the user.
+ *
+ * Since: 1.18
+ */
+/**
+ * PANGO_OT_NO_SCRIPT:
+ *
+ * This is used as a script index that represent no script, that is, when the
+ * requested script was not found, and a default ('DFLT') script was not found
+ * either.  It may be returned as script index by pango_ot_info_find_script()
+ * if the script or a default script are not found, all other functions
+ * taking a script index essentially return if the input script index is
+ * this value, so no special handling is required by the user.
+ *
+ * Since: 1.18
+ */
+/**
+ * PANGO_OT_DEFAULT_LANGUAGE:
+ *
+ * This is used as the language index in pango_ot_info_find_feature() when
+ * the default language system of the script is desired.
+ *
+ * It is also returned by pango_ot_info_find_language() if the requested language
+ * is not found, or the requested language tag was PANGO_OT_TAG_DEFAULT_LANGUAGE.
+ * The end result is that one can always call pango_ot_tag_from_language()
+ * followed by pango_ot_info_find_language() and pass the result to
+ * pango_ot_info_find_feature() without having to worry about falling back to
+ * default language system explicitly.
+ *
+ * Since: 1.16
+ */
 #define PANGO_OT_ALL_GLYPHS			((guint) 0xFFFF)
 #define PANGO_OT_NO_FEATURE			((guint) 0xFFFF)
 #define PANGO_OT_NO_SCRIPT			((guint) 0xFFFF)
 #define PANGO_OT_DEFAULT_LANGUAGE		((guint) 0xFFFF)
 
+/**
+ * PANGO_OT_TAG_DEFAULT_SCRIPT:
+ *
+ * This is a #PangoOTTag representing the special script tag 'DFLT'.  It is
+ * returned as script tag by pango_ot_tag_from_script() if the requested script
+ * is not found.
+ *
+ * Since: 1.18
+ */
+/**
+ * PANGO_OT_TAG_DEFAULT_LANGUAGE:
+ *
+ * This is a #PangoOTTag representing a special language tag 'dflt'.  It is
+ * returned as language tag by pango_ot_tag_from_language() if the requested
+ * language is not found.  It is safe to pass this value to
+ * pango_ot_info_find_language() as that function falls back to returning default
+ * language-system if the requested language tag is not found.
+ *
+ * Since: 1.18
+ */
 #define PANGO_OT_TAG_DEFAULT_SCRIPT		PANGO_OT_TAG_MAKE ('D', 'F', 'L', 'T')
 #define PANGO_OT_TAG_DEFAULT_LANGUAGE		PANGO_OT_TAG_MAKE ('d', 'f', 'l', 't')
 
 /* Note that this must match hb_glyph_info_t */
+/**
+ * PangoOTGlyph:
+ * @glyph: the glyph itself.
+ * @properties: the properties value, identifying which features should be
+ * applied on this glyph.  See pango_ot_ruleset_add_feature().
+ * @cluster: the cluster that this glyph belongs to.
+ * @component: a component value, set by the OpenType layout engine.
+ * @ligID: a ligature index value, set by the OpenType layout engine.
+ * @internal: for Pango internal use
+ *
+ * The #PangoOTGlyph structure represents a single glyph together with
+ * information used for OpenType layout processing of the glyph.
+ * It contains the following fields.
+ */
 struct _PangoOTGlyph
 {
   guint32  glyph;
@@ -75,12 +190,46 @@ struct _PangoOTGlyph
   guint    internal;
 };
 
+/**
+ * PangoOTFeatureMap:
+ * @feature_name: feature tag in represented as four-letter ASCII string.
+ * @property_bit: the property bit to use for this feature.  See
+ * pango_ot_ruleset_add_feature() for details.
+ *
+ * The #PangoOTFeatureMap typedef is used to represent an OpenType
+ * feature with the property bit associated with it.  The feature tag is
+ * represented as a char array instead of a #PangoOTTag for convenience.
+ *
+ * Since: 1.18
+ */
 struct _PangoOTFeatureMap
 {
   char     feature_name[5];
   gulong   property_bit;
 };
 
+/**
+ * PangoOTRulesetDescription:
+ * @script: a #PangoScript.
+ * @language: a #PangoLanguage.
+ * @static_gsub_features: static map of GSUB features, or %NULL.
+ * @n_static_gsub_features: length of @static_gsub_features, or 0.
+ * @static_gpos_features: static map of GPOS features, or %NULL.
+ * @n_static_gpos_features: length of @static_gpos_features, or 0.
+ * @other_features: map of extra features to add to both GSUB and GPOS, or %NULL.
+ * Unlike the static maps, this pointer need not live beyond
+ * the life of function calls taking this struct.
+ * @n_other_features: length of @other_features, or 0.
+ *
+ * The #PangoOTRuleset structure holds all the information needed
+ * to build a complete #PangoOTRuleset from an OpenType font.
+ * The main use of this struct is to act as the key for a per-font
+ * hash of rulesets.  The user populates a ruleset description and
+ * gets the ruleset using pango_ot_ruleset_get_for_description()
+ * or create a new one using pango_ot_ruleset_new_from_description().
+ *
+ * Since: 1.18
+ */
 struct _PangoOTRulesetDescription {
   PangoScript               script;
   PangoLanguage            *language;
diff --git a/pango/pango-script.c b/pango/pango-script.c
index 92f2ef11..95dd3e9a 100644
--- a/pango/pango-script.c
+++ b/pango/pango-script.c
@@ -53,6 +53,15 @@
  * of the copyright holder.
  */
 
+/**
+ * SECTION:scripts
+ * @short_description:Identifying writing systems and languages
+ * @title:Scripts and Languages
+ *
+ * The functions in this section are used to identify the writing
+ * system, or <firstterm>script</firstterm> of individual characters
+ * and of ranges within a larger text string.
+ */
 #include "config.h"
 #include <stdlib.h>
 #include <string.h>
@@ -65,7 +74,7 @@
  * @ch: a Unicode character
  *
  * Looks up the #PangoScript for a particular character (as defined by
- * Unicode Standard Annex #24). No check is made for @ch being a
+ * Unicode Standard Annex \#24). No check is made for @ch being a
  * valid Unicode character; if you pass in invalid character, the
  * result is undefined.
  *
diff --git a/pango/pango-script.h b/pango/pango-script.h
index cc3d0ecc..e370e3e0 100644
--- a/pango/pango-script.h
+++ b/pango/pango-script.h
@@ -34,6 +34,108 @@ G_BEGIN_DECLS
  **/
 typedef struct _PangoScriptIter PangoScriptIter;
 
+/**
+ * PangoScript:
+ * @PANGO_SCRIPT_INVALID_CODE: a value never returned from pango_script_for_unichar()
+ * @PANGO_SCRIPT_COMMON: a character used by multiple different scripts
+ * @PANGO_SCRIPT_INHERITED: a mark glyph that takes its script from the
+ * base glyph to which it is attached
+ * @PANGO_SCRIPT_ARABIC: 	Arabic
+ * @PANGO_SCRIPT_ARMENIAN: Armenian
+ * @PANGO_SCRIPT_BENGALI: 	Bengali
+ * @PANGO_SCRIPT_BOPOMOFO: Bopomofo
+ * @PANGO_SCRIPT_CHEROKEE: 	Cherokee
+ * @PANGO_SCRIPT_COPTIC: 	Coptic
+ * @PANGO_SCRIPT_CYRILLIC: 	Cyrillic
+ * @PANGO_SCRIPT_DESERET: 	Deseret
+ * @PANGO_SCRIPT_DEVANAGARI: 	Devanagari
+ * @PANGO_SCRIPT_ETHIOPIC: 	Ethiopic
+ * @PANGO_SCRIPT_GEORGIAN: 	Georgian
+ * @PANGO_SCRIPT_GOTHIC: 	Gothic
+ * @PANGO_SCRIPT_GREEK: 	Greek
+ * @PANGO_SCRIPT_GUJARATI: 	Gujarati
+ * @PANGO_SCRIPT_GURMUKHI: 	Gurmukhi
+ * @PANGO_SCRIPT_HAN: 	Han
+ * @PANGO_SCRIPT_HANGUL: 	Hangul
+ * @PANGO_SCRIPT_HEBREW: 	Hebrew
+ * @PANGO_SCRIPT_HIRAGANA: 	Hiragana
+ * @PANGO_SCRIPT_KANNADA: 	Kannada
+ * @PANGO_SCRIPT_KATAKANA: 	Katakana
+ * @PANGO_SCRIPT_KHMER: 	Khmer
+ * @PANGO_SCRIPT_LAO: 	Lao
+ * @PANGO_SCRIPT_LATIN: 	Latin
+ * @PANGO_SCRIPT_MALAYALAM: 	Malayalam
+ * @PANGO_SCRIPT_MONGOLIAN: 	Mongolian
+ * @PANGO_SCRIPT_MYANMAR: 	Myanmar
+ * @PANGO_SCRIPT_OGHAM: 	Ogham
+ * @PANGO_SCRIPT_OLD_ITALIC: 	Old Italic
+ * @PANGO_SCRIPT_ORIYA: 	Oriya
+ * @PANGO_SCRIPT_RUNIC: 	Runic
+ * @PANGO_SCRIPT_SINHALA: 	Sinhala
+ * @PANGO_SCRIPT_SYRIAC: 	Syriac
+ * @PANGO_SCRIPT_TAMIL: 	Tamil
+ * @PANGO_SCRIPT_TELUGU: 	Telugu
+ * @PANGO_SCRIPT_THAANA: 	Thaana
+ * @PANGO_SCRIPT_THAI: 	Thai
+ * @PANGO_SCRIPT_TIBETAN: 	Tibetan
+ * @PANGO_SCRIPT_CANADIAN_ABORIGINAL: 	Canadian Aboriginal
+ * @PANGO_SCRIPT_YI: 	Yi
+ * @PANGO_SCRIPT_TAGALOG: 	Tagalog
+ * @PANGO_SCRIPT_HANUNOO: 	Hanunoo
+ * @PANGO_SCRIPT_BUHID: 	Buhid
+ * @PANGO_SCRIPT_TAGBANWA: 	Tagbanwa
+ * @PANGO_SCRIPT_BRAILLE: 	Braille
+ * @PANGO_SCRIPT_CYPRIOT: 	Cypriot
+ * @PANGO_SCRIPT_LIMBU: 	Limbu
+ * @PANGO_SCRIPT_OSMANYA: 	Osmanya
+ * @PANGO_SCRIPT_SHAVIAN: 	Shavian
+ * @PANGO_SCRIPT_LINEAR_B: 	Linear B
+ * @PANGO_SCRIPT_TAI_LE: 	Tai Le
+ * @PANGO_SCRIPT_UGARITIC: 	Ugaritic
+ * @PANGO_SCRIPT_NEW_TAI_LUE: 	New Tai Lue. Since 1.10
+ * @PANGO_SCRIPT_BUGINESE: 	Buginese. Since 1.10
+ * @PANGO_SCRIPT_GLAGOLITIC: 	Glagolitic. Since 1.10
+ * @PANGO_SCRIPT_TIFINAGH: 	Tifinagh. Since 1.10
+ * @PANGO_SCRIPT_SYLOTI_NAGRI: 	Syloti Nagri. Since 1.10
+ * @PANGO_SCRIPT_OLD_PERSIAN: 	Old Persian. Since 1.10
+ * @PANGO_SCRIPT_KHAROSHTHI: 	Kharoshthi. Since 1.10
+ * @PANGO_SCRIPT_UNKNOWN: 		an unassigned code point. Since 1.14
+ * @PANGO_SCRIPT_BALINESE: 		Balinese. Since 1.14
+ * @PANGO_SCRIPT_CUNEIFORM: 	Cuneiform. Since 1.14
+ * @PANGO_SCRIPT_PHOENICIAN: 	Phoenician. Since 1.14
+ * @PANGO_SCRIPT_PHAGS_PA: 		Phags-pa. Since 1.14
+ * @PANGO_SCRIPT_NKO: 		N'Ko. Since 1.14
+ * @PANGO_SCRIPT_KAYAH_LI:   Kayah Li. Since 1.20.1
+ * @PANGO_SCRIPT_LEPCHA:     Lepcha. Since 1.20.1
+ * @PANGO_SCRIPT_REJANG:     Rejang. Since 1.20.1
+ * @PANGO_SCRIPT_SUNDANESE:  Sundanese. Since 1.20.1
+ * @PANGO_SCRIPT_SAURASHTRA: Saurashtra. Since 1.20.1
+ * @PANGO_SCRIPT_CHAM:       Cham. Since 1.20.1
+ * @PANGO_SCRIPT_OL_CHIKI:   Ol Chiki. Since 1.20.1
+ * @PANGO_SCRIPT_VAI:        Vai. Since 1.20.1
+ * @PANGO_SCRIPT_CARIAN:     Carian. Since 1.20.1
+ * @PANGO_SCRIPT_LYCIAN:     Lycian. Since 1.20.1
+ * @PANGO_SCRIPT_LYDIAN:     Lydian. Since 1.20.1
+ * @PANGO_SCRIPT_BATAK:      Batak. Since 1.32
+ * @PANGO_SCRIPT_BRAHMI:     Brahmi. Since 1.32
+ * @PANGO_SCRIPT_MANDAIC:    Mandaic. Since 1.32
+ * @PANGO_SCRIPT_CHAKMA:               Chakma. Since: 1.32
+ * @PANGO_SCRIPT_MEROITIC_CURSIVE:     Meroitic Cursive. Since: 1.32
+ * @PANGO_SCRIPT_MEROITIC_HIEROGLYPHS: Meroitic Hieroglyphs. Since: 1.32
+ * @PANGO_SCRIPT_MIAO:                 Miao. Since: 1.32
+ * @PANGO_SCRIPT_SHARADA:              Sharada. Since: 1.32
+ * @PANGO_SCRIPT_SORA_SOMPENG:         Sora Sompeng. Since: 1.32
+ * @PANGO_SCRIPT_TAKRI:                Takri. Since: 1.32
+ *
+ * The #PangoScript enumeration identifies different writing
+ * systems. The values correspond to the names as defined in the
+ * Unicode standard.
+ * Note that new types may be added in the future. Applications should be ready
+ * to handle unknown values.  This enumeration is interchangeable with
+ * #GUnicodeScript.  See <ulink
+ * url="http://www.unicode.org/reports/tr24/">Unicode Standard Annex
+ * #24: Script names</ulink>.
+ */
 typedef enum {                         /* ISO 15924 code */
       PANGO_SCRIPT_INVALID_CODE = -1,
       PANGO_SCRIPT_COMMON       = 0,   /* Zyyy */
diff --git a/pango/pango-tabs.c b/pango/pango-tabs.c
index 751538cd..1ffa8356 100644
--- a/pango/pango-tabs.c
+++ b/pango/pango-tabs.c
@@ -19,6 +19,14 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:tab-stops
+ * @short_description:Structures for storing tab stops
+ * @title:Tab Stops
+ *
+ * Functions in this section are used to deal with #PangoTabArray objects
+ * that can be used to set tab stop positions in a #PangoLayout.
+ */
 #include "config.h"
 #include "pango-tabs.h"
 #include "pango-impl-utils.h"
@@ -36,6 +44,12 @@ struct _PangoTab
 				 */
 };
 
+/**
+ * PangoTabArray:
+ *
+ * A #PangoTabArray struct contains an array
+ * of tab stops. Each tab stop has an alignment and a position.
+ */
 struct _PangoTabArray
 {
   gint size;
diff --git a/pango/pango-tabs.h b/pango/pango-tabs.h
index 7f52d1d0..8a33bcbb 100644
--- a/pango/pango-tabs.h
+++ b/pango/pango-tabs.h
@@ -28,6 +28,12 @@ G_BEGIN_DECLS
 
 typedef struct _PangoTabArray PangoTabArray;
 
+/**
+ * PangoTabAlign:
+ * @PANGO_TAB_LEFT: the tab stop appears to the left of the text.
+ *
+ * A #PangoTabAlign specifies where a tab stop appears relative to the text.
+ */
 typedef enum
 {
   PANGO_TAB_LEFT
@@ -41,6 +47,11 @@ typedef enum
    */
 } PangoTabAlign;
 
+/**
+ * PANGO_TYPE_TAB_ARRAY:
+ *
+ * The #GObject type for #PangoTabArray.
+ */
 #define PANGO_TYPE_TAB_ARRAY (pango_tab_array_get_type ())
 
 PangoTabArray  *pango_tab_array_new                 (gint           initial_size,
diff --git a/pango/pango-types.h b/pango/pango-types.h
index c4ef8437..0bf4bd7d 100644
--- a/pango/pango-types.h
+++ b/pango/pango-types.h
@@ -40,10 +40,53 @@ typedef struct _PangoRectangle PangoRectangle;
 
 
 /* A index of a glyph into a font. Rendering system dependent */
+/**
+ * PangoGlyph:
+ *
+ * A #PangoGlyph represents a single glyph in the output form of a string.
+ */
 typedef guint32 PangoGlyph;
 
 
 
+/**
+ * PANGO_SCALE:
+ *
+ * The %PANGO_SCALE macro represents the scale between dimensions used
+ * for Pango distances and device units. (The definition of device
+ * units is dependent on the output device; it will typically be pixels
+ * for a screen, and points for a printer.) %PANGO_SCALE is currently
+ * 1024, but this may be changed in the future.
+ *
+ * When setting font sizes, device units are always considered to be
+ * points (as in "12 point font"), rather than pixels.
+ */
+/**
+ * PANGO_PIXELS:
+ * @d: a dimension in Pango units.
+ *
+ * Converts a dimension to device units by rounding.
+ *
+ * Return value: rounded dimension in device units.
+ */
+/**
+ * PANGO_PIXELS_FLOOR:
+ * @d: a dimension in Pango units.
+ *
+ * Converts a dimension to device units by flooring.
+ *
+ * Return value: floored dimension in device units.
+ * Since: 1.14
+ */
+/**
+ * PANGO_PIXELS_CEIL:
+ * @d: a dimension in Pango units.
+ *
+ * Converts a dimension to device units by ceiling.
+ *
+ * Return value: ceiled dimension in device units.
+ * Since: 1.14
+ */
 #define PANGO_SCALE 1024
 #define PANGO_PIXELS(d) (((int)(d) + 512) >> 10)
 #define PANGO_PIXELS_FLOOR(d) (((int)(d)) >> 10)
@@ -57,6 +100,16 @@ typedef guint32 PangoGlyph;
  * PANGO_PIXELS also behaves differently for +512 and -512.
  */
 
+/**
+ * PANGO_UNITS_ROUND:
+ * @d: a dimension in Pango units.
+ *
+ * Rounds a dimension to whole device units, but does not
+ * convert it to device units.
+ *
+ * Return value: rounded dimension in Pango units.
+ * Since: 1.18
+ */
 #define PANGO_UNITS_ROUND(d)				\
   (((d) + (PANGO_SCALE >> 1)) & ~(PANGO_SCALE - 1))
 
@@ -66,8 +119,17 @@ double pango_units_to_double (int i) G_GNUC_CONST;
 
 
 
-/* A rectangle. Used to store logical and physical extents of glyphs,
- * runs, strings, etc.
+/**
+ * PangoRectangle:
+ * @x: X coordinate of the left side of the rectangle.
+ * @y: Y coordinate of the the top side of the rectangle.
+ * @width: width of the rectangle.
+ * @height: height of the rectangle.
+ *
+ * The #PangoRectangle structure represents a rectangle. It is frequently
+ * used to represent the logical or ink extents of a single glyph or section
+ * of text. (See, for instance, pango_font_get_glyph_extents())
+ *
  */
 struct _PangoRectangle
 {
@@ -79,6 +141,44 @@ struct _PangoRectangle
 
 /* Macros to translate from extents rectangles to ascent/descent/lbearing/rbearing
  */
+/**
+ * PANGO_ASCENT:
+ * @rect: a #PangoRectangle
+ *
+ * Extracts the <firstterm>ascent</firstterm> from a #PangoRectangle
+ * representing glyph extents. The ascent is the distance from the
+ * baseline to the highest point of the character. This is positive if the
+ * glyph ascends above the baseline.
+ */
+/**
+ * PANGO_DESCENT:
+ * @rect: a #PangoRectangle
+ *
+ * Extracts the <firstterm>descent</firstterm> from a #PangoRectangle
+ * representing glyph extents. The descent is the distance from the
+ * baseline to the lowest point of the character. This is positive if the
+ * glyph descends below the baseline.
+ */
+/**
+ * PANGO_LBEARING:
+ * @rect: a #PangoRectangle
+ *
+ * Extracts the <firstterm>left bearing</firstterm> from a #PangoRectangle
+ * representing glyph extents. The left bearing is the distance from the
+ * horizontal origin to the farthest left point of the character.
+ * This is positive for characters drawn completely to the right of the
+ * glyph origin.
+ */
+/**
+ * PANGO_RBEARING:
+ * @rect: a #PangoRectangle
+ *
+ * Extracts the <firstterm>right bearing</firstterm> from a #PangoRectangle
+ * representing glyph extents. The right bearing is the distance from the
+ * horizontal origin to the farthest right point of the character.
+ * This is positive except for characters drawn completely to the left of the
+ * horizontal origin.
+ */
 #define PANGO_ASCENT(rect) (-(rect).y)
 #define PANGO_DESCENT(rect) ((rect).y + (rect).height)
 #define PANGO_LBEARING(rect) ((rect).x)
diff --git a/pango/pango-utils.c b/pango/pango-utils.c
index 1ca2de6f..b4ad4511 100644
--- a/pango/pango-utils.c
+++ b/pango/pango-utils.c
@@ -19,6 +19,24 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:pango-version
+ * @short_description:Tools for checking Pango version at compile- and run-time.
+ * @title:Version Checking
+ *
+ * The capital-letter macros defined here can be used to check the version of Pango
+ * at compile-time, and to <firstterm>encode</firstterm> Pango versions into integers.
+ *
+ * The functions can be used to check the version of the linked Pango library at run-time.
+ */
+/**
+ * SECTION:utils
+ * @short_description:Various convenience and utility functions
+ * @title: Miscellaneous Utilities
+ *
+ * The functions and utilities in this section are mostly used from Pango
+ * backends and modules, but may be useful for other purposes too.
+ */
 #include "config.h"
 #include <errno.h>
 #include <string.h>
diff --git a/pango/pango-utils.h b/pango/pango-utils.h
index c55d6dd5..9bac4f0c 100644
--- a/pango/pango-utils.h
+++ b/pango/pango-utils.h
@@ -113,18 +113,62 @@ gboolean pango_is_zero_width (gunichar ch) G_GNUC_CONST;
 /* Pango version checking */
 
 /* Encode a Pango version as an integer */
+/**
+ * PANGO_VERSION_ENCODE:
+ * @major: the major component of the version number
+ * @minor: the minor component of the version number
+ * @micro: the micro component of the version number
+ *
+ * This macro encodes the given Pango version into an integer.  The numbers
+ * returned by %PANGO_VERSION and pango_version() are encoded using this macro.
+ * Two encoded version numbers can be compared as integers.
+ */
 #define PANGO_VERSION_ENCODE(major, minor, micro) (     \
 	  ((major) * 10000)                             \
 	+ ((minor) *   100)                             \
 	+ ((micro) *     1))
 
 /* Encoded version of Pango at compile-time */
+/**
+ * PANGO_VERSION:
+ *
+ * The version of Pango available at compile-time, encoded using PANGO_VERSION_ENCODE().
+ */
+/**
+ * PANGO_VERSION_STRING:
+ *
+ * A string literal containing the version of Pango available at compile-time.
+ */
+/**
+ * PANGO_VERSION_MAJOR:
+ *
+ * The major component of the version of Pango available at compile-time.
+ */
+/**
+ * PANGO_VERSION_MINOR:
+ *
+ * The minor component of the version of Pango available at compile-time.
+ */
+/**
+ * PANGO_VERSION_MICRO:
+ *
+ * The micro component of the version of Pango available at compile-time.
+ */
 #define PANGO_VERSION PANGO_VERSION_ENCODE(     \
 	PANGO_VERSION_MAJOR,                    \
 	PANGO_VERSION_MINOR,                    \
 	PANGO_VERSION_MICRO)
 
 /* Check that compile-time Pango is as new as required */
+/**
+ * PANGO_VERSION_CHECK:
+ * @major: the major component of the version number
+ * @minor: the minor component of the version number
+ * @micro: the micro component of the version number
+ *
+ * Checks that the version of Pango available at compile-time is not older than
+ * the provided version number.
+ */
 #define PANGO_VERSION_CHECK(major,minor,micro)    \
 	(PANGO_VERSION >= PANGO_VERSION_ENCODE(major,minor,micro))
 
diff --git a/pango/pangocairo-context.c b/pango/pangocairo-context.c
index 32b4ef1e..9750fb03 100644
--- a/pango/pangocairo-context.c
+++ b/pango/pangocairo-context.c
@@ -260,7 +260,7 @@ pango_cairo_context_set_font_options (PangoContext               *context,
  * @context: a #PangoContext, from a pangocairo font map
  *
  * Retrieves any font rendering options previously set with
- * pango_cairo_font_map_set_font_options(). This function does not report options
+ * pango_cairo_context_set_font_options(). This function does not report options
  * that are derived from the target surface by pango_cairo_update_context()
  *
  * Return value: the font options previously set on the context, or %NULL
diff --git a/pango/pangocairo-render.c b/pango/pangocairo-render.c
index 48743444..03a2811a 100644
--- a/pango/pangocairo-render.c
+++ b/pango/pangocairo-render.c
@@ -19,6 +19,139 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:pangocairo
+ * @short_description:Rendering with the Cairo backend
+ * @title:Cairo Rendering
+ *
+ * The <ulink url="http://cairographics.org">Cairo library</ulink> is a
+ * vector graphics library with a powerful rendering model. It has such
+ * features as anti-aliased primitives, alpha-compositing, and
+ * gradients. Multiple backends for Cairo are available, to allow
+ * rendering to images, to PDF files, and to the screen on X and on other
+ * windowing systems. The functions in this section allow using Pango
+ * to render to Cairo surfaces.
+ *
+ * Using Pango with Cairo is straightforward. A #PangoContext created
+ * with pango_cairo_font_map_create_context() can be used on any
+ * Cairo context (cairo_t), but needs to be updated to match the
+ * current transformation matrix and target surface of the Cairo context
+ * using pango_cairo_update_context(). The convenience functions
+ * pango_cairo_create_layout() and pango_cairo_update_layout() handle
+ * the common case where the program doesn't need to manipulate the
+ * properties of the #PangoContext.
+ *
+ * When you get the metrics of a layout or of a piece of a layout using
+ * functions such as pango_layout_get_extents(), the reported metrics
+ * are in user-space coordinates. If a piece of text is 10 units long,
+ * and you call cairo_scale (cr, 2.0), it still is more-or-less 10
+ * units long. However, the results will be affected by hinting
+ * (that is, the process of adjusting the text to look good on the
+ * pixel grid), so you shouldn't assume they are completely independent
+ * of the current transformation matrix. Note that the basic metrics
+ * functions in Pango report results in integer Pango units. To get
+ * to the floating point units used in Cairo divide by %PANGO_SCALE.
+ *
+ * <example id="rotated-example">
+ * <title>Using Pango with Cairo</title>
+ *  <programlisting>
+ * #include <math.h>
+ * #include <pango/pangocairo.h>
+ *
+ * static void
+ * draw_text (cairo_t *cr)
+ * {
+ * #define RADIUS 150
+ * #define N_WORDS 10
+ * #define FONT "Sans Bold 27"
+ *
+ *   PangoLayout *layout;
+ *   PangoFontDescription *desc;
+ *   int i;
+ *
+ *   /&ast; Center coordinates on the middle of the region we are drawing
+ *    &ast;/
+ *   cairo_translate (cr, RADIUS, RADIUS);
+ *
+ *   /&ast; Create a PangoLayout, set the font and text &ast;/
+ *   layout = pango_cairo_create_layout (cr);
+ *
+ *   pango_layout_set_text (layout, "Text", -1);
+ *   desc = pango_font_description_from_string (FONT);
+ *   pango_layout_set_font_description (layout, desc);
+ *   pango_font_description_free (desc);
+ *
+ *   /&ast; Draw the layout N_WORDS times in a circle &ast;/
+ *   for (i = 0; i &lt; N_WORDS; i++)
+ *     {
+ *       int width, height;
+ *       double angle = (360. * i) / N_WORDS;
+ *       double red;
+ *
+ *       cairo_save (cr);
+ *
+ *       /&ast; Gradient from red at angle == 60 to blue at angle == 240 &ast;/
+ *       red   = (1 + cos ((angle - 60) * G_PI / 180.)) / 2;
+ *       cairo_set_source_rgb (cr, red, 0, 1.0 - red);
+ *
+ *       cairo_rotate (cr, angle * G_PI / 180.);
+ *
+ *       /&ast; Inform Pango to re-layout the text with the new transformation &ast;/
+ *       pango_cairo_update_layout (cr, layout);
+ *
+ *       pango_layout_get_size (layout, &amp;width, &amp;height);
+ *       cairo_move_to (cr, - ((double)width / PANGO_SCALE) / 2, - RADIUS);
+ *       pango_cairo_show_layout (cr, layout);
+ *
+ *       cairo_restore (cr);
+ *     }
+ *
+ *   /&ast; free the layout object &ast;/
+ *   g_object_unref (layout);
+ * }
+ *
+ * int main (int argc, char **argv)
+ * {
+ *   cairo_t *cr;
+ *   char *filename;
+ *   cairo_status_t status;
+ *   cairo_surface_t *surface;
+ *
+ *   if (argc != 2)
+ *     {
+ *       g_printerr ("Usage: cairosimple OUTPUT_FILENAME\n");
+ *       return 1;
+ *     }
+ *
+ *      filename = argv[1];
+ *
+ *   surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
+ *                                         2 * RADIUS, 2 * RADIUS);
+ *   cr = cairo_create (surface);
+ *
+ *   cairo_set_source_rgb (cr, 1.0, 1.0, 1.0);
+ *   cairo_paint (cr);
+ *   draw_text (cr);
+ *   cairo_destroy (cr);
+ *
+ *   status = cairo_surface_write_to_png (surface, filename);
+ *   cairo_surface_destroy (surface);
+ *
+ *   if (status != CAIRO_STATUS_SUCCESS)
+ *     {
+ *       g_printerr ("Could not save png to '%s'\n", filename);
+ *       return 1;
+ *     }
+ *
+ *   return 0;
+ * }
+ * </programlisting>
+ * </example>
+ * <figure id="rotated-example-output">
+ *   <title>Output of <xref linkend="rotated-example"/></title>
+ *   <graphic fileref="rotated-text.png" format="PNG"/>
+ * </figure>
+ */
 #include "config.h"
 
 #include <math.h>
diff --git a/pango/pangocairo.h b/pango/pangocairo.h
index 81e842de..73ad7aca 100644
--- a/pango/pangocairo.h
+++ b/pango/pangocairo.h
@@ -55,6 +55,20 @@ typedef struct _PangoCairoFontMap        PangoCairoFontMap;
 #define PANGO_CAIRO_FONT_MAP(object)    (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_CAIRO_FONT_MAP, PangoCairoFontMap))
 #define PANGO_IS_CAIRO_FONT_MAP(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_CAIRO_FONT_MAP))
 
+/**
+ * PangoCairoShapeRendererFunc:
+ * @cr: a Cairo context with current point set to where the shape should
+ * be rendered
+ * @attr: the %PANGO_ATTR_SHAPE to render
+ * @do_path: whether only the shape path should be appended to current
+ * path of @cr and no filling/stroking done.  This will be set
+ * to %TRUE when called from pango_cairo_layout_path() and
+ * pango_cairo_layout_line_path() rendering functions.
+ * @data: user data passed to pango_cairo_context_set_shape_renderer()
+ *
+ * Function type for rendering attributes of type %PANGO_ATTR_SHAPE
+ * with Pango's Cairo renderer.
+ */
 typedef void (* PangoCairoShapeRendererFunc) (cairo_t        *cr,
 					      PangoAttrShape *attr,
 					      gboolean        do_path,
diff --git a/pango/pangocoretext.c b/pango/pangocoretext.c
index 36bcd825..d75b2e8d 100644
--- a/pango/pangocoretext.c
+++ b/pango/pangocoretext.c
@@ -20,6 +20,14 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:coretext-fonts
+ * @short_description:Font handling with CoreText fonts
+ * @title:CoreText Fonts
+ *
+ * The macros and functions in this section are used to access fonts natively on
+ * OS X using the CoreText text rendering subsystem.
+ */
 #include "config.h"
 
 #include "pangocoretext.h"
diff --git a/pango/pangocoretext.h b/pango/pangocoretext.h
index 22dd9cb0..9449189a 100644
--- a/pango/pangocoretext.h
+++ b/pango/pangocoretext.h
@@ -38,6 +38,12 @@ typedef struct _PangoCoreTextFontClass    PangoCoreTextFontClass;
 
 #if defined(PANGO_ENABLE_ENGINE) || defined(PANGO_ENABLE_BACKEND)
 
+/**
+ * PANGO_RENDER_TYPE_CORE_TEXT:
+ *
+ * A string constant identifying the CoreText renderer. The associated quark (see
+ * g_quark_from_string()) is used to identify the renderer in pango_find_map().
+ */
 #define PANGO_RENDER_TYPE_CORE_TEXT "PangoRenderCoreText"
 
 #ifdef PANGO_ENABLE_BACKEND
diff --git a/pango/pangofc-decoder.c b/pango/pangofc-decoder.c
index 09a4eed0..f11b4e07 100644
--- a/pango/pangofc-decoder.c
+++ b/pango/pangofc-decoder.c
@@ -19,6 +19,14 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:pangofc-decoder
+ * @short_description:Custom font encoding handling
+ * @title:PangoFcDecoder
+ *
+ * PangoFcDecoder represents a decoder that an application provides
+ * for handling a font that is encoded in a custom way.
+ */
 #include "config.h"
 #include "pangofc-decoder.h"
 
diff --git a/pango/pangofc-font.c b/pango/pangofc-font.c
index 58307906..7056bca9 100644
--- a/pango/pangofc-font.c
+++ b/pango/pangofc-font.c
@@ -19,6 +19,24 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:pangofc-font
+ * @short_description:Base font class for Fontconfig-based backends
+ * @title:PangoFcFont
+ * @see_also:
+ * <variablelist><varlistentry><term>#PangoFcFontMap</term> <listitem>The base class for font maps; creating a new
+ * Fontconfig-based backend involves deriving from both
+ * #PangoFcFontMap and #PangoFcFont.</listitem></varlistentry></variablelist>
+ *
+ * #PangoFcFont is a base class for font implementation using the
+ * Fontconfig and FreeType libraries. It is used in the
+ * <link linkend="pango-Xft-Fonts-and-Rendering">Xft</link> and
+ * <link linkend="pango-FreeType-Fonts-and-Rendering">FreeType</link>
+ * backends shipped with Pango, but can also be used when creating
+ * new backends. Any backend deriving from this base class will
+ * take advantage of the wide range of shapers implemented using
+ * FreeType that come with Pango.
+ */
 #include "config.h"
 
 #include "pangofc-font.h"
diff --git a/pango/pangofc-fontmap.c b/pango/pangofc-fontmap.c
index 05fed2d5..a4053f71 100644
--- a/pango/pangofc-fontmap.c
+++ b/pango/pangofc-fontmap.c
@@ -19,6 +19,27 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:pangofc-fontmap
+ * @short_description:Base fontmap class for Fontconfig-based backends
+ * @title:PangoFcFontMap
+ * @see_also:
+ * <variablelist><varlistentry>
+ * <term>#PangoFcFont</term>
+ * <listitem>The base class for fonts; creating a new
+ * Fontconfig-based backend involves deriving from both
+ * #PangoFcFontMap and #PangoFcFont.</listitem>
+ * </varlistentry></variablelist>
+ *
+ * PangoFcFontMap is a base class for font map implementations using the
+ * Fontconfig and FreeType libraries. It is used in the
+ * <link linkend="pango-Xft-Fonts-and-Rendering">Xft</link> and
+ * <link linkend="pango-FreeType-Fonts-and-Rendering">FreeType</link>
+ * backends shipped with Pango, but can also be used when creating
+ * new backends. Any backend deriving from this base class will
+ * take advantage of the wide range of shapers implemented using
+ * FreeType that come with Pango.
+ */
 #define FONTSET_CACHE_SIZE 256
 
 #include "config.h"
diff --git a/pango/pangofc-fontmap.h b/pango/pangofc-fontmap.h
index 8421f180..3948b1f1 100644
--- a/pango/pangofc-fontmap.h
+++ b/pango/pangofc-fontmap.h
@@ -117,7 +117,7 @@ struct _PangoFcFontMap
  *  may be null.
  * @context_key_get: Gets an opaque key holding backend
  *  specific options for the context that will affect
- *  fonts created by create_font(). The result must point to
+ *  fonts created by @create_font(). The result must point to
  *  persistant storage owned by the fontmap. This key
  *  is used to index hash tables used to look up fontsets
  *  and fonts.
@@ -225,7 +225,7 @@ PangoFontDescription *pango_fc_font_description_from_pattern (FcPattern *pattern
  *
  * String representing a fontconfig property name that Pango sets on any
  * fontconfig pattern it passes to fontconfig if a #PangoGravity other
- * than %PangoGravitySouth is desired.
+ * than %PANGO_GRAVITY_SOUTH is desired.
  *
  * The property will have a #PangoGravity value as a string, like "east".
  * This can be used to write fontconfig configuration rules to choose
diff --git a/pango/pangoft2-fontmap.c b/pango/pangoft2-fontmap.c
index 3b43fbd6..1904f015 100644
--- a/pango/pangoft2-fontmap.c
+++ b/pango/pangoft2-fontmap.c
@@ -37,6 +37,11 @@
 typedef struct _PangoFT2Family       PangoFT2Family;
 typedef struct _PangoFT2FontMapClass PangoFT2FontMapClass;
 
+/**
+ * PangoFT2FontMap:
+ *
+ * The #PangoFT2FontMap is the #PangoFontMap implementation for FreeType fonts.
+ */
 struct _PangoFT2FontMap
 {
   PangoFcFontMap parent_instance;
@@ -203,7 +208,7 @@ pango_ft2_font_map_set_default_substitute (PangoFT2FontMap        *fontmap,
 
 /**
  * pango_ft2_font_map_substitute_changed:
- * @fontmap: a #PangoFT2Fontmap
+ * @fontmap: a #PangoFT2FontMap
  *
  * Call this function any time the results of the
  * default substitution function set with
@@ -224,7 +229,7 @@ pango_ft2_font_map_substitute_changed (PangoFT2FontMap *fontmap)
 
 /**
  * pango_ft2_font_map_set_resolution:
- * @fontmap: a #PangoFT2Fontmap
+ * @fontmap: a #PangoFT2FontMap
  * @dpi_x: dots per inch in the X direction
  * @dpi_y: dots per inch in the Y direction
  *
@@ -246,8 +251,8 @@ pango_ft2_font_map_set_resolution (PangoFT2FontMap *fontmap,
 }
 
 /**
- * pango_ft2_font_map_create_context:
- * @fontmap: a #PangoFT2Fontmap
+ * pango_ft2_font_map_create_context: (skip)
+ * @fontmap: a #PangoFT2FontMap
  *
  * Create a #PangoContext for the given fontmap.
  *
@@ -266,12 +271,12 @@ pango_ft2_font_map_create_context (PangoFT2FontMap *fontmap)
 }
 
 /**
- * pango_ft2_get_context:
+ * pango_ft2_get_context: (skip)
  * @dpi_x:  the horizontal DPI of the target device
  * @dpi_y:  the vertical DPI of the target device
  *
  * Retrieves a #PangoContext for the default PangoFT2 fontmap
- * (see pango_ft2_fontmap_get_for_display()) and sets the resolution
+ * (see pango_ft2_font_map_for_display()) and sets the resolution
  * for the default fontmap to @dpi_x by @dpi_y.
  *
  * Return value: the new #PangoContext
@@ -292,7 +297,7 @@ pango_ft2_get_context (double dpi_x, double dpi_y)
 G_GNUC_END_IGNORE_DEPRECATIONS
 
 /**
- * pango_ft2_font_map_for_display:
+ * pango_ft2_font_map_for_display: (skip)
  *
  * Returns a #PangoFT2FontMap. This font map is cached and should
  * not be freed. If the font map is no longer needed, it can
@@ -341,7 +346,7 @@ _pango_ft2_font_map_get_library (PangoFontMap *fontmap)
 
 /**
  * _pango_ft2_font_map_get_renderer:
- * @fontmap: a #PangoFT2Fontmap
+ * @fontmap: a #PangoFT2FontMap
  *
  * Gets the singleton PangoFT2Renderer for this fontmap.
  *
diff --git a/pango/pangoft2-render.c b/pango/pangoft2-render.c
index 42923f49..2b0ebd53 100644
--- a/pango/pangoft2-render.c
+++ b/pango/pangoft2-render.c
@@ -20,6 +20,17 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:pango-renderer
+ * @short_description:Rendering driver base class
+ * @title:PangoRenderer
+ *
+ * #PangoRenderer is a base class that contains the necessary logic for
+ * rendering a #PangoLayout or #PangoLayoutLine. By subclassing
+ * #PangoRenderer and overriding operations such as @draw_glyphs and
+ * @draw_rectangle, renderers for particular font backends and
+ * destinations can be created.
+ */
 #include "config.h"
 #include <math.h>
 
diff --git a/pango/pangoft2.c b/pango/pangoft2.c
index dc6db5da..3ada81c9 100644
--- a/pango/pangoft2.c
+++ b/pango/pangoft2.c
@@ -20,6 +20,14 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:freetype-fonts
+ * @short_description:Functions for shape engines to manipulate FreeType fonts
+ * @title:FreeType Fonts and Rendering
+ *
+ * The macros and functions in this section are used to access fonts and render
+ * text to bitmaps using the FreeType 2 library.
+ */
 #include "config.h"
 
 #include <string.h>
@@ -467,12 +475,13 @@ pango_ft2_font_finalize (GObject *object)
 
 /**
  * pango_ft2_font_get_coverage:
- * @font: a #PangoFT2Font.
+ * @font: a <type>PangoFT2Font</type>.
  * @language: a language tag.
- * @returns: a #PangoCoverage.
  *
- * Gets the #PangoCoverage for a #PangoFT2Font. Use
+ * Gets the #PangoCoverage for a <type>PangoFT2Font</type>. Use
  * pango_font_get_coverage() instead.
+ *
+ * Return value: a #PangoCoverage.
  **/
 PangoCoverage *
 pango_ft2_font_get_coverage (PangoFont     *font,
diff --git a/pango/pangoft2.h b/pango/pangoft2.h
index d2ba13dd..2b9083c7 100644
--- a/pango/pangoft2.h
+++ b/pango/pangoft2.h
@@ -31,6 +31,12 @@
 G_BEGIN_DECLS
 
 #ifndef PANGO_DISABLE_DEPRECATED
+/**
+ * PANGO_RENDER_TYPE_FT2:
+ *
+ * A string constant that was used to identify shape engines that work
+ * with the FreeType backend. See %PANGO_RENDER_TYPE_FC for the replacement.
+ */
 #define PANGO_RENDER_TYPE_FT2 "PangoRenderFT2"
 #endif
 
@@ -40,6 +46,13 @@ G_BEGIN_DECLS
 
 typedef struct _PangoFT2FontMap      PangoFT2FontMap;
 
+/**
+ * PangoFT2SubstituteFunc:
+ * @pattern: the <type>FcPattern</type> to tweak.
+ * @data: user data.
+ *
+ * Function type for doing final config tweaking on prepared FcPatterns.
+ */
 typedef void (*PangoFT2SubstituteFunc) (FcPattern *pattern,
 					gpointer   data);
 
diff --git a/pango/pangowin32-fontcache.c b/pango/pangowin32-fontcache.c
index cc389eef..a7cfec69 100644
--- a/pango/pangowin32-fontcache.c
+++ b/pango/pangowin32-fontcache.c
@@ -35,6 +35,11 @@
 
 typedef struct _CacheEntry CacheEntry;
 
+/**
+ * PangoWin32FontCache:
+ *
+ * A #PangoWin32FontCache caches HFONTs by their LOGFONT descriptions.
+ */
 struct _PangoWin32FontCache
 {
   GHashTable *forward;
diff --git a/pango/pangowin32-fontmap.c b/pango/pangowin32-fontmap.c
index 68ec2ee0..30700683 100644
--- a/pango/pangowin32-fontmap.c
+++ b/pango/pangowin32-fontmap.c
@@ -736,7 +736,7 @@ _pango_win32_font_map_class_init (PangoWin32FontMapClass *class)
 /**
  * pango_win32_font_map_for_display:
  *
- * Returns a #PangoWin32FontMap. Font maps are cached and should
+ * Returns a <type>PangoWin32FontMap</type>. Font maps are cached and should
  * not be freed. If the font map is no longer needed, it can
  * be released with pango_win32_shutdown_display().
  *
@@ -1658,7 +1658,7 @@ pango_win32_face_list_sizes (PangoFontFace  *face,
 
 /**
  * pango_win32_font_map_get_font_cache:
- * @font_map: a #PangoWin32FontMap.
+ * @font_map: a <type>PangoWin32FontMap</type>.
  *
  * Obtains the font cache associated with the given font map.
  *
diff --git a/pango/pangowin32.c b/pango/pangowin32.c
index bb5b9751..6948037f 100644
--- a/pango/pangowin32.c
+++ b/pango/pangowin32.c
@@ -22,6 +22,14 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:win32-fonts
+ * @short_description:Functions for shape engines to manipulate Win32 fonts
+ * @title:Win32 Fonts and Rendering
+ *
+ * The macros and functions in this section are used to access fonts natively on
+ * Win32 systems and to render text in conjunction with Win32 APIs.
+ */
 #include "config.h"
 
 #include <string.h>
diff --git a/pango/pangowin32.h b/pango/pangowin32.h
index a27c4730..ecfe5f8e 100644
--- a/pango/pangowin32.h
+++ b/pango/pangowin32.h
@@ -37,6 +37,12 @@ G_BEGIN_DECLS
 #include <windows.h>
 #undef STRICT
 
+/**
+ * PANGO_RENDER_TYPE_WIN32:
+ *
+ * A string constant identifying the Win32 renderer. The associated quark (see
+ * g_quark_from_string()) is used to identify the renderer in pango_find_map().
+ */
 #define PANGO_RENDER_TYPE_WIN32 "PangoRenderWin32"
 
 /* Calls for applications
diff --git a/pango/pangoxft-font.c b/pango/pangoxft-font.c
index 2b1b6740..4e5dcb7b 100644
--- a/pango/pangoxft-font.c
+++ b/pango/pangoxft-font.c
@@ -19,6 +19,36 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:xft-fonts
+ * @short_description:Font handling and rendering with the Xft backend
+ * @title:Xft Fonts and Rendering
+ *
+ * The Xft library is a library for displaying fonts on the X window
+ * system; internally it uses the fontconfig library to locate font
+ * files, and the FreeType library to load and render fonts. The
+ * Xft backend is the recommended Pango font backend for screen
+ * display with X. (The <link linkend="pango-Cairo-Rendering">Cairo back end</link> is another possibility.)
+ *
+ * Using the Xft backend is generally straightforward;
+ * pango_xft_get_context() creates a context for a specified display
+ * and screen. You can then create a #PangoLayout with that context
+ * and render it with pango_xft_render_layout(). At a more advanced
+ * level, the low-level fontconfig options used for rendering fonts
+ * can be affected using pango_xft_set_default_substitute(), and
+ * pango_xft_substitute_changed().
+ *
+ * A range of functions for drawing pieces of a layout, such as
+ * individual layout lines and glyphs strings are provided.  You can also
+ * directly create a #PangoXftRenderer. Finally, in some advanced cases, it
+ * is useful to derive from #PangoXftRenderer. Deriving from
+ * #PangoXftRenderer is useful for two reasons. One reason is be to
+ * support custom attributes by overriding #PangoRendererClass virtual
+ * functions like 'prepare_run' or 'draw_shape'. The reason is to
+ * customize exactly how the final bits are drawn to the destination by
+ * overriding the #PangoXftRendererClass virtual functions
+ * 'composite_glyphs' and 'composite_trapezoids'.
+ */
 #include "config.h"
 
 #include <stdlib.h>
diff --git a/pango/pangoxft-fontmap.c b/pango/pangoxft-fontmap.c
index 4976890c..fd96816d 100644
--- a/pango/pangoxft-fontmap.c
+++ b/pango/pangoxft-fontmap.c
@@ -213,7 +213,7 @@ register_display (Display *display)
  * @display: an X display
  * @screen: the screen number of a screen within @display
  *
- * Returns the #PangoXftFontmap for the given display and screen.
+ * Returns the #PangoXftFontMap for the given display and screen.
  * The fontmap is owned by Pango and will be valid until
  * the display is closed.
  *
@@ -389,7 +389,7 @@ pango_xft_get_context (Display *display,
 
 /**
  * _pango_xft_font_map_get_renderer:
- * @fontmap: a #PangoXftFontmap
+ * @fontmap: a #PangoXftFontMap
  *
  * Gets the singleton #PangoXFTRenderer for this fontmap.
  *
diff --git a/pango/pangoxft.h b/pango/pangoxft.h
index c5c7501c..da0c3315 100644
--- a/pango/pangoxft.h
+++ b/pango/pangoxft.h
@@ -31,18 +31,44 @@
 
 G_BEGIN_DECLS
 
+/**
+ * PANGO_RENDER_TYPE_XFT:
+ *
+ * A string constant that was used to identify shape engines that work
+ * with the Xft backend. See %PANGO_RENDER_TYPE_FC for the replacement.
+ */
 #ifndef PANGO_DISABLE_DEPRECATED
 #define PANGO_RENDER_TYPE_XFT "PangoRenderXft"
 #endif
 
+/**
+ * PangoXftFontMap:
+ *
+ * #PangoXftFontMap is an implementation of #PangoFcFontMap suitable for
+ * the Xft library as the renderer.  It is used in to create fonts of
+ * type #PangoXftFont.
+ */
 #define PANGO_TYPE_XFT_FONT_MAP              (pango_xft_font_map_get_type ())
 #define PANGO_XFT_FONT_MAP(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_XFT_FONT_MAP, PangoXftFontMap))
 #define PANGO_XFT_IS_FONT_MAP(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_XFT_FONT_MAP))
 
 typedef struct _PangoXftFontMap      PangoXftFontMap;
 
+/**
+ * PangoXftFont:
+ *
+ * #PangoXftFont is an implementation of #PangoFcFont using the Xft
+ * library for rendering.  It is used in conjunction with #PangoXftFontMap.
+ */
 typedef struct _PangoXftFont    PangoXftFont;
 
+/**
+ * PangoXftSubstituteFunc:
+ * @pattern: the FcPattern to tweak.
+ * @data: user data.
+ *
+ * Function type for doing final config tweaking on prepared FcPatterns.
+ */
 typedef void (*PangoXftSubstituteFunc) (FcPattern *pattern,
 					gpointer   data);
 
diff --git a/pango/shape.c b/pango/shape.c
index 63c36ab7..7c805dec 100644
--- a/pango/shape.c
+++ b/pango/shape.c
@@ -19,6 +19,16 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:glyphs
+ * @short_description:Structures for storing information about glyphs
+ * @title:Glyph Storage
+ *
+ * pango_shape() produces a string of glyphs which
+ * can be measured or drawn to the screen. The following
+ * structures are used to store information about
+ * glyphs.
+ */
 #include "config.h"
 
 #include "pango-impl-utils.h"