More documentation improvements.

2005-11-17  Behdad Esfahbod  <behdad@gnome.org>

        * docs/tmpl/coverage-maps.sgml docs/tmpl/fonts.sgml
        docs/tmpl/glyphs.sgml docs/tmpl/layout.sgml
        docs/tmpl/main.sgml docs/tmpl/scripts.sgml
        docs/tmpl/tab-stops.sgml docs/tmpl/text-attributes.sgml
        pango/break.c pango/fonts.c pango/pango-fontset.c
        pango/pango-layout.c pango/pango-script.c pango/pango-utils.c
        pango/pangofc-decoder.c pango/pangofc-decoder.h
        pango/pangofc-font.c pango/pangofc-font.h
        pango/pangoxft-font.c: More documentation improvements.

20 files changed, 175 insertions, 153 deletions

diff --git a/ChangeLog b/ChangeLog
index 285eb54d..c06210ad 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,17 @@
 2005-11-17  Behdad Esfahbod  <behdad@gnome.org>
 
+	* docs/tmpl/coverage-maps.sgml docs/tmpl/fonts.sgml
+	docs/tmpl/glyphs.sgml docs/tmpl/layout.sgml
+	docs/tmpl/main.sgml docs/tmpl/scripts.sgml
+	docs/tmpl/tab-stops.sgml docs/tmpl/text-attributes.sgml
+	pango/break.c pango/fonts.c pango/pango-fontset.c
+	pango/pango-layout.c pango/pango-script.c pango/pango-utils.c
+	pango/pangofc-decoder.c pango/pangofc-decoder.h
+	pango/pangofc-font.c pango/pangofc-font.h
+	pango/pangoxft-font.c: More documentation improvements.
+
+2005-11-17  Behdad Esfahbod  <behdad@gnome.org>
+
 	Part of #101079:
 
 	* pango/opentype/ftxopen.c (Load_Lookup): In extension subtables,
diff --git a/docs/tmpl/coverage-maps.sgml b/docs/tmpl/coverage-maps.sgml
index d673d65e..f88fa32f 100644
--- a/docs/tmpl/coverage-maps.sgml
+++ b/docs/tmpl/coverage-maps.sgml
@@ -36,7 +36,7 @@ character point for a particular script.
 
 <!-- ##### MACRO PANGO_TYPE_COVERAGE_LEVEL ##### -->
 <para>
-The GObject type for #PangoCoverageLevel.
+The #GObject type for #PangoCoverageLevel.
 </para>
 
 
diff --git a/docs/tmpl/fonts.sgml b/docs/tmpl/fonts.sgml
index 34232cfa..0d777992 100644
--- a/docs/tmpl/fonts.sgml
+++ b/docs/tmpl/fonts.sgml
@@ -30,7 +30,7 @@ the characteristics of a font to load.
 
 <!-- ##### MACRO PANGO_TYPE_FONT_DESCRIPTION ##### -->
 <para>
-The GObject type for #PangoFontDescription.
+The #GObject type for #PangoFontDescription.
 </para>
 
 
@@ -45,7 +45,7 @@ The GObject type for #PangoFontDescription.
 
 <!-- ##### MACRO PANGO_TYPE_STYLE ##### -->
 <para>
-The GObject type for #PangoStyle.
+The #GObject type for #PangoStyle.
 </para>
 
 
@@ -66,7 +66,7 @@ value ranging from 100 to 900, but there are some predefined values:
 
 <!-- ##### MACRO PANGO_TYPE_WEIGHT ##### -->
 <para>
-The GObject type for #PangoWeight.
+The #GObject type for #PangoWeight.
 </para>
 
 
@@ -82,7 +82,7 @@ An enumeration specifying capitalization variant of the font.
 
 <!-- ##### MACRO PANGO_TYPE_VARIANT ##### -->
 <para>
-The GObject type for #PangoVariant.
+The #GObject type for #PangoVariant.
 </para>
 
 
@@ -105,7 +105,7 @@ within a family.
 
 <!-- ##### MACRO PANGO_TYPE_STRETCH ##### -->
 <para>
-The GObject type for #PangoStretch.
+The #GObject type for #PangoStretch.
 </para>
 
 
@@ -125,7 +125,7 @@ The bits in a #PangoFontMask correspond to fields in a
 
 <!-- ##### MACRO PANGO_TYPE_FONT_MASK ##### -->
 <para>
-The GObject type for #PangoFontMask.
+The #GObject type for #PangoFontMask.
 </para>
 
 
@@ -424,7 +424,7 @@ of their meaning.
 
 <!-- ##### MACRO PANGO_TYPE_FONT_METRICS ##### -->
 <para>
-The GObject type for #PangoFontMetrics.
+The #GObject type for #PangoFontMetrics.
 </para>
 
 
@@ -538,7 +538,7 @@ which the implementation fills in.
 
 <!-- ##### MACRO PANGO_TYPE_FONT ##### -->
 <para>
-The GObject type for #PangoFont.
+The #GObject type for #PangoFont.
 </para>
 
 
@@ -629,7 +629,7 @@ slant, weight, width and other aspects.
 
 <!-- ##### MACRO PANGO_TYPE_FONT_FAMILY ##### -->
 <para>
-The GObject type for #PangoFontFamily.
+The #GObject type for #PangoFontFamily.
 </para>
 
 
@@ -687,7 +687,7 @@ the same family, slant, weight, width, but varying sizes.
 
 <!-- ##### MACRO PANGO_TYPE_FONT_FACE ##### -->
 <para>
-The GObject type for #PangoFontFace.
+The #GObject type for #PangoFontFace.
 </para>
 
 
@@ -755,7 +755,7 @@ fills in.
 
 <!-- ##### MACRO PANGO_TYPE_FONT_MAP ##### -->
 <para>
-The GObject type for #PangoFontMap.
+The #GObject type for #PangoFontMap.
 </para>
 
 
