another missing comment end marker and some fixes in gtk-doc comments.

2001-10-15  Sven Neumann  <sven@gimp.org>

	* pango/pangoxft-font.c: another missing comment end marker and some
	fixes in gtk-doc comments.

	* pango/break.c
	* pango/pango-layout.c
	* pango/pangoft2.c
	* docs/pango-sections.txt
	* docs/tmpl/fonts.sgml
	* docs/tmpl/x-fonts.sgml: documentation updates.

14 files changed, 176 insertions, 46 deletions

diff --git a/ChangeLog b/ChangeLog
index d3b2a78f..cab807f7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2001-10-15  Sven Neumann  <sven@gimp.org>
+
+	* pango/pangoxft-font.c: another missing comment end marker and some
+	fixes in gtk-doc comments.
+
+	* pango/break.c
+	* pango/pango-layout.c
+	* pango/pangoft2.c
+	* docs/pango-sections.txt
+	* docs/tmpl/fonts.sgml
+	* docs/tmpl/x-fonts.sgml: documentation updates.
+
 Sun Oct 14 18:42:56 2001  Manish Singh  <yosh@gimp.org>
 	
 	* pango/pangox.c: add missing comment end marker to make it compile
diff --git a/ChangeLog.pre-1-0 b/ChangeLog.pre-1-0
index d3b2a78f..cab807f7 100644
--- a/ChangeLog.pre-1-0
+++ b/ChangeLog.pre-1-0
@@ -1,3 +1,15 @@
+2001-10-15  Sven Neumann  <sven@gimp.org>
+
+	* pango/pangoxft-font.c: another missing comment end marker and some
+	fixes in gtk-doc comments.
+
+	* pango/break.c
+	* pango/pango-layout.c
+	* pango/pangoft2.c
+	* docs/pango-sections.txt
+	* docs/tmpl/fonts.sgml
+	* docs/tmpl/x-fonts.sgml: documentation updates.
+
 Sun Oct 14 18:42:56 2001  Manish Singh  <yosh@gimp.org>
 	
 	* pango/pangox.c: add missing comment end marker to make it compile
diff --git a/ChangeLog.pre-1-10 b/ChangeLog.pre-1-10
index d3b2a78f..cab807f7 100644
--- a/ChangeLog.pre-1-10
+++ b/ChangeLog.pre-1-10
@@ -1,3 +1,15 @@
+2001-10-15  Sven Neumann  <sven@gimp.org>
+
+	* pango/pangoxft-font.c: another missing comment end marker and some
+	fixes in gtk-doc comments.
+
+	* pango/break.c
+	* pango/pango-layout.c
+	* pango/pangoft2.c
+	* docs/pango-sections.txt
+	* docs/tmpl/fonts.sgml
+	* docs/tmpl/x-fonts.sgml: documentation updates.
+
 Sun Oct 14 18:42:56 2001  Manish Singh  <yosh@gimp.org>
 	
 	* pango/pangox.c: add missing comment end marker to make it compile
diff --git a/ChangeLog.pre-1-2 b/ChangeLog.pre-1-2
index d3b2a78f..cab807f7 100644
--- a/ChangeLog.pre-1-2
+++ b/ChangeLog.pre-1-2
@@ -1,3 +1,15 @@
+2001-10-15  Sven Neumann  <sven@gimp.org>
+
+	* pango/pangoxft-font.c: another missing comment end marker and some
+	fixes in gtk-doc comments.
+
+	* pango/break.c
+	* pango/pango-layout.c
+	* pango/pangoft2.c
+	* docs/pango-sections.txt
+	* docs/tmpl/fonts.sgml
+	* docs/tmpl/x-fonts.sgml: documentation updates.
+
 Sun Oct 14 18:42:56 2001  Manish Singh  <yosh@gimp.org>
 	
 	* pango/pangox.c: add missing comment end marker to make it compile
