Document PangoOTBuffer and PangoOTGlyph.

2006-01-28  Behdad Esfahbod  <behdad@gnome.org>

        * doc/tmpl/opentype.sgml: Document PangoOTBuffer and PangoOTGlyph.

        * pango/opentype/pango-ot-buffer.c, pango/opentype/pango-ot-info.c,
        pango/opentype/pango-ot-ruleset.c: Document remaining symbols.

12 files changed, 81 insertions, 48 deletions

diff --git a/ChangeLog b/ChangeLog
index dc46406e..4094d013 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2006-01-28  Behdad Esfahbod  <behdad@gnome.org>
 
+	* doc/tmpl/opentype.sgml: Document PangoOTBuffer and PangoOTGlyph.
+
+	* pango/opentype/pango-ot-buffer.c, pango/opentype/pango-ot-info.c,
+	pango/opentype/pango-ot-ruleset.c: Document remaining symbols.
+
+2006-01-28  Behdad Esfahbod  <behdad@gnome.org>
+
 	* pango/pangofc-font.h, pango/pangoft2-render.c, pango/pangowin32.c,
 	pango/pangoxft-render.c, docs/tmpl/xft-fonts.sgml: Documentation
 	improvements.
diff --git a/docs/tmpl/freetype-fonts.sgml b/docs/tmpl/freetype-fonts.sgml
index 9877c200..e39ba6bb 100644
--- a/docs/tmpl/freetype-fonts.sgml
+++ b/docs/tmpl/freetype-fonts.sgml
@@ -91,8 +91,6 @@ Function type for doing final config tweaking on prepared FcPatterns.
 @dpi_x: 
 @dpi_y: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@dpi: 
 
 
 <!-- ##### FUNCTION pango_ft2_render ##### -->
diff --git a/docs/tmpl/glyphs.sgml b/docs/tmpl/glyphs.sgml
index c8fc63c3..8dd63aaf 100644
--- a/docs/tmpl/glyphs.sgml
+++ b/docs/tmpl/glyphs.sgml
@@ -177,8 +177,6 @@ horizontal origin.
 
 @matrix: 
 @new_matrix: 
-<!-- # Unused Parameters # -->
-@new: 
 
 
 <!-- ##### TYPEDEF PangoGlyph ##### -->
diff --git a/docs/tmpl/modules.sgml b/docs/tmpl/modules.sgml
index 2d74a8ad..e552e387 100644
--- a/docs/tmpl/modules.sgml
+++ b/docs/tmpl/modules.sgml
@@ -60,8 +60,6 @@ matches the language tag for this entry's map exactly or just approximately.
 @map: 
 @script: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@wc: 
 
 
 <!-- ##### FUNCTION pango_map_get_engines ##### -->
diff --git a/docs/tmpl/opentype.sgml b/docs/tmpl/opentype.sgml
index 8cfe4405..d62bb3d9 100644
--- a/docs/tmpl/opentype.sgml
+++ b/docs/tmpl/opentype.sgml
@@ -35,21 +35,28 @@ use pango_ot_info_new().
 
 <!-- ##### STRUCT PangoOTBuffer ##### -->
 <para>
-
+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().
 </para>
 
 
 <!-- ##### STRUCT PangoOTGlyph ##### -->
 <para>
-
+The #PangoOTGlyph structure represents a single glyph together with
+information used for OpenType layout processing of the glyph.
+It contains the following fields.
 </para>
 
-@glyph: 
-@properties: 
-@cluster: 
-@component: 
-@ligID: 
-@property_cache: 
+@glyph: the glyph itself.
+@properties: the properties value, identifying which features should be
+	     applied on this glyph.  See pango_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.
+@property_cache: for internal use.
 
 <!-- ##### STRUCT PangoOTRuleset ##### -->
 <para>
@@ -81,8 +88,6 @@ identify the various OpenType tables in the
 
 @face: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@font: 
 
 
 <!-- ##### FUNCTION pango_ot_info_find_script ##### -->
@@ -191,7 +196,7 @@ identify the various OpenType tables in the
 </para>
 
 @buffer: 
