Documentation updates.

        * pango/fonts.c, pango/pangoft2.c, pango/pangowin32.c,
        pango/pangoxft-font.c, pango/pangox-fontmap.c,
        pango/pangoft2-fontmap.c, pango/pangoxft-fontmap.c,
        pango/pangowin32-fontmap.c, docs/pango-sections.txt,
        docs/tmpl/coverage-maps.sgml, docs/tmpl/fonts.sgml,
        docs/tmpl/freetype-fonts.sgml, docs/tmpl/glyphs.sgml,
        docs/tmpl/layout.sgml, docs/tmpl/main.sgml, docs/tmpl/modules.sgml,
        docs/tmpl/tab-stops.sgml, docs/tmpl/text-attributes.sgml,
        docs/tmpl/win32-fonts.sgml: Documentation updates.

19 files changed, 204 insertions, 147 deletions

diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
index 66836e15..3a0587f6 100644
--- a/docs/pango-sections.txt
+++ b/docs/pango-sections.txt
@@ -28,7 +28,6 @@ pango_context_get_metrics
 pango_context_list_families
 <SUBSECTION Standard>
 PANGO_TYPE_CONTEXT
-pango_context_get_type
 PangoContextClass
 PANGO_CONTEXT
 PANGO_CONTEXT_CLASS
@@ -46,6 +45,7 @@ pango_shape
 
 <SUBSECTION Private>
 pango_direction_get_type
+pango_context_get_type
 </SECTION>
 
 <SECTION>
@@ -145,23 +145,23 @@ pango_font_description_to_string
 pango_font_description_to_filename
 <SUBSECTION>
 PangoFontMetrics
+PANGO_TYPE_FONT_METRICS
 pango_font_metrics_ref
 pango_font_metrics_unref
 pango_font_metrics_get_ascent
 pango_font_metrics_get_descent
 pango_font_metrics_get_approximate_char_width
 pango_font_metrics_get_approximate_digit_width
-PANGO_TYPE_FONT_METRICS
 <SUBSECTION>
 PangoFont
+PANGO_TYPE_FONT
+PANGO_FONT
+PANGO_IS_FONT
 pango_font_find_shaper
 pango_font_describe
 pango_font_get_coverage
 pango_font_get_glyph_extents
 pango_font_get_metrics
-PANGO_TYPE_FONT
-PANGO_FONT
-PANGO_IS_FONT
 <SUBSECTION>
 PangoFontFamily
 PANGO_TYPE_FONT_FAMILY
@@ -178,34 +178,21 @@ pango_font_face_get_face_name
 pango_font_face_describe
 <SUBSECTION>
 PangoFontMap
-PangoFontMapClass
-pango_font_map_load_font
-pango_font_map_list_families
 PANGO_TYPE_FONT_MAP
 PANGO_FONT_MAP
 PANGO_IS_FONT_MAP
+PangoFontMapClass
 PANGO_FONT_MAP_CLASS
 PANGO_IS_FONT_MAP_CLASS
 PANGO_FONT_MAP_GET_CLASS
+pango_font_map_load_font
+pango_font_map_list_families
 
-<SUBSECTION Private>
-pango_font_get_type
-pango_stretch_get_type
-pango_style_get_type
-pango_variant_get_type
-pango_weight_get_type
-pango_font_mask_get_type
-pango_font_description_get_type
-pango_font_map_get_type
-pango_font_face_get_type
-pango_font_family_get_type
-pango_font_metrics_get_type
-
+<SUBSECTION Standard>
 PANGO_FONT_FACE_CLASS
 PANGO_IS_FONT_CLASS
 PANGO_FONT_FACE_GET_CLASS
 PangoFontFamilyClass
-pango_font_metrics_new
 PangoFontFaceClass
 PANGO_FONT_GET_CLASS
 PANGO_FONT_CLASS
@@ -214,6 +201,20 @@ PangoFontClass
 PANGO_FONT_FAMILY_GET_CLASS
 PANGO_FONT_FAMILY_CLASS
 PANGO_IS_FONT_FACE_CLASS