diff --git a/ChangeLog.pre-1-4 b/ChangeLog.pre-1-4
index d3b2a78f..cab807f7 100644
--- a/ChangeLog.pre-1-4
+++ b/ChangeLog.pre-1-4
@@ -1,3 +1,15 @@
+2001-10-15  Sven Neumann  <sven@gimp.org>
+
+	* pango/pangoxft-font.c: another missing comment end marker and some
+	fixes in gtk-doc comments.
+
+	* pango/break.c
+	* pango/pango-layout.c
+	* pango/pangoft2.c
+	* docs/pango-sections.txt
+	* docs/tmpl/fonts.sgml
+	* docs/tmpl/x-fonts.sgml: documentation updates.
+
 Sun Oct 14 18:42:56 2001  Manish Singh  <yosh@gimp.org>
 	
 	* pango/pangox.c: add missing comment end marker to make it compile
diff --git a/ChangeLog.pre-1-6 b/ChangeLog.pre-1-6
index d3b2a78f..cab807f7 100644
--- a/ChangeLog.pre-1-6
+++ b/ChangeLog.pre-1-6
@@ -1,3 +1,15 @@
+2001-10-15  Sven Neumann  <sven@gimp.org>
+
+	* pango/pangoxft-font.c: another missing comment end marker and some
+	fixes in gtk-doc comments.
+
+	* pango/break.c
+	* pango/pango-layout.c
+	* pango/pangoft2.c
+	* docs/pango-sections.txt
+	* docs/tmpl/fonts.sgml
+	* docs/tmpl/x-fonts.sgml: documentation updates.
+
 Sun Oct 14 18:42:56 2001  Manish Singh  <yosh@gimp.org>
 	
 	* pango/pangox.c: add missing comment end marker to make it compile
diff --git a/ChangeLog.pre-1-8 b/ChangeLog.pre-1-8
index d3b2a78f..cab807f7 100644
--- a/ChangeLog.pre-1-8
+++ b/ChangeLog.pre-1-8
@@ -1,3 +1,15 @@
+2001-10-15  Sven Neumann  <sven@gimp.org>
+
+	* pango/pangoxft-font.c: another missing comment end marker and some
+	fixes in gtk-doc comments.
+
+	* pango/break.c
+	* pango/pango-layout.c
+	* pango/pangoft2.c
+	* docs/pango-sections.txt
+	* docs/tmpl/fonts.sgml
+	* docs/tmpl/x-fonts.sgml: documentation updates.
+
 Sun Oct 14 18:42:56 2001  Manish Singh  <yosh@gimp.org>
 	
 	* pango/pangox.c: add missing comment end marker to make it compile
diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
index c31fd60d..66836e15 100644
--- a/docs/pango-sections.txt
+++ b/docs/pango-sections.txt
@@ -151,6 +151,7 @@ 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_font_find_shaper
@@ -198,6 +199,7 @@ 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
 
 PANGO_FONT_FACE_CLASS
 PANGO_IS_FONT_CLASS
@@ -503,7 +505,6 @@ pango_win32_render
 pango_win32_render_layout_line
 pango_win32_render_layout
 pango_win32_get_unknown_glyph
-pango_win32_font_get_coverage
 pango_win32_font_get_glyph_index
 PangoWin32FontCache
 pango_win32_font_cache_new
diff --git a/docs/tmpl/fonts.sgml b/docs/tmpl/fonts.sgml
index fd042362..3296324c 100644
--- a/docs/tmpl/fonts.sgml
+++ b/docs/tmpl/fonts.sgml
@@ -447,6 +447,13 @@ within a family.
 @Returns: 
 
 
+<!-- ##### MACRO PANGO_TYPE_FONT_METRICS ##### -->
+<para>
+
+</para>
+
+
+
 <!-- ##### STRUCT PangoFont ##### -->
 <para>
 The #PangoFont structure is used to represent
diff --git a/docs/tmpl/x-fonts.sgml b/docs/tmpl/x-fonts.sgml
index 3ca223ca..1e78bc0f 100644
--- a/docs/tmpl/x-fonts.sgml
+++ b/docs/tmpl/x-fonts.sgml
@@ -140,6 +140,16 @@ glyph index.
 @Returns: 
 
 
+<!-- ##### FUNCTION pango_x_font_get_unknown_glyph ##### -->
+<para>
+
+</para>
+
+@font: 
+@wc: 
+@Returns: 
+
+
 <!-- ##### FUNCTION pango_x_apply_ligatures ##### -->
 <para>
 