-@glyph_index: 
+@glyph: 
 @properties: 
 @cluster: 
 
diff --git a/docs/tmpl/pango-renderer.sgml b/docs/tmpl/pango-renderer.sgml
index f88a679b..2b5dd74c 100644
--- a/docs/tmpl/pango-renderer.sgml
+++ b/docs/tmpl/pango-renderer.sgml
@@ -130,8 +130,6 @@ destinations can be created.
 @y2: 
 @x12: 
 @x22: 
-<!-- # Unused Parameters # -->
-@y1: 
 
 
 <!-- ##### FUNCTION pango_renderer_draw_glyph ##### -->
diff --git a/docs/tmpl/pangocairo.sgml b/docs/tmpl/pangocairo.sgml
index 0c58c923..93172ac4 100644
--- a/docs/tmpl/pangocairo.sgml
+++ b/docs/tmpl/pangocairo.sgml
@@ -168,9 +168,6 @@ int main (int argc, char **argv)
 
 @fontmap: 
 @dpi: 
-<!-- # Unused Parameters # -->
-@dpi_x: 
-@dpi_y: 
 
 
 <!-- ##### FUNCTION pango_cairo_font_map_get_resolution ##### -->
diff --git a/docs/tmpl/pangofc-fontmap.sgml b/docs/tmpl/pangofc-fontmap.sgml
index 34c99b77..68a349f1 100644
--- a/docs/tmpl/pangofc-fontmap.sgml
+++ b/docs/tmpl/pangofc-fontmap.sgml
@@ -78,8 +78,6 @@ Fontconfig-based backend involves deriving from both
 
 @fcfontmap: 
 @Returns: 
-<!-- # Unused Parameters # -->
-@fontmap: 
 
 
 <!-- ##### FUNCTION pango_fc_font_map_shutdown ##### -->
@@ -88,8 +86,6 @@ Fontconfig-based backend involves deriving from both
 </para>
 
 @fcfontmap: 
-<!-- # Unused Parameters # -->
-@fontmap: 
 
 
 <!-- ##### FUNCTION pango_fc_font_map_add_decoder_find_func ##### -->
diff --git a/pango/opentype/pango-ot-buffer.c b/pango/opentype/pango-ot-buffer.c
index 3e1c1688..448024dd 100644
--- a/pango/opentype/pango-ot-buffer.c
+++ b/pango/opentype/pango-ot-buffer.c
@@ -28,6 +28,10 @@
  * pango_ot_buffer_new
  * @font: a #PangoFcFont
  *
+ * Creates a new #PangoOTBuffer for the given OpenType font.
+ *
+ * Return value: the new #PangoOTBuffer
+ *
  * Since: 1.4
  **/ 
 PangoOTBuffer *
@@ -59,6 +63,8 @@ pango_ot_buffer_new (PangoFcFont *font)
  * pango_ot_buffer_destroy
  * @buffer: a #PangoOTBuffer
  *
+ * Destroys a #PangoOTBuffer and free all associated memory.
+ *
  * Since: 1.4
  **/ 
 void
@@ -73,6 +79,8 @@ pango_ot_buffer_destroy (PangoOTBuffer *buffer)
  * pango_ot_buffer_clear
  * @buffer: a #PangoOTBuffer
  *
+ * Empties a #PangoOTBuffer, make it ready to add glyphs to.
+ *
  * Since: 1.4
  **/ 
 void
@@ -85,27 +93,33 @@ pango_ot_buffer_clear (PangoOTBuffer *buffer)
 /**
  * pango_ot_buffer_add_glyph
  * @buffer: a #PangoOTBuffer
- * @glyph_index:
- * @properties:
- * @cluster: 
+ * @glyph: the glyph index to add, like a #PangoGlyph
+ * @properties: the glyph properties
+ * @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().
  *
  * Since: 1.4
  **/ 
 void
 pango_ot_buffer_add_glyph (PangoOTBuffer *buffer,
-			   guint          glyph_index,
+			   guint          glyph,
 			   guint          properties,
 			   guint          cluster)
 {
   otl_buffer_add_glyph (buffer->buffer,
-			glyph_index, properties, cluster);
+			glyph, properties, cluster);
 
 }
 
 /**
  * pango_ot_buffer_set_rtl
  * @buffer: a #PangoOTBuffer
- * @rtl: %TRUE for right-to-left 
+ * @rtl: %TRUE for right-to-left text
+ *
+ * Sets whether glyphs will be rendered right-to-left.  This setting
+ * is needed for proper horizontal positioning of right-to-left scripts.
  *
  * Since: 1.4
  **/ 