+
+<SUBSECTION Private>
+pango_font_metrics_new
+pango_font_get_type
+pango_stretch_get_type
+pango_style_get_type
+pango_variant_get_type
+pango_weight_get_type
+pango_font_mask_get_type
+pango_font_description_get_type
+pango_font_map_get_type
+pango_font_face_get_type
+pango_font_family_get_type
+pango_font_metrics_get_type
 </SECTION>
 
 <SECTION>
@@ -406,13 +407,15 @@ pango_layout_line_get_x_ranges
 
 <SUBSECTION Standard>
 PANGO_TYPE_LAYOUT
-pango_layout_get_type
 PangoLayoutClass
 PANGO_LAYOUT
 PANGO_IS_LAYOUT
 PANGO_LAYOUT_CLASS
 PANGO_IS_LAYOUT_CLASS
 PANGO_LAYOUT_GET_CLASS
+
+<SUBSECTION Private>
+pango_layout_get_type
 pango_alignment_get_type
 pango_wrap_mode_get_type
 </SECTION>
@@ -564,9 +567,12 @@ pango_xft_font_get_face
 pango_xft_font_get_ot_info
 pango_xft_font_get_display
 pango_xft_font_get_unknown_glyph
+
 <SUBSECTION Standard>
 PANGO_TYPE_XFT_FONT
 PANGO_XFT_IS_FONT
+
+<SUBSECTION Private>
 pango_xft_font_get_type
 </SECTION>
 
diff --git a/docs/tmpl/coverage-maps.sgml b/docs/tmpl/coverage-maps.sgml
index cd6e08ba..c3116ed2 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.
 </para>
 
 
diff --git a/docs/tmpl/fonts.sgml b/docs/tmpl/fonts.sgml
index 3296324c..9ff62359 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.
 </para>
 
 
@@ -45,7 +45,7 @@ the characteristics of a font to load.
 
 <!-- ##### MACRO PANGO_TYPE_STYLE ##### -->
 <para>
-
+The GObject type for #PangoStyle.
 </para>
 
 
@@ -65,7 +65,7 @@ value ranging from 100 to 900, but there are some predefined values:
 
 <!-- ##### MACRO PANGO_TYPE_WEIGHT ##### -->
 <para>
-
+The GObject type for #PangoWeight.
 </para>
 
 
@@ -81,7 +81,7 @@ An enumeration specifying capitalization variant of the font.
 
 <!-- ##### MACRO PANGO_TYPE_VARIANT ##### -->
 <para>
-
+The GObject type for #PangoVariant.
 </para>
 
 
@@ -104,7 +104,7 @@ within a family.
 
 <!-- ##### MACRO PANGO_TYPE_STRETCH ##### -->
 <para>
-
+The GObject type for #PangoStretch.
 </para>
 
 
@@ -123,7 +123,7 @@ within a family.
 
 <!-- ##### MACRO PANGO_TYPE_FONT_MASK ##### -->
 <para>
-
+The GObject type for #PangoFontMask.
 </para>
 
 
@@ -394,6 +394,13 @@ within a family.
 @approximate_char_width: 
 @approximate_digit_width: 
 
+
+<!-- ##### MACRO PANGO_TYPE_FONT_METRICS ##### -->
+<para>
+The GObject type for #PangoFontMetrics.
+</para>
+
+
 <!-- ##### FUNCTION pango_font_metrics_ref ##### -->
 <para>
 
@@ -447,12 +454,6 @@ within a family.
 @Returns: 
 
 
-<!-- ##### MACRO PANGO_TYPE_FONT_METRICS ##### -->
-<para>
-
-</para>
-
-
 
 <!-- ##### STRUCT PangoFont ##### -->
 <para>
@@ -473,6 +474,28 @@ which the implementation fills in:
 
 @parent_instance: 
 