@@ -869,7 +869,7 @@ set of metrics for the entire fontset.
 
 <!-- ##### MACRO PANGO_TYPE_FONTSET ##### -->
 <para>
-The GObject type for #PangoFontset.
+The #GObject type for #PangoFontset.
 </para>
 
 
@@ -882,7 +882,7 @@ a particular #PangoFontset implementation.
 
 @parent_class: 
 @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().
+   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.
@@ -939,7 +939,7 @@ which the creator provides when constructing the
 
 <!-- ##### MACRO PANGO_TYPE_FONTSET_SIMPLE ##### -->
 <para>
-The GObject type for #PangoFontsetSimple.
+The #GObject type for #PangoFontsetSimple.
 </para>
 
 
diff --git a/docs/tmpl/glyphs.sgml b/docs/tmpl/glyphs.sgml
index a25e5895..c8fc63c3 100644
--- a/docs/tmpl/glyphs.sgml
+++ b/docs/tmpl/glyphs.sgml
@@ -275,7 +275,7 @@ each of which contains a list of #PangoGlyphItem.
 
 <!-- ##### MACRO PANGO_TYPE_GLYPH_STRING ##### -->
 <para>
-The GObject type for #PangoGlyphString.
+The #GObject type for #PangoGlyphString.
 </para>
 
 
diff --git a/docs/tmpl/layout.sgml b/docs/tmpl/layout.sgml
index d358115a..5f798c0c 100644
--- a/docs/tmpl/layout.sgml
+++ b/docs/tmpl/layout.sgml
@@ -219,7 +219,7 @@ enough space for a full word.
 
 <!-- ##### MACRO PANGO_TYPE_WRAP_MODE ##### -->
 <para>
-The GObject type for #PangoWrapMode.
+The #GObject type for #PangoWrapMode.
 </para>
 
 
@@ -254,7 +254,7 @@ The GObject type for #PangoWrapMode.
 
 <!-- ##### MACRO PANGO_TYPE_ELLIPSIZE_MODE ##### -->
 <para>
-The GObject type for #PangoEllipsizeMode.
+The #GObject type for #PangoEllipsizeMode.
 </para>
 
 
@@ -389,8 +389,7 @@ The GObject type for #PangoEllipsizeMode.
 <para>
 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(), then this only has an effect
-for partial lines.
+using pango_layout_set_justify(), this only has effect for partial lines.
 </para>
 
 @PANGO_ALIGN_LEFT: Put all available space on the right
@@ -399,7 +398,7 @@ for partial lines.
 
 <!-- ##### MACRO PANGO_TYPE_ALIGNMENT ##### -->
 <para>
-The GObject type for #PangoAlignment.
+The #GObject type for #PangoAlignment.
 </para>
 
 
@@ -700,12 +699,12 @@ Routines for rendering PangoLayout objects are provided in
 code specific to each rendering system.
 </para>
 
-@layout: the parent layout for this line.
-@start_index: the start of the line as byte index into @layout->text.
-@length: the length of the line in bytes.
-@runs: a list containing the runs of the line in visual order.
-@is_paragraph_start: %TRUE if this is the first line of the paragraph.
-@resolved_dir: 
+@layout: the parent layout for this line
+@start_index: the start of the line as byte index into @layout->text
+@length: the length of the line in bytes
+@runs: a list containing the runs of the line in visual order
+@is_paragraph_start: %TRUE if this is the first line of the paragraph
+@resolved_dir: the resolved #PangoDirection of the line
 
 <!-- ##### TYPEDEF PangoLayoutRun ##### -->
 <para>
diff --git a/docs/tmpl/main.sgml b/docs/tmpl/main.sgml
index 713fa998..89d5cb1e 100644
--- a/docs/tmpl/main.sgml
+++ b/docs/tmpl/main.sgml
@@ -64,7 +64,7 @@ fields:
 
 <!-- ##### MACRO PANGO_TYPE_DIRECTION ##### -->
 <para>
-The GObject type for #PangoDirection.
+The #GObject type for #PangoDirection.
 </para>
 
 
@@ -300,7 +300,7 @@ Determines the direction of a character; either
 %PANGO_DIRECTION_NEUTRAL.
 </para>
 
-@ch: character to examine
+@ch: a Unicode character
 @Returns:  the direction of a character, as used in the
   Unicode bidirectional algorithm.
 
diff --git a/docs/tmpl/scripts.sgml b/docs/tmpl/scripts.sgml
index f68c9341..f454678e 100644
--- a/docs/tmpl/scripts.sgml
+++ b/docs/tmpl/scripts.sgml
@@ -31,7 +31,7 @@ url="http://www.unicode.org/reports/tr24/">Unicode Standard Annex
 #24: Script names</ulink>).
 </para>
 
-@PANGO_SCRIPT_INVALID_CODE: a value never used for any unicode character
+@PANGO_SCRIPT_INVALID_CODE: a value never used for any Unicode character
 @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.
@@ -97,7 +97,7 @@ url="http://www.unicode.org/reports/tr24/">Unicode Standard Annex
 
 <!-- ##### MACRO PANGO_TYPE_SCRIPT ##### -->
 <para>
-The GObject type for #PangoScript
+The #GObject type for #PangoScript
 </para>
 
 
diff --git a/docs/tmpl/tab-stops.sgml b/docs/tmpl/tab-stops.sgml
index b06289b8..757280ad 100644
--- a/docs/tmpl/tab-stops.sgml
+++ b/docs/tmpl/tab-stops.sgml
@@ -23,7 +23,7 @@ of tab stops. Each tab stop has an alignment and a position.
 
 <!-- ##### MACRO PANGO_TYPE_TAB_ARRAY ##### -->
 <para>
-The GObject type for #PangoTabArray.
+The #GObject type for #PangoTabArray.
 </para>
 
 