@@ -118,7 +132,7 @@ pango_ot_buffer_set_rtl (PangoOTBuffer *buffer,
 }
 
 /**
- * pango_ot_buffer_set_zero_width_marks:
+ * pango_ot_buffer_set_zero_width_marks
  * @buffer: a #PangoOTBuffer
  * @zero_width_marks: %TRUE if characters with a mark class should
  *  be forced to zero width.
@@ -140,8 +154,12 @@ pango_ot_buffer_set_zero_width_marks (PangoOTBuffer     *buffer,
 /**
  * pango_ot_buffer_get_glyphs
  * @buffer: a #PangoOTBuffer
- * @glyph: 
- * @n_glyphs:
+ * @glyphs: location to store the array of glyphs, or %NULL
+ * @n_glyphs: location to store the number of glyphs, or %NULL
+ *
+ * Gets the glyph array contained in a #PangoOTBuffer.  The glyphs are
+ * owned by the buffer and should not be freed, and are only valid as long
+ * as buffer is not modified.
  *
  * Since: 1.4
  **/ 
@@ -252,6 +270,10 @@ apply_gpos_rtl (PangoGlyphString *glyphs,
  * @buffer: a #PangoOTBuffer
  * @glyphs: a #PangoGlyphString
  *
+ * Exports the glyphs in a #PangoOTBuffer into a #PangoGlyphString.  This is
+ * typically used after the OpenType layout processing is over, to convert the
+ * resulting glyphs into a generic Pango glyph string.
+ *
  * Since: 1.4
  **/ 
 void
diff --git a/pango/opentype/pango-ot-info.c b/pango/opentype/pango-ot-info.c
index 1b6a1807..ff3f5bb9 100644
--- a/pango/opentype/pango-ot-info.c
+++ b/pango/opentype/pango-ot-info.c
@@ -108,11 +108,12 @@ pango_ot_info_finalizer (void *object)
 /**
  * pango_ot_info_get:
  * @face: a #FT_Face.
- * @returns: the #PangoOTInfo for @face. This object will
- *   have the same lifetime as FT_Face.
  * 
  * Returns the #PangoOTInfo structure for the given FreeType font.
  *
+ * Return value: the #PangoOTInfo for @face. This object will have
+ * the same lifetime as @face.
+ *
  * Since: 1.2
  **/
 PangoOTInfo *
@@ -399,9 +400,10 @@ get_tables (PangoOTInfo      *info,
  * @table_type: the table type to obtain information about.
  * @script_tag: the tag of the script to find.
  * @script_index: location to store the index of the script, or %NULL.
- * @returns: %TRUE if the script was found.
  * 
  * Finds the index of a script.
+ *
+ * Return value: %TRUE if the script was found.
  **/
 gboolean 
 pango_ot_info_find_script (PangoOTInfo      *info,
@@ -440,9 +442,10 @@ pango_ot_info_find_script (PangoOTInfo      *info,
  * @language_index: location to store the index of the language, or %NULL.
  * @required_feature_index: location to store the required feature index of 
  *    the language, or %NULL.
- * @returns: %TRUE if the language was found.
  * 
  * Finds the index of a language and its required feature index.  
+ *
+ * Return value: %TRUE if the language was found.
  **/
 gboolean
 pango_ot_info_find_language (PangoOTInfo      *info,
@@ -489,9 +492,10 @@ pango_ot_info_find_language (PangoOTInfo      *info,
  * @language_index: the index of the language whose features are searched,
  *     or 0xffff to use the default language of the script.
  * @feature_index: location to store the index of the feature, or %NULL. 
- * @returns: %TRUE if the feature was found.
  * 
  * Finds the index of a feature.
+ *
+ * Return value: %TRUE if the feature was found.
  **/
 gboolean
 pango_ot_info_find_feature  (PangoOTInfo      *info,
@@ -545,10 +549,11 @@ pango_ot_info_find_feature  (PangoOTInfo      *info,
  * pango_ot_info_list_scripts:
  * @info: a #PangoOTInfo.
  * @table_type: the table type to obtain information about.
- * @returns: a newly-allocated array containing the tags of the
- *   available scripts.
  *
  * Obtains the list of available scripts. 
+ *
+ * Return value: a newly-allocated array containing the tags of the
+ *   available scripts.
  **/
 PangoOTTag *
 pango_ot_info_list_scripts (PangoOTInfo      *info,
@@ -579,10 +584,11 @@ pango_ot_info_list_scripts (PangoOTInfo      *info,
  * @table_type: the table type to obtain information about.
  * @script_index: the index of the script to list languages for.
  * @language_tag: unused parameter.
- * @returns: a newly-allocated array containing the tags of the
- *   available languages.
  * 
  * Obtains the list of available languages for a given script.
+ *
+ * Return value: a newly-allocated array containing the tags of the
+ *   available languages.
  **/ 
 PangoOTTag *
 pango_ot_info_list_languages (PangoOTInfo      *info,
@@ -622,10 +628,11 @@ pango_ot_info_list_languages (PangoOTInfo      *info,
  * @script_index: the index of the script to obtain information about. 
  * @language_index: the indes of the language to list features for, or
  *     0xffff, to list features for the default language of the script.
- * @returns: a newly-allocated array containing the tags of the available
- *    features. 
  *
  * Obtains the list of features for the given language of the given script.
+ *
+ * Return value: a newly-allocated array containing the tags of the
+ * available features. 
  **/
 PangoOTTag *
 pango_ot_info_list_features  (PangoOTInfo      *info,
diff --git a/pango/opentype/pango-ot-ruleset.c b/pango/opentype/pango-ot-ruleset.c
index 94e0febd..071cdd61 100644
--- a/pango/opentype/pango-ot-ruleset.c
+++ b/pango/opentype/pango-ot-ruleset.c
@@ -93,9 +93,10 @@ pango_ot_ruleset_finalize (GObject *object)
 /**
  * pango_ot_ruleset_new:
  * @info: a #PangoOTInfo.
- * @returns: a new #PangoOTRuleset.
  *
  * Creates a new #PangoOTRuleset for the given OpenType info.
+ *
+ * Return value: a new #PangoOTRuleset.
  **/
 PangoOTRuleset *
 pango_ot_ruleset_new (PangoOTInfo *info)
@@ -141,6 +142,9 @@ pango_ot_ruleset_add_feature (PangoOTRuleset   *ruleset,
  * @ruleset: a #PangoOTRuleset.
  * @buffer: a #PangoOTBuffer.
  *
+ * Performs the OpenType GSUB substitution on @buffer using the features
+ * in @ruleset
+ *
  * Since: 1.4
  **/
 void
@@ -194,6 +198,9 @@ pango_ot_ruleset_substitute  (PangoOTRuleset   *ruleset,
  * @ruleset: a #PangoOTRuleset.
  * @buffer: a #PangoOTBuffer.
  *
+ * Performs the OpenType GPOS positionoing on @buffer using the features
+ * in @ruleset
+ *
  * Since: 1.4
  **/
 void
diff --git a/pango/pango-ot.h b/pango/pango-ot.h
index 79af9ff9..f6749a5b 100644
--- a/pango/pango-ot.h
+++ b/pango/pango-ot.h
@@ -91,7 +91,7 @@ void           pango_ot_buffer_clear      (PangoOTBuffer     *buffer);
 void           pango_ot_buffer_set_rtl    (PangoOTBuffer     *buffer,
 					   gboolean           rtl);
 void           pango_ot_buffer_add_glyph  (PangoOTBuffer     *buffer,
-					   guint              glyph_index,
+					   guint              glyph,
 					   guint              properties,
 					   guint              cluster);
 void           pango_ot_buffer_get_glyphs (PangoOTBuffer     *buffer,