+<!-- ##### MACRO PANGO_TYPE_FONT ##### -->
+<para>
+The GObject type for #PangoFont.
+</para>
+
+
+<!-- ##### MACRO PANGO_FONT ##### -->
+<para>
+Casts a #GObject to a #PangoFont.
+</para>
+
+@object: a #GObject. 
+
+
+<!-- ##### MACRO PANGO_IS_FONT ##### -->
+<para>
+Returns %TRUE if @object is a #PangoFont.
+</para>
+
+@object: a #GObject.
+
+
 <!-- ##### FUNCTION pango_font_find_shaper ##### -->
 <para>
 
@@ -482,9 +505,6 @@ which the implementation fills in:
 @language: 
 @ch: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@lang: 
-@char: 
 
 
 <!-- ##### FUNCTION pango_font_describe ##### -->
@@ -504,8 +524,6 @@ which the implementation fills in:
 @font: 
 @language: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@lang: 
 
 
 <!-- ##### FUNCTION pango_font_get_glyph_extents ##### -->
@@ -527,33 +545,8 @@ which the implementation fills in:
 @font: 
 @language: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@metrics: 
-@lang: 
 
 
-<!-- ##### MACRO PANGO_TYPE_FONT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### MACRO PANGO_FONT ##### -->
-<para>
-
-</para>
-
-@object: 
-
-
-<!-- ##### MACRO PANGO_IS_FONT ##### -->
-<para>
-
-</para>
-
-@object: 
-
 
 <!-- ##### STRUCT PangoFontFamily ##### -->
 <para>
@@ -564,25 +557,25 @@ which the implementation fills in:
 
 <!-- ##### MACRO PANGO_TYPE_FONT_FAMILY ##### -->
 <para>
-
+The GObject type for #PangoFontFamily.
 </para>
 
 
 
 <!-- ##### MACRO PANGO_FONT_FAMILY ##### -->
 <para>
-
+Casts a #GObject to a #PangoFontFamily.
 </para>
 
-@object: 
+@object: a #GObject.
 
 
 <!-- ##### MACRO PANGO_IS_FONT_FAMILY ##### -->
 <para>
-
+Returns %TRUE if @object is a #PangoFontFamily.
 </para>
 
-@object: 
+@object: a #GObject. 
 
 
 <!-- ##### FUNCTION pango_font_family_get_name ##### -->
@@ -613,25 +606,25 @@ which the implementation fills in:
 
 <!-- ##### MACRO PANGO_TYPE_FONT_FACE ##### -->
 <para>
-
+The GObject type for #PangoFontFace.
 </para>
 
 
 
 <!-- ##### MACRO PANGO_FONT_FACE ##### -->
 <para>
-
+Casts a #GObject to a #PangoFontFace.
 </para>
 
-@object: 
+@object: a #GObject. 
 
 
 <!-- ##### MACRO PANGO_IS_FONT_FACE ##### -->
 <para>
-
+Returns %TRUE if @object is a #PangoFontFace.
 </para>
 
-@object: 
+@object: a #GObject. 
 
 
 <!-- ##### FUNCTION pango_font_face_get_face_name ##### -->
@@ -669,84 +662,84 @@ The #PangoFont structure contains one member which the implementation fills in:
 
 @parent_instance: 
 
-<!-- ##### STRUCT PangoFontMapClass ##### -->
+
+<!-- ##### MACRO PANGO_TYPE_FONT_MAP ##### -->
 <para>
-The #PangoFontMapClass structure holds the virtual functions for
-a particular #PangoFontMap implementation.
+The GObject type for #PangoFontMap.
 </para>
 
-@parent_class: 
-@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().
 
-<!-- ##### FUNCTION pango_font_map_load_font ##### -->
-<para>
 
+<!-- ##### MACRO PANGO_FONT_MAP ##### -->
+<para>
+Casts a #GObject to a #PangoFontMap. 
 </para>
 
-@fontmap: 
-@desc: 
-@Returns: 
-<!-- # Unused Parameters # -->
-@size: 
+@object: a #GObject. 
 
 
-<!-- ##### FUNCTION pango_font_map_list_families ##### -->
+<!-- ##### MACRO PANGO_IS_FONT_MAP ##### -->
 <para>