@@ -37,7 +37,7 @@ A #PangoTabAlign specifies where a tab stop appears relative to the text.
 
 <!-- ##### MACRO PANGO_TYPE_TAB_ALIGN ##### -->
 <para>
-The GObject type for #PangoTabAlign.
+The #GObject type for #PangoTabAlign.
 </para>
 
 
diff --git a/docs/tmpl/text-attributes.sgml b/docs/tmpl/text-attributes.sgml
index 8d56424b..ba17fed1 100644
--- a/docs/tmpl/text-attributes.sgml
+++ b/docs/tmpl/text-attributes.sgml
@@ -52,7 +52,7 @@ attribute is listed in parentheses after the description.
 
 <!-- ##### MACRO PANGO_TYPE_ATTR_TYPE ##### -->
 <para>
-The GObject type for #PangoAttrType.
+The #GObject type for #PangoAttrType.
 </para>
 
 
@@ -384,7 +384,7 @@ of underlining.
 
 <!-- ##### MACRO PANGO_TYPE_UNDERLINE ##### -->
 <para>
-The GObject type for #PangoUnderline.
+The #GObject type for #PangoUnderline.
 </para>
 
 
@@ -522,7 +522,7 @@ represent a color in an uncalibrated RGB colorspace.
 
 <!-- ##### MACRO PANGO_TYPE_COLOR ##### -->
 <para>
-The GObject type for #PangoColor.
+The #GObject type for #PangoColor.
 </para>
 
 
@@ -567,7 +567,7 @@ copied and compared with each other.
 
 <!-- ##### MACRO PANGO_TYPE_LANGUAGE ##### -->
 <para>
-The GObject type for #PangoLanguage. 
+The #GObject type for #PangoLanguage. 
 </para>
 
 
@@ -618,7 +618,7 @@ for more than one paragraph of text.
 
 <!-- ##### MACRO PANGO_TYPE_ATTR_LIST ##### -->
 <para>
-The GObject type for #PangoAttrList.
+The #GObject type for #PangoAttrList.
 </para>
 
 
