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.

4 files changed, 58 insertions, 22 deletions

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,