-
+Returns %TRUE if @object is a #PangoFontMap.
 </para>
 
-@fontmap: 
-@families: 
-@n_families: 
+@object: a #GObject. 
 
 
-<!-- ##### MACRO PANGO_TYPE_FONT_MAP ##### -->
+<!-- ##### STRUCT PangoFontMapClass ##### -->
 <para>
-
+The #PangoFontMapClass structure holds the virtual functions for
+a particular #PangoFontMap implementation.
 </para>
 
+@parent_class: 
+@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().
 
 
-<!-- ##### MACRO PANGO_FONT_MAP ##### -->
+<!-- ##### MACRO PANGO_FONT_MAP_CLASS ##### -->
 <para>
-
+Casts a #GObject to a #PangoFontMapClass.
 </para>
 
-@object: 
+@klass: a #GObject. 
 
 
-<!-- ##### MACRO PANGO_IS_FONT_MAP ##### -->
+<!-- ##### MACRO PANGO_IS_FONT_MAP_CLASS ##### -->
 <para>
-
+Returns %TRUE if @klass is a subtype of #PangoFontMapClass.
 </para>
 
-@object: 
+@klass: a #GObject.
 
 
-<!-- ##### MACRO PANGO_FONT_MAP_CLASS ##### -->
+<!-- ##### MACRO PANGO_FONT_MAP_GET_CLASS ##### -->
 <para>
-
+Returns the type of a #PangoFontMap.
 </para>
 
-@klass: 
+@obj: a #PangoFontMap.
 
-
-<!-- ##### MACRO PANGO_IS_FONT_MAP_CLASS ##### -->
+<!-- ##### FUNCTION pango_font_map_load_font ##### -->
 <para>
 
 </para>
 
-@klass: 
+@fontmap: 
+@desc: 
+@Returns: 
 
 
-<!-- ##### MACRO PANGO_FONT_MAP_GET_CLASS ##### -->
+<!-- ##### FUNCTION pango_font_map_list_families ##### -->
 <para>
 
 </para>
 
-@obj: 
+@fontmap: 
+@families: 
+@n_families: 
+
 
 
diff --git a/docs/tmpl/freetype-fonts.sgml b/docs/tmpl/freetype-fonts.sgml
index af453165..a9f06632 100644
--- a/docs/tmpl/freetype-fonts.sgml
+++ b/docs/tmpl/freetype-fonts.sgml
@@ -40,8 +40,6 @@ FreeType Fonts and Rendering
 @n_fonts: 
 @size: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@args: 
 
 
 <!-- ##### FUNCTION pango_ft2_render ##### -->
@@ -146,8 +144,6 @@ FreeType Fonts and Rendering
 @font: 
 @language: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@lang: 
 
 
 <!-- ##### FUNCTION pango_ft2_get_face ##### -->
diff --git a/docs/tmpl/glyphs.sgml b/docs/tmpl/glyphs.sgml
index 079696c4..227cd88e 100644
--- a/docs/tmpl/glyphs.sgml
+++ b/docs/tmpl/glyphs.sgml
@@ -241,7 +241,7 @@ accessible fields
 
 <!-- ##### MACRO PANGO_TYPE_GLYPH_STRING ##### -->
 <para>
-
+The GObject type for #PangoGlyphString.
 </para>
 
 
diff --git a/docs/tmpl/layout.sgml b/docs/tmpl/layout.sgml
index 886340f6..ea58f3ee 100644
--- a/docs/tmpl/layout.sgml
+++ b/docs/tmpl/layout.sgml
@@ -203,7 +203,7 @@ fields.
 
 <!-- ##### MACRO PANGO_TYPE_WRAP_MODE ##### -->
 <para>
-
+The GObject type for #PangoWrapMode.
 </para>
 
 
@@ -330,7 +330,7 @@ for partial lines.
 
 <!-- ##### MACRO PANGO_TYPE_ALIGNMENT ##### -->
 <para>
-
+The GObject type for #PangoAlignment.
 </para>
 
 