diff --git a/pango/break.c b/pango/break.c
index 9626e5a4..e400d790 100644
--- a/pango/break.c
+++ b/pango/break.c
@@ -1346,7 +1346,7 @@ pango_default_break (const gchar   *text,
       prev_type = type;
       prev_wc = wc;
 
-      /* wc might not be a valid unicode base character, but really all we
+      /* wc might not be a valid Unicode base character, but really all we
        * need to know is the last non-combining character */
       if (type != G_UNICODE_COMBINING_MARK && 
           type != G_UNICODE_ENCLOSING_MARK && 
diff --git a/pango/fonts.c b/pango/fonts.c
index 352e561e..9082fe59 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -1141,7 +1141,7 @@ pango_font_get_coverage (PangoFont     *font,
  * pango_font_find_shaper:
  * @font: a #PangoFont
  * @language: the language tag
- * @ch: a unicode character.
+ * @ch: a Unicode character.
  * 
  * Finds the best matching shaper for a font for a particular
  * language tag and character point.
@@ -1266,7 +1266,7 @@ pango_font_metrics_new (void)
  * pango_font_metrics_ref:
  * @metrics: a #PangoFontMetrics structure
  * 
- * Increases the reference count of a font metrics structure.
+ * Increase the reference count of a font metrics structure by one.
  * 
  * Return value: @metrics
  **/
@@ -1284,7 +1284,7 @@ pango_font_metrics_ref (PangoFontMetrics *metrics)
  * pango_font_metrics_unref:
  * @metrics: a #PangoFontMetrics structure
  * 
- * Decreases the reference count of a font metrics structure. If
+ * Decrease the reference count of a font metrics structure by one. If
  * the result is zero, frees the structure and any associated
  * memory.
  **/
diff --git a/pango/pango-fontset.c b/pango/pango-fontset.c
index f02344a1..261b6d70 100644
--- a/pango/pango-fontset.c
+++ b/pango/pango-fontset.c
@@ -43,10 +43,10 @@ PANGO_DEFINE_TYPE_ABSTRACT (PangoFontset, pango_fontset,
 /**
  * pango_fontset_get_font:
  * @fontset: a #PangoFontset
- * @wc: a unicode character
+ * @wc: a Unicode character
  *
  * Returns the font in the fontset that contains the best glyph for the
- * unicode character wc.
+ * Unicode character @wc.
  *
  * Returns: a #PangoFont. The caller must call g_object_unref when finished
  *          with the font.
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 65d06097..e6e78f24 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -94,7 +94,7 @@ struct _PangoLayoutIter
   /* first glyph in the next cluster */
   int next_cluster_glyph;
 
-  /* number of unicode chars in current cluster */
+  /* number of Unicode chars in current cluster */
   int cluster_num_chars;
 
   /* visual position of current character within the cluster */
@@ -202,7 +202,7 @@ pango_layout_finalize (GObject *object)
  * Create a new #PangoLayout object with attributes initialized to
  * default values for a particular #PangoContext.
  * 
- * Return value: a new #PangoLayout, with a reference count of one.
+ * Return value: the new #PangoLayout, with a reference count of one.
  **/
 PangoLayout *
 pango_layout_new (PangoContext *context)
@@ -227,7 +227,7 @@ pango_layout_new (PangoContext *context)
  * tab array, and text from the original layout are all copied by
  * value.
  * 
- * Return value: a new #PangoLayout identical to @src
+ * Return value: the new #PangoLayout.
  **/
 PangoLayout*
 pango_layout_copy (PangoLayout *src)
@@ -271,7 +271,7 @@ pango_layout_copy (PangoLayout *src)
  * 
  * Retrieves the #PangoContext used for this layout.
  * 
- * Return value: The #PangoContext for the layout. This does not
+ * Return value: the #PangoContext for the layout. This does not
  * have an additional refcount added, so if you want to keep
  * a copy of this around, you must reference it yourself.
  **/
@@ -289,7 +289,7 @@ pango_layout_get_context (PangoLayout *layout)
  * @width: the desired width, or -1 to indicate that no wrapping should be
  *         performed.
  * 
- * Sets the width to which the lines of the #PangoLayout should be wrapped.
+ * Sets the width to which the lines of the #PangoLayout should wrap.
  **/
 void
 pango_layout_set_width (PangoLayout *layout,
@@ -308,9 +308,9 @@ pango_layout_set_width (PangoLayout *layout,
  * pango_layout_get_width:
  * @layout: a #PangoLayout
  * 
- * Gets the width to which the lines of the #PangoLayout should be wrapped.
+ * Gets the width to which the lines of the #PangoLayout should wrap.
  * 
- * Return value: the width
+ * Return value: the width.
  **/
 int
 pango_layout_get_width (PangoLayout    *layout)
@@ -324,7 +324,7 @@ pango_layout_get_width (PangoLayout    *layout)
  * @layout: a #PangoLayout
  * @wrap: the wrap mode
  * 
- * Sets the wrap mode; the wrap mode only has an effect if a width
+ * Sets the wrap mode; the wrap mode only has effect if a width
  * is set on the layout with pango_layout_set_width(). To turn off wrapping,
  * set the width to -1.
  **/
@@ -347,7 +347,7 @@ pango_layout_set_wrap (PangoLayout  *layout,
  * 
  * Gets the wrap mode for the layout.
  * 
- * Return value: Active wrap mode.
+ * Return value: active wrap mode.
  **/
 PangoWrapMode
 pango_layout_get_wrap (PangoLayout *layout)
@@ -360,10 +360,10 @@ pango_layout_get_wrap (PangoLayout *layout)
 /**
  * pango_layout_set_indent
  * @layout: a #PangoLayout.
- * @indent: the amount by which to indentset
+ * @indent: the amount by which to indent.
  * 
  * Sets the width in Pango units to indent each paragraph. A negative value
- * of @indent will produce a hanging indent. That is, the first line will
+ * of @indent will produce a hanging indentation. That is, the first line will
  * have the full width, and subsequent lines will be indented by the
  * absolute value of @indent.
  **/
@@ -385,9 +385,9 @@ pango_layout_set_indent (PangoLayout *layout,
  * @layout: a #PangoLayout
  * 
  * Gets the paragraph indent width in Pango units. A negative value
- * indicates a hanging indent.
+ * indicates a hanging indentation.
  * 
- * Return value: the indent
+ * Return value: the indent.
  **/
 int
 pango_layout_get_indent (PangoLayout *layout)
@@ -401,7 +401,9 @@ pango_layout_get_indent (PangoLayout *layout)
  * @layout: a #PangoLayout.
  * @spacing: the amount of spacing
  * 
- * Sets the amount of spacing between the lines of the layout.
+ * Sets the amount of spacing in #PangoGlyphUnit between the lines of the
+ * layout.
+ *
  **/
 void
 pango_layout_set_spacing (PangoLayout *layout,
@@ -420,9 +422,10 @@ pango_layout_set_spacing (PangoLayout *layout,
  * pango_layout_get_spacing:
  * @layout: a #PangoLayout
  * 
- * Gets the amount of spacing between the lines of the layout.
+ * Gets the amount of spacing in #PangoGlyphUnit between the lines of the
+ * layout.
  * 
- * Return value: the spacing (in #PangoGlyphUnit)
+ * Return value: the spacing.
  **/
 int
 pango_layout_get_spacing (PangoLayout *layout)
@@ -463,7 +466,7 @@ pango_layout_set_attributes (PangoLayout   *layout,
  * 
  * Gets the attribute list for the layout, if any.
  * 
- * Return value: a #PangoAttrList
+ * Return value: a #PangoAttrList.
  **/
 PangoAttrList*
 pango_layout_get_attributes (PangoLayout *layout)
@@ -477,7 +480,7 @@ pango_layout_get_attributes (PangoLayout *layout)
  * pango_layout_set_font_description:
  * @layout: a #PangoLayout
  * @desc: the new #PangoFontDescription, or %NULL to unset the
- *        current font description.
+ *        current font description
  * 
  * Sets the default font description for the layout. If no font 
  * description is set on the layout, the font description from
@@ -528,12 +531,13 @@ pango_layout_get_font_description (PangoLayout *layout)
  * @layout: a #PangoLayout
  * @justify: whether the lines in the layout should be justified.
  * 
- * Sets whether or not each complete line should be stretched to
+ * Sets whether each complete line should be stretched to
  * fill the entire width of the layout. This stretching is typically
  * done by adding whitespace, but for some scripts (such as Arabic),
- * the justification is done by extending the characters.
+ * the justification may be done in more complex ways, like extending
+ * the characters.
  *
- * Note that as of Pango-1.4, this functionality is not yet implemented.
+ * Note that as of Pango-1.10, this functionality is not yet implemented.
  **/
 void
 pango_layout_set_justify (PangoLayout *layout,
@@ -548,10 +552,10 @@ pango_layout_set_justify (PangoLayout *layout,
  * pango_layout_get_justify:
  * @layout: a #PangoLayout
  * 
- * Gets whether or not each complete line should be stretched to
- * fill the entire width of the layout.
+ * Gets whether each complete line should be stretched to fill the entire
+ * width of the layout.
  * 
- * Return value: the justify
+ * Return value: the justify.
  **/
 gboolean
 pango_layout_get_justify (PangoLayout *layout)
@@ -576,11 +580,11 @@ pango_layout_get_justify (PangoLayout *layout)
  * characters get their direction from the surrounding paragraphs.
  *
  * When %FALSE, the choice between left-to-right and
- * right-to-left layout is done by according to the base direction
+ * right-to-left layout is done according to the base direction
  * of the layout's #PangoContext. (See pango_context_set_base_dir()).
  *
  * When the auto-computed direction or a paragraph differs from the
- * base direction of the context, then the interpretation of
+ * base direction of the context, the interpretation of
  * %PANGO_ALIGN_LEFT and %PANGO_ALIGN_RIGHT are swapped. 
  **/
 void
@@ -606,8 +610,8 @@ pango_layout_set_auto_dir (PangoLayout *layout,
  * for the layout according to the contents of the layout.
  * See pango_layout_set_auto_dir().
  * 
- * Return value: if %TRUE, the bidirectional base direction
- *   is computed from the layout's contents.
+ * Return value: %TRUE if the bidirectional base direction
+ *   is computed from the layout's contents, %FALSE otherwise.
  **/
 gboolean
 pango_layout_get_auto_dir (PangoLayout *layout)
@@ -620,10 +624,10 @@ pango_layout_get_auto_dir (PangoLayout *layout)
 /**
  * pango_layout_set_alignment:
  * @layout: a #PangoLayout
- * @alignment: the new alignment
+ * @alignment: the alignment
  * 
- * Sets the alignment for the layout (how partial lines are
- * positioned within the horizontal space available.)
+ * Sets the alignment for the layout: how partial lines are
+ * positioned within the horizontal space available.
  **/
 void
 pango_layout_set_alignment (PangoLayout   *layout,
@@ -638,10 +642,10 @@ pango_layout_set_alignment (PangoLayout   *layout,
  * pango_layout_get_alignment:
  * @layout: a #PangoLayout
  * 
- * Sets the alignment for the layout (how partial lines are
- * positioned within the horizontal space available.)
+ * Gets the alignment for the layout: how partial lines are
+ * positioned within the horizontal space available.
  * 
- * Return value: the alignment value
+ * Return value: the alignment.
  **/
 PangoAlignment
 pango_layout_get_alignment (PangoLayout *layout)
@@ -682,7 +686,7 @@ pango_layout_set_tabs (PangoLayout   *layout,
  * and %NULL is returned. Default tabs are every 8 spaces.
  * The return value should be freed with pango_tab_array_free().
  * 
- * Return value: a copy of the tabs for this layout, or %NULL
+ * Return value: a copy of the tabs for this layout, or %NULL.
  **/
 PangoTabArray*
 pango_layout_get_tabs (PangoLayout *layout)
@@ -729,7 +733,7 @@ pango_layout_set_single_paragraph_mode (PangoLayout *layout,
  * Obtains the value set by pango_layout_set_single_paragraph_mode().
  * 
  * Return value: %TRUE if the layout does not break paragraphs at 
- * paragraph separator characters
+ * paragraph separator characters, %FALSE otherwise.
  **/
 gboolean
 pango_layout_get_single_paragraph_mode (PangoLayout *layout)
@@ -776,7 +780,7 @@ pango_layout_set_ellipsize (PangoLayout        *layout,
  * Gets the type of ellipsization being performed for @layout.
  * See pango_layout_set_ellipsize()
  * 
- * Return value: the current ellipsization mode for @layout
+ * Return value: the current ellipsization mode for @layout.
  *
  * Since: 1.6
  **/
@@ -845,7 +849,7 @@ pango_layout_set_text (PangoLayout *layout,
  * Gets the text in the layout. The returned text should not
  * be freed or modified.
  * 
- * Return value: the text in the @layout
+ * Return value: the text in the @layout.
  **/
 const char*
 pango_layout_get_text (PangoLayout *layout)
@@ -859,7 +863,8 @@ pango_layout_get_text (PangoLayout *layout)
  * pango_layout_set_markup:
  * @layout: a #PangoLayout
  * @markup: marked-up text
- * @length: length of marked-up text in bytes, or -1
+ * @length: length of marked-up text in bytes, or -1 if @markup is
+ * nul-terminated
  *
  * Same as pango_layout_set_markup_with_accel(), but
  * the markup text isn't scanned for accelerators.
@@ -876,11 +881,12 @@ pango_layout_set_markup (PangoLayout *layout,
 /**
  * pango_layout_set_markup_with_accel:
  * @layout: a #PangoLayout
- * @markup: some marked-up text 
+ * @markup: marked-up text 
  * (see <link linkend="PangoMarkupFormat">markup format</link>)
- * @length: length of @markup in bytes
+ * @length: length of marked-up text in bytes, or -1 if @markup is
+ * nul-terminated
  * @accel_marker: marker for accelerators in the text
- * @accel_char: return location for any located accelerators
+ * @accel_char: return location for first located accelerator, or %NULL
  * 
  * Sets the layout text and attribute list from marked-up text (see
  * <link linkend="PangoMarkupFormat">markup format</link>). Replaces
@@ -982,7 +988,7 @@ pango_layout_get_log_attrs (PangoLayout    *layout,
  * 
  * Retrieves the count of lines for the @layout.
  * 
- * Return value: the line count
+ * Return value: the line count.
  **/
 int
 pango_layout_get_line_count (PangoLayout   *layout)
@@ -1463,7 +1469,7 @@ pango_layout_move_cursor_visually (PangoLayout *layout,
  * If either the X or Y positions were not inside the layout, then the
  * function returns %FALSE; on an exact hit, it returns %TRUE.
  *
- * Return value: %TRUE if the coordinates were inside text
+ * Return value: %TRUE if the coordinates were inside text, %FALSE otherwise.
  **/
 gboolean
 pango_layout_xy_to_index (PangoLayout *layout,
@@ -1873,14 +1879,17 @@ direction_simple (PangoDirection d)
 {
   switch (d)
     {
-    case PANGO_DIRECTION_LTR :	    return 1;
-    case PANGO_DIRECTION_RTL :	    return -1;
-    case PANGO_DIRECTION_TTB_LTR :  return 1;
-    case PANGO_DIRECTION_TTB_RTL :  return -1;
-    case PANGO_DIRECTION_WEAK_LTR : return 1;
-    case PANGO_DIRECTION_WEAK_RTL : return -1;
-    case PANGO_DIRECTION_NEUTRAL :  return 0;
-    /* no default compiler should complain if a new values is added */
+    case PANGO_DIRECTION_LTR :
+    case PANGO_DIRECTION_WEAK_LTR :
+    case PANGO_DIRECTION_TTB_RTL :
+      return 1;
+    case PANGO_DIRECTION_RTL :
+    case PANGO_DIRECTION_WEAK_RTL :
+    case PANGO_DIRECTION_TTB_LTR :
+      return -1;
+    case PANGO_DIRECTION_NEUTRAL :
+      return 0;
+    /* no default, compiler should complain if a new values is added */
     }
   /* not reached */
   return 0;
@@ -3320,9 +3329,11 @@ pango_layout_check_lines (PangoLayout *layout)
  * pango_layout_line_ref:
  * @line: a #PangoLayoutLine
  * 
- * Increases the reference count of a #PangoLayoutLine by one.
+ * Increase the reference count of a #PangoLayoutLine by one.
+ *
+ * Return value: the line passed in.
  *
- * Return value: the line passed in (since 1.10)
+ * Since: 1.10
  **/
 PangoLayoutLine *
 pango_layout_line_ref (PangoLayoutLine *line)
@@ -3340,8 +3351,8 @@ pango_layout_line_ref (PangoLayoutLine *line)
  * pango_layout_line_unref:
  * @line: a #PangoLayoutLine
  * 
- * Decreases the reference count of a #PangoLayoutLine by one.
- * if the result is zero, the line and all associated memory
+ * Decrease the reference count of a #PangoLayoutLine by one.
+ * If the result is zero, the line and all associated memory
  * will be freed.
  **/
 void
@@ -3382,7 +3393,7 @@ pango_layout_line_get_type(void)
 /**
  * pango_layout_line_x_to_index:
  * @line:      a #PangoLayoutLine
- * @x_pos:     the x offset (in #PangoGlyphUnit)
+ * @x_pos:     the X offset (in #PangoGlyphUnit)
  *             from the left edge of the line.
  * @index_:    location to store calculated byte index for
  *             the grapheme in which the user clicked.
@@ -3913,13 +3924,13 @@ pango_layout_run_get_extents (PangoLayoutRun *run,
 /**
  * pango_layout_line_get_extents:
  * @line:     a #PangoLayoutLine
- * @ink_rect: rectangle used to store the extents of the glyph string as drawn
- *            or %NULL to indicate that the result is not needed.
- * @logical_rect: rectangle used to store the logical extents of the glyph string
- *            or %NULL to indicate that the result is not needed.
+ * @ink_rect: rectangle used to store the extents of the glyph string
+ *            as drawn, or %NULL
+ * @logical_rect: rectangle used to store the logical extents of the glyph
+ *            string, or %NULL
  * 
- * Computes the logical and ink extents of a layout line. See the documentation
- * for pango_font_get_glyph_extents() for details about the interpretation
+ * Computes the logical and ink extents of a layout line. See
+ * pango_font_get_glyph_extents() for details about the interpretation
  * of the rectangles.
  */
 void
@@ -4027,13 +4038,13 @@ pango_layout_line_new (PangoLayout *layout)
 /**
  * pango_layout_line_get_pixel_extents:
  * @layout_line: a #PangoLayoutLine
- * @ink_rect:    rectangle used to store the extents of the glyph string as drawn
- *               or %NULL to indicate that the result is not needed.
- * @logical_rect: rectangle used to store the logical extents of the glyph string
- *               or %NULL to indicate that the result is not needed.
+ * @ink_rect:    rectangle used to store the extents of the glyph string
+ *               as drawn, or %NULL
+ * @logical_rect: rectangle used to store the logical extents of the glyph
+ *               string, or %NULL
  * 
- * Computes the logical and ink extents of a layout line. See the documentation
- * for pango_font_get_glyph_extents() for details about the interpretation
+ * Computes the logical and ink extents of a layout line. See
+ * pango_font_get_glyph_extents() for details about the interpretation
  * of the rectangles. The returned rectangles are in device units, as
  * opposed to pango_layout_line_get_extents(), which returns the extents in
  * #PangoGlyphUnit.
@@ -4569,7 +4580,7 @@ pango_layout_iter_get_type (void)
  * 
  * Returns an iterator to iterate over the visual extents of the layout.
  * 
- * Return value: a new #PangoLayoutIter
+ * Return value: the new #PangoLayoutIter.
  **/
 PangoLayoutIter*
 pango_layout_get_iter (PangoLayout *layout)
@@ -4641,7 +4652,7 @@ pango_layout_iter_free (PangoLayoutIter *iter)
  * sequential. Also, the index may be equal to the length of the text
  * in the layout, if on the %NULL run (see pango_layout_iter_get_run()).
  * 
- * Return value: current byte index
+ * Return value: current byte index.
  **/
 int
 pango_layout_iter_get_index (PangoLayoutIter *iter)
@@ -4661,7 +4672,7 @@ pango_layout_iter_get_index (PangoLayoutIter *iter)
  * %NULL. The %NULL run at the end of each line ensures that all lines have
  * at least one run, even lines consisting of only a newline.
  * 
- * Return value: the current run
+ * Return value: the current run.
  **/
 PangoLayoutRun*
 pango_layout_iter_get_run (PangoLayoutIter *iter)
@@ -4678,7 +4689,7 @@ pango_layout_iter_get_run (PangoLayoutIter *iter)
  * 
  * Gets the current line.
  * 
- * Return value: the current line
+ * Return value: the current line.
  **/
 PangoLayoutLine*
 pango_layout_iter_get_line (PangoLayoutIter *iter)
@@ -4695,7 +4706,7 @@ pango_layout_iter_get_line (PangoLayoutIter *iter)
  * 
  * Determines whether @iter is on the last line of the layout.
  * 
- * Return value: %TRUE if @iter is on the last line
+ * Return value: %TRUE if @iter is on the last line.
  **/
 gboolean
 pango_layout_iter_at_last_line (PangoLayoutIter *iter)
@@ -4815,7 +4826,7 @@ next_cluster_internal (PangoLayoutIter *iter,
  * Moves @iter forward to the next character in visual order. If @iter was already at
  * the end of the layout, returns %FALSE.
  * 
- * Return value: whether motion was possible
+ * Return value: whether motion was possible.
  **/
 gboolean
 pango_layout_iter_next_char (PangoLayoutIter *iter)
@@ -4859,7 +4870,7 @@ pango_layout_iter_next_char (PangoLayoutIter *iter)
  * Moves @iter forward to the next cluster in visual order. If @iter
  * was already at the end of the layout, returns %FALSE.
  * 
- * Return value: whether motion was possible
+ * Return value: whether motion was possible.
  **/
 gboolean
 pango_layout_iter_next_cluster (PangoLayoutIter *iter)
@@ -4874,7 +4885,7 @@ pango_layout_iter_next_cluster (PangoLayoutIter *iter)
  * Moves @iter forward to the next run in visual order. If @iter was
  * already at the end of the layout, returns %FALSE.
  * 
- * Return value: whether motion was possible
+ * Return value: whether motion was possible.
  **/
 gboolean
 pango_layout_iter_next_run (PangoLayoutIter *iter)
@@ -4918,7 +4929,7 @@ pango_layout_iter_next_run (PangoLayoutIter *iter)
  * Moves @iter forward to the start of the next line. If @iter is
  * already on the last line, returns %FALSE.
  * 
- * Return value: whether motion was possible
+ * Return value: whether motion was possible.
  **/
 gboolean
 pango_layout_iter_next_line (PangoLayoutIter *iter)
@@ -5005,8 +5016,8 @@ pango_layout_iter_get_char_extents (PangoLayoutIter *iter,
 /**
  * pango_layout_iter_get_cluster_extents:
  * @iter: a #PangoLayoutIter
- * @ink_rect: rectangle to fill with ink extents
- * @logical_rect: rectangle to fill with logical extents
+ * @ink_rect: rectangle to fill with ink extents, or %NULL
+ * @logical_rect: rectangle to fill with logical extents, or %NULL
  *
  * Gets the extents of the current cluster, in layout coordinates
  * (origin is the top left of the entire layout).
@@ -5052,8 +5063,8 @@ pango_layout_iter_get_cluster_extents (PangoLayoutIter *iter,
 /**
  * pango_layout_iter_get_run_extents:
  * @iter: a #PangoLayoutIter
- * @ink_rect: rectangle to fill with ink extents
- * @logical_rect: rectangle to fill with logical extents
+ * @ink_rect: rectangle to fill with ink extents, or %NULL
+ * @logical_rect: rectangle to fill with logical extents, or %NULL
  * 
  * Gets the extents of the current run in layout coordinates
  * (origin is the top left of the entire layout).
@@ -5094,8 +5105,8 @@ pango_layout_iter_get_run_extents (PangoLayoutIter *iter,
 /**
  * pango_layout_iter_get_line_extents:
  * @iter: a #PangoLayoutIter
- * @ink_rect: rectangle to fill with ink extents
- * @logical_rect: rectangle to fill with logical extents
+ * @ink_rect: rectangle to fill with ink extents, or %NULL
+ * @logical_rect: rectangle to fill with logical extents, or %NULL
  *
  * Obtains the extents of the current line. @ink_rect or @logical_rect
  * can be NULL if you aren't interested in them. Extents are in layout
@@ -5142,7 +5153,7 @@ pango_layout_iter_get_line_extents (PangoLayoutIter *iter,
  * the current line.  A line's range includes the line's logical
  * extents, plus half of the spacing above and below the line, if
  * pango_layout_set_spacing() has been called to set layout spacing.
- * The y positions are in layout coordinates (origin at top left of the
+ * The Y positions are in layout coordinates (origin at top left of the
  * entire layout).
  * 
  **/
@@ -5188,10 +5199,10 @@ pango_layout_iter_get_line_yrange (PangoLayoutIter *iter,
  * pango_layout_iter_get_baseline:
  * @iter: a #PangoLayoutIter
  * 
- * Gets the y position of the current line's baseline, in layout
+ * Gets the Y position of the current line's baseline, in layout
  * coordinates (origin at top left of the entire layout).
  * 
- * Return value: baseline of current line
+ * Return value: baseline of current line.
  **/
 int
 pango_layout_iter_get_baseline (PangoLayoutIter *iter)
@@ -5209,8 +5220,8 @@ pango_layout_iter_get_baseline (PangoLayoutIter *iter)
 /**
  * pango_layout_iter_get_layout_extents:
  * @iter: a #PangoLayoutIter
- * @ink_rect: rectangle to fill with ink extents
- * @logical_rect: rectangle to fill with logical extents
+ * @ink_rect: rectangle to fill with ink extents, or %NULL
+ * @logical_rect: rectangle to fill with logical extents, or %NULL
  *
  * Obtains the extents of the #PangoLayout being iterated
  * over. @ink_rect or @logical_rect can be NULL if you
diff --git a/pango/pango-script.c b/pango/pango-script.c
index 9113d799..5a8e1058 100644
--- a/pango/pango-script.c
+++ b/pango/pango-script.c
@@ -84,11 +84,11 @@ struct _PangoScriptIter
 
 /**
  * pango_script_for_unichar:
- * @ch: a unicode characters
+ * @ch: a Unicode character
  * 
  * Looks up the #PangoScript for a particular character (as defined by
- * Unicode Technical report #24). No check is made for @ch being
- * valid unicode character; if you pass in invalid character, the
+ * 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.
  * 
  * Return value: the #PangoScript for the character.
@@ -118,14 +118,14 @@ pango_script_for_unichar (gunichar ch)
 /**
  * pango_script_iter_new:
  * @text: a UTF-8 string
- * @length: length of @text, or -1 if @text is NUL-terminated.
+ * @length: length of @text, or -1 if @text is nul-terminated.
  * 
  * Create a new #PangoScriptIter, used to break a string of
  * Unicode into runs by text. No copy is made of @text, so
  * the caller needs to make sure it remains valid until
  * the iterator is freed with pango_script_iter_free ().x
  * 
- * Return value: the newly created script iterator, initialized
+ * Return value: the new script iterator, initialized
  *  to point at the first range in the text. If the string is
  *  empty, it will point at an empty range.
  **/
diff --git a/pango/pango-utils.c b/pango/pango-utils.c
index d7584561..406c304a 100644
--- a/pango/pango-utils.c
+++ b/pango/pango-utils.c
@@ -1427,10 +1427,10 @@ pango_log2vis_get_embedding_levels (gunichar       *str,
 
 /**
  * pango_get_mirror_char:
- * @ch: a unicode character
+ * @ch: a Unicode character
  * @mirrored_ch: location to store the mirrored character
  *
- * If @ch has the Unicode mirrored property and there is another unicode
+ * If @ch has the Unicode mirrored property and there is another Unicode
  * character that typically has a glyph that is the mirror image of @ch's
  * glyph, puts that character in the address pointed to by @mirrored_ch.
  *
@@ -1717,7 +1717,7 @@ pango_find_base_dir (const gchar *text,
 
 /**
  * pango_is_zero_width:
- * @ch: a unicode character
+ * @ch: a Unicode character
  *
  * Checks @ch to see if it is a zero-width character that should not be
  * normally rendered on the screen.
diff --git a/pango/pangofc-decoder.c b/pango/pangofc-decoder.c
index 766e09e7..cae86fc6 100644
--- a/pango/pangofc-decoder.c
+++ b/pango/pangofc-decoder.c
@@ -67,9 +67,9 @@ pango_fc_decoder_get_charset (PangoFcDecoder *decoder,
  * pango_fc_decoder_get_glyph:
  * @decoder: a #PangoFcDecoder
  * @fcfont: a #PangoFcFont to query.
- * @wc: the unicode code point to convert to a single #PangoGlyph.
+ * @wc: the Unicode code point to convert to a single #PangoGlyph.
  *
- * Generates a #PangoGlyph for the given unicode point using the
+ * Generates a #PangoGlyph for the given Unicode point using the
  * custom decoder. For complex scripts where there can be multiple
  * glyphs for a single character, the decoder will return whatever
  * glyph is most convenient for it. (Usually whatever glyph is directly
diff --git a/pango/pangofc-decoder.h b/pango/pangofc-decoder.h
index d5bb6818..f812c1e2 100644
--- a/pango/pangofc-decoder.h
+++ b/pango/pangofc-decoder.h
@@ -65,8 +65,8 @@ struct _PangoFcDecoder
  *  #FcCharSet that is returned should be an internal reference to your
  *  code.  Pango will not free this structure.  It is important that
  *  you make this callback fast because this callback is called
- *  separately for each character to determine unicode coverage.
- * @get_glyph: This returns a single #PangoGlyph for a given unicode
+ *  separately for each character to determine Unicode coverage.
+ * @get_glyph: This returns a single #PangoGlyph for a given Unicode
  *  code point.
  *
  * Class structure for #PangoFcDecoder.
diff --git a/pango/pangofc-font.c b/pango/pangofc-font.c
index 21ddf8d0..439fdf1f 100644
--- a/pango/pangofc-font.c
+++ b/pango/pangofc-font.c
@@ -582,14 +582,14 @@ pango_fc_font_has_char (PangoFcFont *font,
 /**
  * pango_fc_font_get_glyph:
  * @font: a #PangoFcFont
- * @wc: Unicode codepoint to look up
+ * @wc: Unicode character to look up
  * 
- * Gets the glyph index for a given unicode codepoint
+ * Gets the glyph index for a given Unicode character
  * for @font. If you only want to determine
  * whether the font has the glyph, use pango_fc_font_has_char().
  * 
- * Return value: the glyph index, or 0, if the unicode
- *  codepoint doesn't exist in the font.
+ * Return value: the glyph index, or 0, if the Unicode
+ *   character doesn't exist in the font.
  *
  * Since: 1.4
  **/
diff --git a/pango/pangofc-font.h b/pango/pangofc-font.h
index 42282c53..404f6ad3 100644
--- a/pango/pangofc-font.h
+++ b/pango/pangofc-font.h
@@ -95,7 +95,7 @@ struct _PangoFcFont
  *   Unicode character.
  * @get_unknown_glyph: Gets the glyph that should be used to
  *   display an unknown-glyph indication for the specified
- *   unicode character.
+ *   Unicode character.
  * @shutdown: Performs any font-specific shutdown code that
  *   needs to be done when pango_fc_font_map_shutdown is called.
  *   May be %NULL.
diff --git a/pango/pangoxft-font.c b/pango/pangoxft-font.c
index f4726f59..258b7a44 100644
--- a/pango/pangoxft-font.c
+++ b/pango/pangoxft-font.c
@@ -567,14 +567,14 @@ pango_xft_font_unlock_face (PangoFont *font)
  * @font: a #PangoFont for the Xft backend
  * @wc: Unicode codepoint to look up
  * 
- * Gets the glyph index for a given unicode codepoint
+ * Gets the glyph index for a given Unicode character
  * for @font. If you only want to determine
  * whether the font has the glyph, use pango_xft_font_has_char().
  * 
  * Use pango_fc_font_get_glyph() instead.
  *
- * Return value: the glyph index, or 0, if the unicode
- *  codepoint doesn't exist in the font.
+ * Return value: the glyph index, or 0, if the Unicode
+ *  character does not exist in the font.
  *
  * Since: 1.2
  **/