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.

8 files changed, 82 insertions, 5 deletions

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
  *