diff --git a/docs/tmpl/main.sgml b/docs/tmpl/main.sgml
index 3685b6b6..9db09c07 100644
--- a/docs/tmpl/main.sgml
+++ b/docs/tmpl/main.sgml
@@ -134,7 +134,7 @@ for text.
 
 <!-- ##### MACRO PANGO_TYPE_DIRECTION ##### -->
 <para>
-
+The GObject type for #PangoDirection.
 </para>
 
 
@@ -151,9 +151,6 @@ for text.
 @attrs: 
 @cached_iter: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@lang_info: 
-@n_langs: 
 
 
 <!-- ##### FUNCTION pango_item_free ##### -->
@@ -280,8 +277,6 @@ for text.
 @context: 
 @desc: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@size: 
 
 
 <!-- ##### FUNCTION pango_context_get_metrics ##### -->
@@ -379,7 +374,5 @@ about the attributes of a single character.
 @length: 
 @analysis: 
 @glyphs: 
-<!-- # Unused Parameters # -->
-@font: 
 
 
diff --git a/docs/tmpl/modules.sgml b/docs/tmpl/modules.sgml
index 47ea089a..872b7e1b 100644
--- a/docs/tmpl/modules.sgml
+++ b/docs/tmpl/modules.sgml
@@ -46,8 +46,6 @@ modules
 @engine_type_id: 
 @render_type_id: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@lang: 
 
 
 <!-- ##### FUNCTION pango_map_get_entry ##### -->
diff --git a/docs/tmpl/tab-stops.sgml b/docs/tmpl/tab-stops.sgml
index 2d2359d8..702b7912 100644
--- a/docs/tmpl/tab-stops.sgml
+++ b/docs/tmpl/tab-stops.sgml
@@ -22,7 +22,7 @@ Tab Stops
 
 <!-- ##### MACRO PANGO_TYPE_TAB_ARRAY ##### -->
 <para>
-
+The GObject type for #PangoTabArray.
 </para>
 
 
@@ -36,7 +36,7 @@ Tab Stops
 
 <!-- ##### MACRO PANGO_TYPE_TAB_ALIGN ##### -->
 <para>
-
+The GObject type for #PangoTabAlign.
 </para>
 
 
diff --git a/docs/tmpl/text-attributes.sgml b/docs/tmpl/text-attributes.sgml
index 7bfb1cdd..5254c19b 100644
--- a/docs/tmpl/text-attributes.sgml
+++ b/docs/tmpl/text-attributes.sgml
@@ -46,7 +46,7 @@ attribute is listed in parentheses after the description.
 
 <!-- ##### MACRO PANGO_TYPE_ATTR_TYPE ##### -->
 <para>
-
+The GObject type for #PangoAttrType.
 </para>
 
 
@@ -321,7 +321,7 @@ of underlining.
 
 <!-- ##### MACRO PANGO_TYPE_UNDERLINE ##### -->
 <para>
-
+The GObject type for #PangoUnderline.
 </para>
 
 
@@ -414,7 +414,7 @@ of underlining.
 
 <!-- ##### MACRO PANGO_TYPE_COLOR ##### -->
 <para>
-
+The GObject type for #PangoColor.
 </para>
 
 
@@ -454,7 +454,7 @@ of underlining.
 
 <!-- ##### MACRO PANGO_TYPE_LANGUAGE ##### -->
 <para>
-
+The GObject type for #PangoLanguage. 
 </para>
 
 
@@ -504,7 +504,7 @@ for more than one paragraph of text.
 
 <!-- ##### MACRO PANGO_TYPE_ATTR_LIST ##### -->
 <para>
-
+The GObject type for #PangoAttrList.
 </para>
 
 
@@ -648,10 +648,6 @@ attributes currently in effect can be queried.
 @desc: 
 @language: 
 @extra_attrs: 
-<!-- # Unused Parameters # -->
-@base: 
-@current: 
-@lang: 
 
 
 <!-- ##### FUNCTION pango_attr_iterator_destroy ##### -->