diff --git a/pango/break.c b/pango/break.c
index a4377fb4..5aeb397d 100644
--- a/pango/break.c
+++ b/pango/break.c
@@ -364,9 +364,10 @@ typedef enum
 /**
  * pango_default_break:
  * @text: text to break
- * @length: length of text in bytes (or -1 is allowed if text is nul-terminated)
- * @analysis: a #PangoAnalysis for the text
+ * @length: length of text in bytes (may be -1 if @text is nul-terminated)
+ * @analysis: a #PangoAnalysis for the @text
  * @attrs: logical attributes to fill in
+ * @attrs_len: size of the array passed as @attrs
  *
  * This is the default break algorithm, used if no language
  * engine overrides it. Normally you should use pango_break()
@@ -1277,9 +1278,11 @@ pango_default_break (const gchar   *text,
 /**
  * pango_break:
  * @text:      the text to process
- * @length:    the length (in bytes) of @text
- * @analysis:  #PangoAnalysis structure from PangoItemize
+ * @length:    length of @text in bytes (may be -1 if @text is nul-terminated)
+ * @analysis:  #PangoAnalysis structure from pango_itemize()
  * @attrs:     an array to store character information in
+ * @attrs_len: size of the array passed as @attrs
+
  *
  * Determines possible line, word, and character breaks
  * for a string of Unicode text.
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 97b594d7..b82fe902 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -694,7 +694,8 @@ 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
+ * Return value: %TRUE if the layout does not break paragraphs at 
+ * paragraph separator characters
  **/
    
 gboolean