diff --git a/docs/tmpl/win32-fonts.sgml b/docs/tmpl/win32-fonts.sgml
index 25070e07..657e97d5 100644
--- a/docs/tmpl/win32-fonts.sgml
+++ b/docs/tmpl/win32-fonts.sgml
@@ -112,8 +112,6 @@ Win32 Fonts and Rendering
 @cache: 
 @logfont: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@lfp: 
 
 
 <!-- ##### FUNCTION pango_win32_font_cache_unload ##### -->
diff --git a/pango/fonts.c b/pango/fonts.c
index 6ad73f8c..084f0250 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -1025,7 +1025,7 @@ pango_font_describe (PangoFont      *font)
  * 
  * Computes the coverage map for a given font and language tag.
  * 
- * Return value: a newly-allocated #PangoContext object.
+ * Return value: a newly-allocated #PangoCoverage object.
  **/
 PangoCoverage *
 pango_font_get_coverage (PangoFont     *font,
diff --git a/pango/pangoft2-fontmap.c b/pango/pangoft2-fontmap.c
index 32f8af7f..1419347e 100644
--- a/pango/pangoft2-fontmap.c
+++ b/pango/pangoft2-fontmap.c
@@ -276,6 +276,15 @@ pango_ft2_scan_directory (const char      *path,
   return found_font;
 }
 
+/**
+ * pango_ft2_font_map_for_display:
+ *
+ * Returns a #PangoFT2FontMap. Font maps are cached and should
+ * not be freed. If the font map is no longer needed, it can
+ * be released with pango_ft2_shutdown_display().
+ *
+ * Returns: a #PangoFT2FontMap.
+ **/
 PangoFontMap *
 pango_ft2_font_map_for_display (void)
 {
@@ -861,6 +870,14 @@ free_coverages_foreach (gpointer key,
   pango_coverage_unref (value);
 }
 
+/**
+ * pango_ft2_font_map_get_font_cache:
+ * @font_map: a #PangoFT2FontMap.
+ *
+ * Obtains the font cache associated with the given font map.
+ *
+ * Returns: the #PangoFT2FontCache of @font_map.
+ **/
 PangoFT2FontCache *
 pango_ft2_font_map_get_font_cache (PangoFontMap *font_map)
 {
@@ -982,6 +999,13 @@ dump_family (gpointer key,
   pango_ft2_family_entry_dump (indent, entry);
 }
 
+/**
+ * pango_ft2_fontmap_dump:
+ * @indent: the indent to use.
+ * @fontmap: a #PangoFT2FontMap.
+ *
+ * Writes a description of the given font map to stdout.
+ **/
 void
 pango_ft2_fontmap_dump (int           indent,
 			PangoFontMap *fontmap)
diff --git a/pango/pangoft2.c b/pango/pangoft2.c
index a831fc42..ea1653ad 100644
--- a/pango/pangoft2.c
+++ b/pango/pangoft2.c
@@ -709,6 +709,15 @@ pango_ft2_n_subfonts (PangoFont *font)
   return ft2font->n_fonts;
 }
 
+/**
+ * pango_ft2_get_coverage:
+ * @font: a #PangoFT2Font.
+ * @language: the language to compute the coverage for.
+ * 
+ * Computes the coverage of @language by @font.
+ * 
+ * Returns: a newly-allocated #PangoCoverage.
+ **/
 PangoCoverage *
 pango_ft2_get_coverage (PangoFont     *font,
 			PangoLanguage *language)
diff --git a/pango/pangowin32-fontmap.c b/pango/pangowin32-fontmap.c
index 7f2e2b6e..451649c3 100644
--- a/pango/pangowin32-fontmap.c
+++ b/pango/pangowin32-fontmap.c
@@ -1,5 +1,5 @@
 /* Pango
- * pangowin32-fontmap.c: Font handling
+ * pangowin32-fontmap.c: Win32 font handling
  *
  * Copyright (C) 2000 Red Hat Software
  * Copyright (C) 2000 Tor Lillqvist
@@ -228,6 +228,15 @@ pango_win32_enum_proc (LOGFONT    *lfp,
   return 1;
 }
 
+/**
+ * pango_win32_font_map_for_display:
+ *
+ * Returns a #PangoWin32FontMap. 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().
+ *
+ * Returns: a #PangoFontMap.
+ **/
 PangoFontMap *
 pango_win32_font_map_for_display (void)
 {
@@ -975,6 +984,14 @@ pango_win32_font_entry_remove (PangoWin32Face *face,
   face->cached_fonts = g_slist_remove (face->cached_fonts, font);
 }
 
+/**
+ * pango_win32_font_map_get_font_cache:
+ * @font_map: a #PangoWin32FontMap.
+ *
+ * Obtains the font cache associated with the given font map.
+ *
+ * Returns: the #PangoWin32FontCache of @font_map.
+ **/
 PangoWin32FontCache *
 pango_win32_font_map_get_font_cache (PangoFontMap *font_map)
 {
diff --git a/pango/pangowin32.c b/pango/pangowin32.c
index c670fc6e..d184728e 100644
--- a/pango/pangowin32.c
+++ b/pango/pangowin32.c
@@ -997,6 +997,15 @@ font_get_unicode_table (PangoFont *font)
   return table;
 }
 
+/**
+ * pango_win32_font_get_glyph_index:
+ * @font: a #PangoFont.
+ * @wc: a Unicode character.
+ *
+ * Obtains the index of the glyph for @wc in @font.
+ *
+ * Returns: the glyph index for @wc.
+ **/
 gint
 pango_win32_font_get_glyph_index (PangoFont *font,
 				  gunichar   wc)
diff --git a/pango/pangox-fontmap.c b/pango/pangox-fontmap.c
index 4deebe66..213aa251 100644
--- a/pango/pangox-fontmap.c
+++ b/pango/pangox-fontmap.c
@@ -1,5 +1,5 @@
 /* Pango
- * pango-font.h: Font handling
+ * pangox-fontmap.c: X font handling
  *
  * Copyright (C) 2000 Red Hat Software
  *
@@ -217,6 +217,16 @@ pango_x_font_map_class_init (PangoFontMapClass *class)
 
 static GList *fontmaps = NULL;
 
+/**
+ * pango_x_font_map_for_display:
+ * @display: an X #Display.
+ *
+ * Returns a #PangoXFontMap for @display. Font maps are cached and should 
+ * not be freed. If the font map for a display is no longer needed, it can 
+ * be released with pango_x_shutdown_display().
+ *
+ * Returns: a #PangoXFontMap for @display.
+ **/
 PangoFontMap *
 pango_x_font_map_for_display (Display *display)
 {
@@ -1280,6 +1290,14 @@ free_coverages_foreach (gpointer key,
   pango_coverage_unref (value);
 }
 
+/**
+ * pango_x_font_map_get_font_cache:
+ * @font_map: a #PangoXFontMap.
+ *
+ * Obtains the font cache associated with the given font map.
+ *
+ * Returns: the #PangoXFontCache of @font_map.
+ **/
 PangoXFontCache *
 pango_x_font_map_get_font_cache (PangoFontMap *font_map)
 {
diff --git a/pango/pangoxft-font.c b/pango/pangoxft-font.c
index 05311871..94593bc3 100644
--- a/pango/pangoxft-font.c
+++ b/pango/pangoxft-font.c
@@ -512,7 +512,7 @@ pango_xft_font_get_display (PangoFont *font)
 }
 
 /**
- * pango_xft_get_unknown_glyph:
+ * pango_xft_font_get_unknown_glyph:
  * @font: a #PangoFont.
  * @wc: the Unicode character for which a glyph is needed.
  *
diff --git a/pango/pangoxft-fontmap.c b/pango/pangoxft-fontmap.c
index 8202432c..f6d0f261 100644
--- a/pango/pangoxft-fontmap.c
+++ b/pango/pangoxft-fontmap.c
@@ -1,5 +1,5 @@
 /* Pango
- * pangoxft-fontmap.h: Font handling
+ * pangoxft-fontmap.h: Xft font handling
  *
  * Copyright (C) 2000 Red Hat Software
  *