@@ -755,7 +756,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)
@@ -786,7 +787,8 @@ pango_layout_set_markup (PangoLayout *layout,
 /**
  * pango_layout_set_markup_with_accel:
  * @layout: a #PangoLayout
- * @markup: some marked-up text (see <link linkend="PangoMarkupFormat">markup format</link>)
+ * @markup: some marked-up text 
+ * (see <link linkend="PangoMarkupFormat">markup format</link>)
  * @length: length of @markup in bytes
  * @accel_marker: marker for accelerators in the text
  * @accel_char: return location for any located accelerators
@@ -860,7 +862,7 @@ pango_layout_context_changed (PangoLayout *layout)
  *           of characters in the layout.)
  * 
  * Retrieve an array of logical attributes for each character in
- * the layout. 
+ * the @layout. 
  **/
 void
 pango_layout_get_log_attrs (PangoLayout    *layout,
@@ -886,7 +888,7 @@ pango_layout_get_log_attrs (PangoLayout    *layout,
  * pango_layout_get_line_count:
  * @layout: #PangoLayout
  * 
- * Retrieve the count of lines for the #PangoLayout
+ * Retrieve the count of lines for the @layout.
  * 
  * Return value: the line count
  **/
@@ -903,7 +905,7 @@ pango_layout_get_line_count (PangoLayout   *layout)
  * pango_layout_get_lines:
  * @layout: a #PangoLayout
  * 
- * Return the lines of the layout as a list
+ * Return the lines of the @layout as a list.
  * 
  * Return value: a #GSList containing the lines in the layout. This
  * points to internal data of the #PangoLayout and must be used with
@@ -923,7 +925,7 @@ pango_layout_get_lines (PangoLayout *layout)
  * @line: the index of a line, which must be between 0 and
  *        pango_layout_get_line_count(layout) - 1, inclusive.
  * 
- * Retrieves a particular line from a #PangoLayout
+ * Retrieves a particular line from a #PangoLayout.
  * 
  * Return value: the requested #PangoLayoutLine, or %NULL if the
  *               index is out of range. This layout line can
@@ -950,15 +952,14 @@ pango_layout_get_line (PangoLayout *layout,
 
 /**
  * pango_layout_line_index_to_x:
- * @line:         a #PangoLayoutLine
- * @index:        byte offset of a grapheme within the layout
- * @trailing: an integer indicating the edge of the grapheme to retrieve the position
- *            of. If 0, the trailing edge of the grapheme, if > 0, the leading
- *            of the grapheme.
+ * @line:     a #PangoLayoutLine
+ * @index:    byte offset of a grapheme within the layout
+ * @trailing: an integer indicating the edge of the grapheme to retrieve 
+ *            the position of. If 0, the trailing edge of the grapheme, 
+ *            if > 0, the leading of the grapheme.
  * @x_pos: location to store the x_offset (in thousandths of a device unit)
  * 
- * Convert index within a line to X pos
- *
+ * Converts an index within a line to a X position.
  *
  **/
 void
@@ -1117,15 +1118,15 @@ pango_layout_index_to_line_and_extents (PangoLayout     *layout,
  * pango_layout_index_to_line_x:
  * @layout:    a #PangoLayout
  * @index:     the byte index of a grapheme within the layout.
- * @trailing:  an integer indicating the edge of the grapheme to retrieve the position
- *             of. If 0, the trailing edge of the grapheme, if > 0, the leading
- *             of the grapheme.
+ * @trailing:  an integer indicating the edge of the grapheme to retrieve the 
+ *             position of. If 0, the trailing edge of the grapheme, if > 0, 
+ *             the leading of the grapheme.
  * @line:      location to store resulting line index. (which will
  *             between 0 and pango_layout_get_line_count(layout) - 1)
  * @x_pos:     location to store resulting position within line
  *             (in thousandths of a device unit)
  *
- * Converts from byte index within the layout to line and X position.
+ * Converts from byte @index within the @layout to line and X position.
  * (X position is measured from the left edge of the line)
  */
 void
@@ -1876,9 +1877,9 @@ pango_layout_get_extents_internal (PangoLayout    *layout,
 
   pango_layout_check_lines (layout);
 
-  /* When we are not wrapping, we need the overall width of the layout to figure
-   * out the x_offsets of each line. However, we only need the x_offsets if
-   * we are computing the ink_rect or individual line extents.
+  /* When we are not wrapping, we need the overall width of the layout to 
+   * figure out the x_offsets of each line. However, we only need the 
+   * x_offsets if we are computing the ink_rect or individual line extents.
    */
   width = layout->width;
   if (width == -1 && layout->alignment != PANGO_ALIGN_LEFT && (ink_rect || line_extents))
@@ -1984,10 +1985,10 @@ pango_layout_get_extents_internal (PangoLayout    *layout,
  * @layout:   a #PangoLayout
  * @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.
+ * @logical_rect: rectangle used to store the logical extents of the glyph 
+ *            string or %NULL to indicate that the result is not needed.
  * 
- * Compute the logical and ink extents of a layout. See the documentation
+ * Compute the logical and ink extents of @layout. See the documentation
  * for pango_font_get_glyph_extents() for details about the interpretation
  * of the rectangles.
  */
@@ -2006,10 +2007,10 @@ pango_layout_get_extents (PangoLayout    *layout,
  * @layout:   a #PangoLayout
  * @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.
+ * @logical_rect: rectangle used to store the logical extents of the glyph 
+ *            string or %NULL to indicate that the result is not needed.
  * 
- * Compute the logical and ink extents of a layout. See the documentation
+ * Compute the logical and ink extents of @layout. See the documentation
  * for 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_get_extents(), which returns the extents in
diff --git a/pango/pangoft2.c b/pango/pangoft2.c
index 271e0d1e..a831fc42 100644
--- a/pango/pangoft2.c
+++ b/pango/pangoft2.c
@@ -101,6 +101,17 @@ pango_ft2_open_args_describe (PangoFT2OA *oa)
     return g_strdup_printf ("open_args at %p, face_index %ld", oa->open_args, oa->face_index);
 }
 
+/**
+ * pango_ft2_get_face:
+ * @font: a #PangoFont
+ * @subfont_index: the index of a subfont
+ * 
+ * Looks up a subfont in a #PangoFT2Font and returns a pointer to the 
+ * native FreeType2 FT_Face structure. This may be useful if you want
+ * to use FreeType2 functions directly.
+ * 
+ * Return value: a pointer to a #FT_Face structure.
+ **/
 FT_Face
 pango_ft2_get_face (PangoFont      *font,
 		    PangoFT2Subfont subfont_index)
@@ -147,8 +158,9 @@ pango_ft2_get_face (PangoFont      *font,
 /**
  * pango_ft2_get_context:
  * 
- * Retrieves a #PangoContext appropriate for rendering with Pango fonts.
-  * 
+ * Retrieves a #PangoContext appropriate for rendering with the PangoFT2
+ * backend.
+ * 
  * Return value: the new #PangoContext
  **/
 PangoContext *
@@ -282,13 +294,13 @@ pango_ft2_load_font (PangoFontMap  *fontmap,
  
 /**
  * pango_ft2_render:
- * @bitmap:  the FreeType2 bitmap onto which draw the string
+ * @bitmap:  the FreeType2 bitmap onto which to draw the string
  * @font:    the font in which to draw the string
  * @glyphs:  the glyph string to draw
- * @x:       the x position of start of string (in pixels)
- * @y:       the y position of baseline (in pixels)
+ * @x:       the x position of the start of the string (in pixels)
+ * @y:       the y position of the baseline (in pixels)
  *
- * Render a PangoGlyphString onto a FreeType2 bitmap
+ * Renders a PangoGlyphString onto a FreeType2 bitmap.
  **/
 void 
 pango_ft2_render (FT_Bitmap        *bitmap,
@@ -476,6 +488,17 @@ pango_ft2_font_get_glyph_extents (PangoFont      *font,
     *logical_rect = info->logical_rect;
 }
 
+/**
+ * pango_ft2_font_get_kerning:
+ * @font: a #PangoFont
+ * @left: the left #PangoGlyph
+ * @right: the right #PangoGlyph
+ * 
+ * Retrieves kerning information for a combination of two glyphs.
+ * 
+ * Return value: The amount of kerning (in Pango units) to apply for 
+ * the given combination of glyphs.
+ **/
 int
 pango_ft2_font_get_kerning (PangoFont *font,
 			    PangoGlyph left,
@@ -670,11 +693,11 @@ pango_ft2_font_get_metrics (PangoFont        *font,
 
 /**
  * pango_ft2_n_subfonts:
- * @font: a PangoFont
+ * @font: a #PangoFont
  *
- * Returns number of subfonts in a PangoFT2Font.
+ * Returns the number of subfonts in a #PangoFT2Font.
  *
- * Return value: number of subfonts in @font
+ * Return value: the number of subfonts in @font
  **/
 int
 pango_ft2_n_subfonts (PangoFont *font)
@@ -718,7 +741,7 @@ pango_ft2_get_coverage (PangoFont     *font,
 /**
  * pango_ft2_font_subfont_open_args:
  * @font: a #PangoFont which must be from the FT2 backend
- * @subfont_id: the id of a subfont within the font
+ * @subfont_id: the id of a subfont within the @font
  * @open_args: pointer where to store the #FT_Open_Args for this subfont
  * @face_index: pointer where to store the face index for this subfont
  * 
diff --git a/pango/pangoxft-font.c b/pango/pangoxft-font.c
index 9b34251e..05311871 100644
--- a/pango/pangoxft-font.c
+++ b/pango/pangoxft-font.c
@@ -471,11 +471,12 @@ pango_xft_font_find_shaper (PangoFont     *font,
 
 /**
  * pango_xft_font_get_font:
- * @font a Pango font.
+ * @font: a #PangoFont.
  *
  * Returns the XftFont of a font.
  *
  * Returns: the XftFont associated to @font.
+ **/
 XftFont *
 pango_xft_font_get_font (PangoFont *font)
 {
@@ -490,7 +491,7 @@ pango_xft_font_get_font (PangoFont *font)
 
 /**
  * pango_xft_font_get_display:
- * @font a Pango font.
+ * @font: a #PangoFont.
  *
  * Returns the X display of the XftFont of a font.
  *
@@ -531,7 +532,7 @@ pango_xft_font_get_unknown_glyph (PangoFont *font,
 
 /**
  * pango_xft_font_get_face:
- * @font: a Pango font.
+ * @font: a #PangoFont.
  *
  * Gets the FreeType FT_Face associated with a font.
  *
@@ -554,7 +555,7 @@ pango_xft_font_get_face (PangoFont *font)
 
 /**
  * pango_xft_font_get_ot_info:
- * @font: a Pango font.
+ * @font: a #PangoFont.
  *
  * Gets the OpenType info of a font as a #PangoOTInfo.
  *