diff --git a/src/hb-face.cc b/src/hb-face.cc
index 7bde50df5..848c4ff9c 100644
--- a/src/hb-face.cc
+++ b/src/hb-face.cc
@@ -41,8 +41,10 @@
  * @short_description: Font face objects
  * @include: hb.h
  *
- * Font face is objects represent a single face in a font family.
- * More exactly, a font face represents a single face in a binary font file.
+ * A font face is an object that represents a single face from within a
+ * font family.
+ *
+ * More precisely, a font face represents a single face in a binary font file.
  * Font faces are typically built from a binary blob and a face index.
  * Font faces are used to create fonts.
  **/
@@ -52,7 +54,7 @@
  * hb_face_count:
  * @blob: a blob.
  *
- * Get number of faces in a blob.
+ * Fetches the number of faces in a blob.
  *
  * Return value: Number of faces in @blob
  *
@@ -96,13 +98,19 @@ DEFINE_NULL_INSTANCE (hb_face_t) =
 
 /**
  * hb_face_create_for_tables:
- * @reference_table_func: (closure user_data) (destroy destroy) (scope notified):
- * @user_data:
- * @destroy:
+ * @reference_table_func: (closure user_data) (destroy destroy) (scope notified): Table-referencing function
+ * @user_data: A pointer to the user data
+ * @destroy: (optional): A callback to call when @data is not needed anymore
  *
+ * Variant of hb_face_create(), built for those cases where it is more
+ * convenient to provide data for individual tables instead of the whole font
+ * data. With the caveat that hb_face_get_table_tags() does not currently work
+ * with faces created this way.
+ * 
+ * Creates a new face object from the specified @user_data and @reference_table_func,
+ * with the @destroy callback. 
  *
- *
- * Return value: (transfer full)
+ * Return value: (transfer full): The new face object
  *
  * Since: 0.9.2
  **/
@@ -182,12 +190,15 @@ _hb_face_for_data_reference_table (hb_face_t *face HB_UNUSED, hb_tag_t tag, void
 
 /**
  * hb_face_create: (Xconstructor)
- * @blob:
- * @index:
+ * @blob: #hb_blob_t to work upon
+ * @index: The index of the face within @blob
  *
+ * Constructs a new face object from the specified blob and
+ * a face index into that blob. This is used for blobs of
+ * file formats such as Dfont and TTC that can contain more
+ * than one face.
  *
- *
- * Return value: (transfer full):
+ * Return value: (transfer full): The new face object
  *
  * Since: 0.9.2
  **/
@@ -222,9 +233,9 @@ hb_face_create (hb_blob_t    *blob,
 /**
  * hb_face_get_empty:
  *
+ * Fetches the singleton empty face object.
  *
- *
- * Return value: (transfer full)
+ * Return value: (transfer full) The empty face object
  *
  * Since: 0.9.2
  **/
@@ -237,11 +248,11 @@ hb_face_get_empty ()
 
 /**
  * hb_face_reference: (skip)
- * @face: a face.
+ * @face: A face object
  *
+ * Increases the reference count on a face object.
  *
- *
- * Return value:
+ * Return value: The @face object
  *
  * Since: 0.9.2
  **/
@@ -253,9 +264,11 @@ hb_face_reference (hb_face_t *face)
 
 /**
  * hb_face_destroy: (skip)
- * @face: a face.
- *
- *
+ * @face: A face object
+ * 
+ * Decreases the reference count on a face object. When the
+ * reference count reaches zero, the face is destroyed,
+ * freeing all memory.
  *
  * Since: 0.9.2
  **/
@@ -283,15 +296,15 @@ hb_face_destroy (hb_face_t *face)
 
 /**
  * hb_face_set_user_data: (skip)
- * @face: a face.
- * @key:
- * @data:
- * @destroy:
- * @replace:
+ * @face: A face object
+ * @key: The user-data key to set
+ * @data: A pointer to the user data
+ * @destroy: (optional): A callback to call when @data is not needed anymore
+ * @replace: Whether to replace an existing data with the same key
  *
+ * Attaches a user-data key/data pair to the given face object. 
  *
- *
- * Return value:
+ * Return value: %true if success, false otherwise
  *
  * Since: 0.9.2
  **/
@@ -307,12 +320,13 @@ hb_face_set_user_data (hb_face_t          *face,
 
 /**
  * hb_face_get_user_data: (skip)
- * @face: a face.
- * @key:
+ * @face: A face object
+ * @key: The user-data key to query
  *
+ * Fetches the user data associated with the specified key,
+ * attached to the specified face object.
  *
- *
- * Return value: (transfer none):
+ * Return value: (transfer none): A pointer to the user data
  *
  * Since: 0.9.2
  **/
@@ -325,9 +339,9 @@ hb_face_get_user_data (const hb_face_t    *face,
 
 /**
  * hb_face_make_immutable:
- * @face: a face.
- *
+ * @face: A face object
  *
+ * Makes the given face object immutable.
  *
  * Since: 0.9.2
  **/
@@ -342,11 +356,11 @@ hb_face_make_immutable (hb_face_t *face)
 
 /**
  * hb_face_is_immutable:
- * @face: a face.
+ * @face: A face object
  *
+ * Tests whether the given face object is immutable.
  *
- *
- * Return value:
+ * Return value: True is @face is immutable, false otherwise
  *
  * Since: 0.9.2
  **/
@@ -359,12 +373,13 @@ hb_face_is_immutable (const hb_face_t *face)
 
 /**
  * hb_face_reference_table:
- * @face: a face.
- * @tag:
+ * @face: A face object
+ * @tag: The #hb_tag_t of the table to query
  *
+ * Fetches a reference to the specified table within
+ * the specified face.
  *
- *
- * Return value: (transfer full):
+ * Return value: (transfer full): A pointer to the @tag table within @face
  *
  * Since: 0.9.2
  **/
@@ -380,11 +395,13 @@ hb_face_reference_table (const hb_face_t *face,
 
 /**
  * hb_face_reference_blob:
- * @face: a face.
+ * @face: A face object
  *
+ * Fetches a pointer to the binary blob that contains the
+ * specified face. Returns an empty blob if referencing face data is not
+ * possible.
  *
- *
- * Return value: (transfer full):
+ * Return value: (transfer full): A pointer to the blob for @face
  *
  * Since: 0.9.2
  **/
@@ -396,10 +413,13 @@ hb_face_reference_blob (hb_face_t *face)
 
 /**
  * hb_face_set_index:
- * @face: a face.
- * @index:
+ * @face: A face object
+ * @index: The index to assign
  *
+ * Assigns the specified face-index to @face. Fails if the
+ * face is immutable.
  *
+ * <note>Note: face indices within a collection are zero-based.</note>
  *
  * Since: 0.9.2
  **/
@@ -415,11 +435,13 @@ hb_face_set_index (hb_face_t    *face,
 
 /**
  * hb_face_get_index:
- * @face: a face.
+ * @face: A face object
  *
+ * Fetches the face-index corresponding to the given face.
  *
+ * <note>Note: face indices within a collection are zero-based.</note>
  *
- * Return value:
+ * Return value: The index of @face. 
  *
  * Since: 0.9.2
  **/
@@ -431,10 +453,10 @@ hb_face_get_index (const hb_face_t *face)
 
 /**
  * hb_face_set_upem:
- * @face: a face.
- * @upem:
- *
+ * @face: A face object
+ * @upem: The units-per-em value to assign
  *
+ * Sets the units-per-em (upem) for a face object to the specified value.
  *
  * Since: 0.9.2
  **/
@@ -450,11 +472,11 @@ hb_face_set_upem (hb_face_t    *face,
 
 /**
  * hb_face_get_upem:
- * @face: a face.
+ * @face: A face object
  *
+ * Fetches the units-per-em (upem) value of the specified face object.
  *
- *
- * Return value:
+ * Return value: The upem value of @face
  *
  * Since: 0.9.2
  **/
@@ -466,10 +488,10 @@ hb_face_get_upem (const hb_face_t *face)
 
 /**
  * hb_face_set_glyph_count:
- * @face: a face.
- * @glyph_count:
- *
+ * @face: A face object
+ * @glyph_count: The glyph-count value to assign
  *
+ * Sets the glyph count for a face object to the specified value.
  *
  * Since: 0.9.7
  **/
@@ -485,11 +507,11 @@ hb_face_set_glyph_count (hb_face_t    *face,
 
 /**
  * hb_face_get_glyph_count:
- * @face: a face.
+ * @face: A face object
  *
+ * Fetches the glyph-count value of the specified face object.
  *
- *
- * Return value:
+ * Return value: The glyph-count value of @face
  *
  * Since: 0.9.7
  **/
@@ -501,14 +523,16 @@ hb_face_get_glyph_count (const hb_face_t *face)
 
 /**
  * hb_face_get_table_tags:
- * @face: a face.
- * @start_offset: index of first tag to return.
- * @table_count: input length of @table_tags array, output number of items written.
- * @table_tags: array to write tags into.
+ * @face: A face object
+ * @start_offset: The index of first table tag to retrieve
+ * @table_count: (inout): Input = the maximum number of table tags to return;
+ *                Output = the actual number of table tags returned (may be zero)
+ * @table_tags: (out) (array length=table_count): The array of table tags found
  *
- * Retrieves table tags for a face, if possible.
+ * Fetches a list of all table tags for a face, if possible. The list returned will
+ * begin at the offset provided
  *
- * Return value: total number of tables, or 0 if not possible to list.
+ * Return value: Total number of tables, or zero if it is not possible to list
  *
  * Since: 1.6.0
  **/
@@ -542,8 +566,11 @@ hb_face_get_table_tags (const hb_face_t *face,
 #ifndef HB_NO_FACE_COLLECT_UNICODES
 /**
  * hb_face_collect_unicodes:
- * @face: font face.
- * @out: set to add Unicode characters covered by @face to.
+ * @face: A face object
+ * @out: The set to add Unicode characters to
+ *
+ * Collects all of the Unicode characters covered by @face and adds
+ * them to the #hb_set_t set @out.
  *
  * Since: 1.9.0
  */
@@ -555,10 +582,11 @@ hb_face_collect_unicodes (hb_face_t *face,
 }
 /**
  * hb_face_collect_variation_selectors:
- * @face: font face.
- * @out: set to add Variation Selector characters covered by @face to.
- *
+ * @face: A face object
+ * @out: The set to add Variation Selector characters to
  *
+ * Collects all Unicode "Variation Selector" characters covered by @face and adds
+ * them to the #hb_set_t set @out.
  *
  * Since: 1.9.0
  */
@@ -570,10 +598,12 @@ hb_face_collect_variation_selectors (hb_face_t *face,
 }
 /**
  * hb_face_collect_variation_unicodes:
- * @face: font face.
- * @out: set to add Unicode characters for @variation_selector covered by @face to.
- *
+ * @face: A face object
+ * @variation_selector: The Variation Selector to query
+ * @out: The set to add Unicode characters to
  *
+ * Collects all Unicode characters for @variation_selector covered by @face and adds
+ * them to the #hb_set_t set @out.
  *
  * Since: 1.9.0
  */
@@ -708,6 +738,9 @@ hb_face_builder_create ()
 
 /**
  * hb_face_builder_add_table:
+ * @face: A face object created with hb_face_builder_create()
+ * @tag: The #hb_tag_t of the table to add
+ * @blob: The blob containing the table data to add
  *
  * Add table for @tag with data provided by @blob to the face.  @face must
  * be created using hb_face_builder_create().
diff --git a/src/hb-face.h b/src/hb-face.h
index e8ff090d5..3b18f7eef 100644
--- a/src/hb-face.h
+++ b/src/hb-face.h
@@ -46,6 +46,12 @@ hb_face_count (hb_blob_t *blob);
  * hb_face_t
  */
 
+/**
+ * hb_face_t:
+ *
+ * Data type for holding font faces.
+ *
+ **/
 typedef struct hb_face_t hb_face_t;
 
 HB_EXTERN hb_face_t *
diff --git a/src/hb-ot-font.cc b/src/hb-ot-font.cc
index a1dc88603..fae7b5b65 100644
--- a/src/hb-ot-font.cc
+++ b/src/hb-ot-font.cc
@@ -306,6 +306,9 @@ _hb_ot_get_font_funcs ()
 
 /**
  * hb_ot_font_set_funcs:
+ * @font: #hb_font_t to work upon
+ *
+ * Sets the font functions to use when working with @font. 
  *
  * Since: 0.9.28
  **/
diff --git a/src/hb-ot-layout.cc b/src/hb-ot-layout.cc
index 46408bb9d..7918f86dd 100644
--- a/src/hb-ot-layout.cc
+++ b/src/hb-ot-layout.cc
@@ -76,7 +76,7 @@
  * Tests whether a face includes any kerning data in the 'kern' table.
  * Does NOT test for kerning lookups in the GPOS table.
  *
- * Return value: true if data found, false otherwise
+ * Return value: %true if data found, false otherwise
  *
  **/
 bool
@@ -92,7 +92,7 @@ hb_ot_layout_has_kerning (hb_face_t *face)
  * Tests whether a face includes any state-machine kerning in the 'kern' table.
  * Does NOT examine the GPOS table.
  *
- * Return value: true if data found, false otherwise
+ * Return value: %true if data found, false otherwise
  *
  **/
 bool
@@ -112,7 +112,7 @@ hb_ot_layout_has_machine_kerning (hb_face_t *face)
  *
  * Does NOT examine the GPOS table.
  *
- * Return value: true is data found, false otherwise
+ * Return value: %true is data found, false otherwise
  *
  **/
 bool
@@ -268,7 +268,7 @@ _hb_ot_layout_set_glyph_props (hb_font_t *font,
  *
  * Tests whether a face has any glyph classes defined in its GDEF table.
  *
- * Return value: true if data found, false otherwise
+ * Return value: %true if data found, false otherwise
  *
  **/
 hb_bool_t
@@ -444,7 +444,7 @@ hb_ot_layout_table_get_script_tags (hb_face_t    *face,
  * Fetches the index if a given script tag in the specified face's GSUB table
  * or GPOS table.
  *
- * Return value: true if the script is found, false otherwise
+ * Return value: %true if the script is found, false otherwise
  *
  **/
 hb_bool_t
@@ -598,7 +598,7 @@ hb_ot_layout_table_get_feature_tags (hb_face_t    *face,
  * Fetches the index for a given feature tag in the specified face's GSUB table
  * or GPOS table.
  *
- * Return value: true if the feature is found, false otherwise
+ * Return value: %true if the feature is found, false otherwise
  **/
 bool
 hb_ot_layout_table_find_feature (hb_face_t    *face,
@@ -663,7 +663,7 @@ hb_ot_layout_script_get_language_tags (hb_face_t    *face,
  * Fetches the index of a given language tag in the specified face's GSUB table
  * or GPOS table, underneath the specified script tag.
  *
- * Return value: true if the language tag is found, false otherwise
+ * Return value: %true if the language tag is found, false otherwise
  *
  * Since: ??
  * Deprecated: ??
@@ -697,7 +697,7 @@ hb_ot_layout_script_find_language (hb_face_t    *face,
  * Fetches the index of a given language tag in the specified face's GSUB table
  * or GPOS table, underneath the specified script index.
  *
- * Return value: true if the language tag is found, false otherwise
+ * Return value: %true if the language tag is found, false otherwise
  *
  * Since: 2.0.0
  **/
@@ -739,7 +739,7 @@ hb_ot_layout_script_select_language (hb_face_t      *face,
  * Fetches the index of a requested feature in the given face's GSUB or GPOS table,
  * underneath the specified script and language.
  *
- * Return value: true if the feature is found, false otherwise
+ * Return value: %true if the feature is found, false otherwise
  *
  **/
 hb_bool_t
@@ -770,7 +770,7 @@ hb_ot_layout_language_get_required_feature_index (hb_face_t    *face,
  * Fetches the tag of a requested feature index in the given face's GSUB or GPOS table,
  * underneath the specified script and language.
  *
- * Return value: true if the feature is found, false otherwise
+ * Return value: %true if the feature is found, false otherwise
  *
  * Since: 0.9.30
  **/
@@ -877,7 +877,7 @@ hb_ot_layout_language_get_feature_tags (hb_face_t    *face,
  * Fetches the index of a given feature tag in the specified face's GSUB table
  * or GPOS table, underneath the specified script and language.
  *
- * Return value: true if the feature is found, false otherwise
+ * Return value: %true if the feature is found, false otherwise
  *
  **/
 hb_bool_t
@@ -1196,7 +1196,7 @@ hb_ot_layout_collect_lookups (hb_face_t      *face,
  * @glyphs_before: (out): Array of glyphs preceding the substitution range
  * @glyphs_input: (out): Array of input glyphs that would be substituted by the lookup
  * @glyphs_after: (out): Array of glyphs following the substitution range
- * @glyphs_output: (out): Array of glyphs that would be the substitued output of the lookup
+ * @glyphs_output: (out): Array of glyphs that would be the substituted output of the lookup
  *
  * Fetches a list of all glyphs affected by the specified lookup in the
  * specified face's GSUB table or GPOS table.
@@ -1245,7 +1245,7 @@ hb_ot_layout_lookup_collect_glyphs (hb_face_t    *face,
  * @face: #hb_face_t to work upon
  * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS
  * @coords: The variation coordinates to query
- * @num_coords: The number of variation coorinates
+ * @num_coords: The number of variation coordinates
  * @variations_index: (out): The array of feature variations found for the query
  *
  * Fetches a list of feature variations in the specified face's GSUB table
@@ -1310,7 +1310,7 @@ hb_ot_layout_feature_with_variations_get_lookups (hb_face_t    *face,
  *
  * Tests whether the specified face includes any GSUB substitutions.
  *
- * Return value: true if data found, false otherwise
+ * Return value: %true if data found, false otherwise
  *
  **/
 hb_bool_t
@@ -1331,7 +1331,7 @@ hb_ot_layout_has_substitution (hb_face_t *face)
  * Tests whether a specified lookup in the specified face would
  * trigger a substitution on the given glyph sequence.
  *
- * Return value: true if a substitution would be triggered, false otherwise
+ * Return value: %true if a substitution would be triggered, false otherwise
  *
  * Since: 0.9.7
  **/
@@ -1488,7 +1488,7 @@ hb_ot_layout_lookups_substitute_closure (hb_face_t      *face,
  * hb_ot_layout_has_positioning:
  * @face: #hb_face_t to work upon
  *
- * Return value: true if the face has GPOS data, false otherwise
+ * Return value: %true if the face has GPOS data, false otherwise
  *
  **/
 hb_bool_t
@@ -1561,7 +1561,7 @@ hb_ot_layout_position_finish_offsets (hb_font_t *font, hb_buffer_t *buffer)
  * For more information on this distinction, see the [`size` feature documentation](
  * https://docs.microsoft.com/en-us/typography/opentype/spec/features_pt#tag-size).
  *
- * Return value: true if data found, false otherwise
+ * Return value: %true if data found, false otherwise
  *
  * Since: 0.9.10
  **/
@@ -1625,7 +1625,7 @@ hb_ot_layout_get_size_params (hb_face_t       *face,
  * Fetches name indices from feature parameters for "Stylistic Set" ('ssXX') or
  * "Character Variant" ('cvXX') features.
  *
- * Return value: true if data found, false otherwise
+ * Return value: %true if data found, false otherwise
  *
  * Since: 2.0.0
  **/
diff --git a/src/hb-ot-shape.cc b/src/hb-ot-shape.cc
index fe0444987..010a6f2c8 100644
--- a/src/hb-ot-shape.cc
+++ b/src/hb-ot-shape.cc
@@ -1155,6 +1155,12 @@ _hb_ot_shape (hb_shape_plan_t    *shape_plan,
 
 /**
  * hb_ot_shape_plan_collect_lookups:
+ * @shape_plan: #hb_shape_plan_t to query
+ * @table_tag: GSUB or GPOS
+ * @lookup_indexes: (out): The #hb_set_t set of lookups returned
+ *
+ * Computes the complete set of GSUB or GPOS lookups that are applicable
+ * under a given @shape_plan. 
  *
  * Since: 0.9.7
  **/
@@ -1189,6 +1195,15 @@ add_char (hb_font_t          *font,
 
 /**
  * hb_ot_shape_glyphs_closure:
+ * @font: #hb_font_t to work upon
+ * @buffer: The input buffer to compute from
+ * @features: (array length=num_features): The features enabled on the buffer
+ * @num_features: The number of features enabled on the buffer
+ * @glyphs: (out): The #hb_set_t set of glyphs comprising the transitive closure of the query
+ *
+ * Computes the transitive closure of glyphs needed for a specified
+ * input buffer under the given font and feature list. The closure is
+ * computed as a set, not as a list.
  *
  * Since: 0.9.2
  **/
diff --git a/src/hb-shape-plan.cc b/src/hb-shape-plan.cc
index a5a101d0f..2e03003dd 100644
--- a/src/hb-shape-plan.cc
+++ b/src/hb-shape-plan.cc
@@ -37,10 +37,17 @@
  * @short_description: Object representing a shaping plan
  * @include: hb.h
  *
- * Shape plans are not used for shaping directly, but can be access to query
- * certain information about how shaping will perform given a set of input
- * parameters (script, language, direction, features, etc.)
- * Most client would not need to deal with shape plans directly.
+ * Shape plans are an internal mechanism. Each plan contains state
+ * describing how HarfBuzz will shape a particular text segment, based on
+ * the combination of segment properties and the capabilities in the
+ * font face in use.
+ *
+ * Shape plans are not used for shaping directly, but can be queried to
+ * access certain information about how shaping will perform, given a set
+ * of specific input parameters (script, language, direction, features,
+ * etc.).
+ *
+ * Most client programs will not need to deal with shape plans directly.
  **/
 
 
@@ -164,15 +171,16 @@ hb_shape_plan_key_t::equal (const hb_shape_plan_key_t *other)
 
 /**
  * hb_shape_plan_create: (Xconstructor)
- * @face:
- * @props:
- * @user_features: (array length=num_user_features):
- * @num_user_features:
- * @shaper_list: (array zero-terminated=1):
+ * @face: #hb_face_t to use
+ * @props: The #hb_segment_properties_t of the segment
+ * @user_features: (array length=num_user_features): The list of user-selected features
+ * @num_user_features: The number of user-selected features
+ * @shaper_list: (array zero-terminated=1): List of shapers to try
  *
+ * Constructs a shaping plan for a combination of @face, @user_features, @props,
+ * and @shaper_list.
  *
- *
- * Return value: (transfer full):
+ * Return value: (transfer full): The shaping plan
  *
  * Since: 0.9.7
  **/
@@ -189,6 +197,24 @@ hb_shape_plan_create (hb_face_t                     *face,
 				shaper_list);
 }
 
+/**
+ * hb_shape_plan_create2: (Xconstructor)
+ * @face: #hb_face_t to use
+ * @props: The #hb_segment_properties_t of the segment
+ * @user_features: (array length=num_user_features): The list of user-selected features
+ * @num_user_features: The number of user-selected features
+ * @coords: (array length=num_coords): The list of variation-space coordinates
+ * @num_coords: The number of variation-space coordinates
+ * @shaper_list: (array zero-terminated=1): List of shapers to try
+ *
+ * The variable-font version of #hb_shape_plan_create. 
+ * Constructs a shaping plan for a combination of @face, @user_features, @props,
+ * and @shaper_list, plus the variation-space coordinates @coords.
+ *
+ * Return value: (transfer full): The shaping plan
+ *
+ * Since: 1.4.0
+ **/
 hb_shape_plan_t *
 hb_shape_plan_create2 (hb_face_t                     *face,
 		       const hb_segment_properties_t *props,
@@ -248,9 +274,9 @@ bail:
 /**
  * hb_shape_plan_get_empty:
  *
+ * Fetches the singleton empty shaping plan.
  *
- *
- * Return value: (transfer full):
+ * Return value: (transfer full): The empty shaping plan
  *
  * Since: 0.9.7
  **/
@@ -262,11 +288,11 @@ hb_shape_plan_get_empty ()
 
 /**
  * hb_shape_plan_reference: (skip)
- * @shape_plan: a shape plan.
+ * @shape_plan: A shaping plan
  *
+ * Increases the reference count on the given shaping plan.
  *
- *
- * Return value: (transfer full):
+ * Return value: (transfer full): @shape_plan
  *
  * Since: 0.9.7
  **/
@@ -278,9 +304,11 @@ hb_shape_plan_reference (hb_shape_plan_t *shape_plan)
 
 /**
  * hb_shape_plan_destroy: (skip)
- * @shape_plan: a shape plan.
- *
+ * @shape_plan: A shaping plan
  *
+ * Decreases the reference count on the given shaping plan. When the
+ * reference count reaches zero, the shaping plan is destroyed,
+ * freeing all memory.
  *
  * Since: 0.9.7
  **/
@@ -298,13 +326,13 @@ hb_shape_plan_destroy (hb_shape_plan_t *shape_plan)
 
 /**
  * hb_shape_plan_set_user_data: (skip)
- * @shape_plan: a shape plan.
- * @key:
- * @data:
- * @destroy:
- * @replace:
- *
+ * @shape_plan: A shaping plan
+ * @key: The user-data key to set
+ * @data: A pointer to the user data
+ * @destroy: A callback to call when @data is not needed anymore
+ * @replace: Whether to replace an existing data with the same key
  *
+ * Attaches a user-data key/data pair to the given shaping plan. 
  *
  * Return value:
  *
@@ -322,12 +350,13 @@ hb_shape_plan_set_user_data (hb_shape_plan_t    *shape_plan,
 
 /**
  * hb_shape_plan_get_user_data: (skip)
- * @shape_plan: a shape plan.
- * @key:
+ * @shape_plan: A shaping plan
+ * @key: The user-data key to query
  *
+ * Fetches the user data associated with the specified key, 
+ * attached to the specified shaping plan.
  *
- *
- * Return value: (transfer none):
+ * Return value: (transfer none): A pointer to the user data
  *
  * Since: 0.9.7
  **/
@@ -340,11 +369,11 @@ hb_shape_plan_get_user_data (hb_shape_plan_t    *shape_plan,
 
 /**
  * hb_shape_plan_get_shaper:
- * @shape_plan: a shape plan.
+ * @shape_plan: A shaping plan
  *
+ * Fetches the shaper from a given shaping plan.
  *
- *
- * Return value: (transfer none):
+ * Return value: (transfer none): The shaper
  *
  * Since: 0.9.7
  **/
@@ -400,15 +429,16 @@ _hb_shape_plan_execute_internal (hb_shape_plan_t    *shape_plan,
 }
 /**
  * hb_shape_plan_execute:
- * @shape_plan: a shape plan.
- * @font: a font.
- * @buffer: a buffer.
- * @features: (array length=num_features):
- * @num_features:
+ * @shape_plan: A shaping plan
+ * @font: The #hb_font_t to use
+ * @buffer: The #hb_buffer_t to work upon
+ * @features: (array length=num_features): Features to enable
+ * @num_features: The number of features to enable
  *
+ * Executes the given shaping plan on the specified buffer, using
+ * the given @font and @features.
  *
- *
- * Return value:
+ * Return value: 
  *
  * Since: 0.9.7
  **/
@@ -435,15 +465,16 @@ hb_shape_plan_execute (hb_shape_plan_t    *shape_plan,
 
 /**
  * hb_shape_plan_create_cached:
- * @face:
- * @props:
- * @user_features: (array length=num_user_features):
- * @num_user_features:
- * @shaper_list: (array zero-terminated=1):
+ * @face: #hb_face_t to use
+ * @props: The #hb_segment_properties_t of the segment
+ * @user_features: (array length=num_user_features): The list of user-selected features
+ * @num_user_features: The number of user-selected features
+ * @shaper_list: (array zero-terminated=1): List of shapers to try
  *
+ * Creates a cached shaping plan suitable for reuse, for a combination
+ * of @face, @user_features, @props, and @shaper_list.
  *
- *
- * Return value: (transfer full):
+ * Return value: (transfer full): The shaping plan
  *
  * Since: 0.9.7
  **/
@@ -460,6 +491,25 @@ hb_shape_plan_create_cached (hb_face_t                     *face,
 				       shaper_list);
 }
 
+/**
+ * hb_shape_plan_create_cached2:
+ * @face: #hb_face_t to use
+ * @props: The #hb_segment_properties_t of the segment
+ * @user_features: (array length=num_user_features): The list of user-selected features
+ * @num_user_features: The number of user-selected features
+ * @coords: (array length=num_coords): The list of variation-space coordinates
+ * @num_coords: The number of variation-space coordinates
+ * @shaper_list: (array zero-terminated=1): List of shapers to try
+ *
+ * The variable-font version of #hb_shape_plan_create_cached. 
+ * Creates a cached shaping plan suitable for reuse, for a combination
+ * of @face, @user_features, @props, and @shaper_list, plus the
+ * variation-space coordinates @coords.
+ *
+ * Return value: (transfer full): The shaping plan
+ *
+ * Since: 1.4.0
+ **/
 hb_shape_plan_t *
 hb_shape_plan_create_cached2 (hb_face_t                     *face,
 			      const hb_segment_properties_t *props,
diff --git a/src/hb-shape-plan.h b/src/hb-shape-plan.h
index b62ae7ca3..336524ee2 100644
--- a/src/hb-shape-plan.h
+++ b/src/hb-shape-plan.h
@@ -36,6 +36,20 @@
 
 HB_BEGIN_DECLS
 
+/**
+ * hb_shape_plan_t:
+ *
+ * Data type for holding a shaping plan. 
+ *
+ * Shape plans contain information about how HarfBuzz will shape a
+ * particular text segment, based on the segment's properties and the
+ * capabilities in the font face in use.
+ *
+ * Shape plans can be queried about how shaping will perform, given a set
+ * of specific input parameters (script, language, direction, features,
+ * etc.).
+ *
+ **/
 typedef struct hb_shape_plan_t hb_shape_plan_t;
 
 HB_EXTERN hb_shape_plan_t *
diff --git a/src/hb-unicode.cc b/src/hb-unicode.cc
index 36070a7f1..71de71549 100644
--- a/src/hb-unicode.cc
+++ b/src/hb-unicode.cc
@@ -40,11 +40,16 @@
  * @include: hb.h
  *
  * Unicode functions are used to access Unicode character properties.
- * Client can pass its own Unicode functions to HarfBuzz, or access
- * the built-in Unicode functions that come with HarfBuzz.
+ * With these functions, client programs can query various properties from
+ * the Unicode Character Database for any code point, such as General
+ * Category (gc), Script (sc), Canonical Combining Class (ccc), etc.
  *
- * With the Unicode functions, one can query variour Unicode character
- * properties, such as General Category, Script, Combining Class, etc.
+ * Client programs can optionally pass in their own Unicode functions
+ * that implement the same queries. The set of functions available is
+ * defined by the virtual methods in #hb_unicode_funcs_t.
+ *
+ * HarfBuzz provides built-in default functions for each method in
+ * #hb_unicode_funcs_t.
  **/
 
 
@@ -133,6 +138,16 @@ hb_unicode_decompose_compatibility_nil (hb_unicode_funcs_t *ufuncs     HB_UNUSED
 #include "hb-icu.h"
 #endif
 
+/**
+ * hb_unicode_funcs_get_default:
+ *
+ * Fetches a pointer to the default Unicode-functions structure that is used
+ * when no functions are explicitly set on #hb_buffer_t.
+ *
+ * Return value: (transfer none): a pointer to the #hb_unicode_funcs_t Unicode-functions structure
+ *
+ * Since: 0.9.2
+ **/
 hb_unicode_funcs_t *
 hb_unicode_funcs_get_default ()
 {
@@ -155,11 +170,11 @@ hb_unicode_funcs_get_default ()
 
 /**
  * hb_unicode_funcs_create: (Xconstructor)
- * @parent: (nullable):
+ * @parent: (nullable): Parent Unicode-functions structure
  *
+ * Creates a new #hb_unicode_funcs_t structure of Unicode functions.
  *
- *
- * Return value: (transfer full):
+ * Return value: (transfer full): The Unicode-functions structure
  *
  * Since: 0.9.2
  **/
@@ -203,9 +218,9 @@ DEFINE_NULL_INSTANCE (hb_unicode_funcs_t) =
 /**
  * hb_unicode_funcs_get_empty:
  *
+ * Fetches the singleton empty Unicode-functions structure.
  *
- *
- * Return value: (transfer full):
+ * Return value: (transfer full): The empty Unicode-functions structure
  *
  * Since: 0.9.2
  **/
@@ -217,11 +232,11 @@ hb_unicode_funcs_get_empty ()
 
 /**
  * hb_unicode_funcs_reference: (skip)
- * @ufuncs: Unicode functions.
+ * @ufuncs: The Unicode-functions structure
  *
+ * Increases the reference count on a Unicode-functions structure.
  *
- *
- * Return value: (transfer full):
+ * Return value: (transfer full): The Unicode-functions structure
  *
  * Since: 0.9.2
  **/
@@ -233,9 +248,11 @@ hb_unicode_funcs_reference (hb_unicode_funcs_t *ufuncs)
 
 /**
  * hb_unicode_funcs_destroy: (skip)
- * @ufuncs: Unicode functions.
- *
+ * @ufuncs: The Unicode-functions structure
  *
+ * Decreases the reference count on a Unicode-functions structure. When
+ * the reference count reaches zero, the Unicode-functions structure is
+ * destroyed, freeing all memory.
  *
  * Since: 0.9.2
  **/
@@ -256,15 +273,15 @@ hb_unicode_funcs_destroy (hb_unicode_funcs_t *ufuncs)
 
 /**
  * hb_unicode_funcs_set_user_data: (skip)
- * @ufuncs: Unicode functions.
- * @key:
- * @data:
- * @destroy:
- * @replace:
+ * @ufuncs: The Unicode-functions structure
+ * @key: The user-data key
+ * @data: A pointer to the user data
+ * @destroy: A callback to call when @data is not needed anymore
+ * @replace: Whether to replace an existing data with the same key
  *
+ * Attaches a user-data key/data pair to the specified Unicode-functions structure. 
  *
- *
- * Return value:
+ * Return value: %true if success, false otherwise
  *
  * Since: 0.9.2
  **/
@@ -280,12 +297,13 @@ hb_unicode_funcs_set_user_data (hb_unicode_funcs_t *ufuncs,
 
 /**
  * hb_unicode_funcs_get_user_data: (skip)
- * @ufuncs: Unicode functions.
- * @key:
+ * @ufuncs: The Unicode-functions structure
+ * @key: The user-data key to query
  *
+ * Fetches the user-data associated with the specified key,
+ * attached to the specified Unicode-functions structure.
  *
- *
- * Return value: (transfer none):
+ * Return value: (transfer none): A pointer to the user data
  *
  * Since: 0.9.2
  **/
@@ -299,9 +317,10 @@ hb_unicode_funcs_get_user_data (hb_unicode_funcs_t *ufuncs,
 
 /**
  * hb_unicode_funcs_make_immutable:
- * @ufuncs: Unicode functions.
- *
+ * @ufuncs: The Unicode-functions structure
  *
+ * Makes the specified Unicode-functions structure
+ * immutable.
  *
  * Since: 0.9.2
  **/
@@ -316,11 +335,12 @@ hb_unicode_funcs_make_immutable (hb_unicode_funcs_t *ufuncs)
 
 /**
  * hb_unicode_funcs_is_immutable:
- * @ufuncs: Unicode functions.
+ * @ufuncs: The Unicode-functions structure
  *
+ * Tests whether the specified Unicode-functions structure
+ * is immutable.
  *
- *
- * Return value:
+ * Return value: %true if @ufuncs is immutable, false otherwise
  *
  * Since: 0.9.2
  **/
@@ -332,11 +352,12 @@ hb_unicode_funcs_is_immutable (hb_unicode_funcs_t *ufuncs)
 
 /**
  * hb_unicode_funcs_get_parent:
- * @ufuncs: Unicode functions.
+ * @ufuncs: The Unicode-functions structure
  *
+ * Fetches the parent of the Unicode-functions structure
+ * @ufuncs.
  *
- *
- * Return value:
+ * Return value: The parent Unicode-functions structure
  *
  * Since: 0.9.2
  **/
@@ -389,14 +410,18 @@ HB_UNICODE_FUNCS_IMPLEMENT_CALLBACKS_SIMPLE
 
 /**
  * hb_unicode_compose:
- * @ufuncs: Unicode functions.
- * @a:
- * @b:
- * @ab: (out):
+ * @ufuncs: The Unicode-functions structure
+ * @a: The first Unicode code point to compose
+ * @b: The second Unicode code point to compose
+ * @ab: (out): The composition of @a, @b
  *
+ * Fetches the composition of a sequence of two Unicode
+ * code points.
  *
+ * Calls the composition function of the specified
+ * Unicode-functions structure @ufuncs.
  *
- * Return value:
+ * Return value: %true if @a and @b composed, false otherwise
  *
  * Since: 0.9.2
  **/
@@ -411,14 +436,17 @@ hb_unicode_compose (hb_unicode_funcs_t *ufuncs,
 
 /**
  * hb_unicode_decompose:
- * @ufuncs: Unicode functions.
- * @ab:
- * @a: (out):
- * @b: (out):
+ * @ufuncs: The Unicode-functions structure
+ * @ab: Unicode code point to decompose
+ * @a: (out): The first code point of the decomposition of @ab
+ * @b: (out): The second code point of the decomposition of @ab
  *
+ * Fetches the decomposition of a Unicode code point. 
  *
+ * Calls the decomposition function of the specified
+ * Unicode-functions structure @ufuncs.
  *
- * Return value:
+ * Return value: %true if @ab was decomposed, false otherwise
  *
  * Since: 0.9.2
  **/
@@ -434,11 +462,12 @@ hb_unicode_decompose (hb_unicode_funcs_t *ufuncs,
 #ifndef HB_DISABLE_DEPRECATED
 /**
  * hb_unicode_decompose_compatibility:
- * @ufuncs: Unicode functions.
- * @u:
- * @decomposed: (out):
- *
+ * @ufuncs: The Unicode-functions structure
+ * @u: Code point to decompose
+ * @decomposed: (out): Compatibility decomposition of @u
  *
+ * Fetches the compatibility decomposition of a Unicode
+ * code point. Deprecated.
  *
  * Return value:
  *
diff --git a/src/hb-unicode.h b/src/hb-unicode.h
index 61b1b0ba1..2353f0fbf 100644
--- a/src/hb-unicode.h
+++ b/src/hb-unicode.h
@@ -48,7 +48,42 @@ HB_BEGIN_DECLS
 #define HB_UNICODE_MAX 0x10FFFFu
 
 
-/* hb_unicode_general_category_t */
+/**
+ * hb_unicode_general_category_t:
+ * @HB_UNICODE_GENERAL_CATEGORY_CONTROL:              (Cc)
+ * @HB_UNICODE_GENERAL_CATEGORY_FORMAT:		      (Cf)
+ * @HB_UNICODE_GENERAL_CATEGORY_UNASSIGNED:	      (Cn)
+ * @HB_UNICODE_GENERAL_CATEGORY_PRIVATE_USE:	      (Co)
+ * @HB_UNICODE_GENERAL_CATEGORY_SURROGATE:	      (Cs)
+ * @HB_UNICODE_GENERAL_CATEGORY_LOWERCASE_LETTER:     (Ll)
+ * @HB_UNICODE_GENERAL_CATEGORY_MODIFIER_LETTER:      (Lm)
+ * @HB_UNICODE_GENERAL_CATEGORY_OTHER_LETTER:	      (Lo)
+ * @HB_UNICODE_GENERAL_CATEGORY_TITLECASE_LETTER:     (Lt)
+ * @HB_UNICODE_GENERAL_CATEGORY_UPPERCASE_LETTER:     (Lu)
+ * @HB_UNICODE_GENERAL_CATEGORY_SPACING_MARK:	      (Mc)
+ * @HB_UNICODE_GENERAL_CATEGORY_ENCLOSING_MARK:	      (Me)
+ * @HB_UNICODE_GENERAL_CATEGORY_NON_SPACING_MARK:     (Mn)
+ * @HB_UNICODE_GENERAL_CATEGORY_DECIMAL_NUMBER:	      (Nd)
+ * @HB_UNICODE_GENERAL_CATEGORY_LETTER_NUMBER:	      (Nl)
+ * @HB_UNICODE_GENERAL_CATEGORY_OTHER_NUMBER:	      (No)
+ * @HB_UNICODE_GENERAL_CATEGORY_CONNECT_PUNCTUATION:  (Pc)
+ * @HB_UNICODE_GENERAL_CATEGORY_DASH_PUNCTUATION:     (Pd)
+ * @HB_UNICODE_GENERAL_CATEGORY_CLOSE_PUNCTUATION:    (Pe)
+ * @HB_UNICODE_GENERAL_CATEGORY_FINAL_PUNCTUATION:    (Pf)
+ * @HB_UNICODE_GENERAL_CATEGORY_INITIAL_PUNCTUATION:  (Pi)
+ * @HB_UNICODE_GENERAL_CATEGORY_OTHER_PUNCTUATION:    (Po)
+ * @HB_UNICODE_GENERAL_CATEGORY_OPEN_PUNCTUATION:     (Ps)
+ * @HB_UNICODE_GENERAL_CATEGORY_CURRENCY_SYMBOL:      (Sc)
+ * @HB_UNICODE_GENERAL_CATEGORY_MODIFIER_SYMBOL:      (Sk)
+ * @HB_UNICODE_GENERAL_CATEGORY_MATH_SYMBOL:	      (Sm)
+ * @HB_UNICODE_GENERAL_CATEGORY_OTHER_SYMBOL:	      (So)
+ * @HB_UNICODE_GENERAL_CATEGORY_LINE_SEPARATOR:	      (Zl)
+ * @HB_UNICODE_GENERAL_CATEGORY_PARAGRAPH_SEPARATOR:  (Zp)
+ * @HB_UNICODE_GENERAL_CATEGORY_SPACE_SEPARATOR:      (Zs)
+ *
+ * Data type for the "General_Category" (gc) property from
+ * the Unicode Character Database.
+ **/
 
 /* Unicode Character Database property: General_Category (gc) */
 typedef enum
@@ -85,13 +120,72 @@ typedef enum
   HB_UNICODE_GENERAL_CATEGORY_SPACE_SEPARATOR		/* Zs */
 } hb_unicode_general_category_t;
 
-/* hb_unicode_combining_class_t */
-
-/* Note: newer versions of Unicode may add new values.  Clients should be ready to handle
- * any value in the 0..254 range being returned from hb_unicode_combining_class().
- */
-
-/* Unicode Character Database property: Canonical_Combining_Class (ccc) */
+/**
+ * hb_unicode_combining_class_t:
+ * @HB_UNICODE_COMBINING_CLASS_NOT_REORDERED
+ * @HB_UNICODE_COMBINING_CLASS_OVERLAY
+ * @HB_UNICODE_COMBINING_CLASS_NUKTA
+ * @HB_UNICODE_COMBINING_CLASS_KANA_VOICING
+ * @HB_UNICODE_COMBINING_CLASS_VIRAMA
+ * @HB_UNICODE_COMBINING_CLASS_CCC11: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC12: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC13: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC14: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC15: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC16: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC17: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC18: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC19: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC20: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC21: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC22: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC23: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC24: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC25: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC26: (Hebrew)
+ * @HB_UNICODE_COMBINING_CLASS_CCC28: (Arabic)
+ * @HB_UNICODE_COMBINING_CLASS_CCC29: (Arabic)
+ * @HB_UNICODE_COMBINING_CLASS_CCC30: (Arabic)
+ * @HB_UNICODE_COMBINING_CLASS_CCC31: (Arabic)
+ * @HB_UNICODE_COMBINING_CLASS_CCC32: (Arabic)
+ * @HB_UNICODE_COMBINING_CLASS_CCC33: (Arabic)
+ * @HB_UNICODE_COMBINING_CLASS_CCC34: (Arabic)
+ * @HB_UNICODE_COMBINING_CLASS_CCC35: (Arabic)
+ * @HB_UNICODE_COMBINING_CLASS_CCC36: (Syriac)
+ * @HB_UNICODE_COMBINING_CLASS_CCC84: (Telugu)
+ * @HB_UNICODE_COMBINING_CLASS_CCC91: (Telugu)
+ * @HB_UNICODE_COMBINING_CLASS_CCC103: (Thai)
+ * @HB_UNICODE_COMBINING_CLASS_CCC107: (Thai)
+ * @HB_UNICODE_COMBINING_CLASS_CCC118: (Lao)
+ * @HB_UNICODE_COMBINING_CLASS_CCC122: (Lao)
+ * @HB_UNICODE_COMBINING_CLASS_CCC129: (Tibetan)
+ * @HB_UNICODE_COMBINING_CLASS_CCC130: (Tibetan)
+ * @HB_UNICODE_COMBINING_CLASS_CCC133: (Tibetan)
+ * @HB_UNICODE_COMBINING_CLASS_ATTACHED_BELOW_LEFT
+ * @HB_UNICODE_COMBINING_CLASS_ATTACHED_BELOW
+ * @HB_UNICODE_COMBINING_CLASS_ATTACHED_ABOVE
+ * @HB_UNICODE_COMBINING_CLASS_ATTACHED_ABOVE_RIGHT
+ * @HB_UNICODE_COMBINING_CLASS_BELOW_LEFT
+ * @HB_UNICODE_COMBINING_CLASS_BELOW
+ * @HB_UNICODE_COMBINING_CLASS_BELOW_RIGHT
+ * @HB_UNICODE_COMBINING_CLASS_LEFT
+ * @HB_UNICODE_COMBINING_CLASS_RIGHT
+ * @HB_UNICODE_COMBINING_CLASS_ABOVE_LEFT
+ * @HB_UNICODE_COMBINING_CLASS_ABOVE
+ * @HB_UNICODE_COMBINING_CLASS_ABOVE_RIGHT
+ * @HB_UNICODE_COMBINING_CLASS_DOUBLE_BELOW
+ * @HB_UNICODE_COMBINING_CLASS_DOUBLE_ABOVE
+ * @HB_UNICODE_COMBINING_CLASS_IOTA_SUBSCRIPT
+ * @HB_UNICODE_COMBINING_CLASS_INVALID: 255
+ *
+ * Data type for the Canonical_Combining_Class (ccc) property
+ * from the Unicode Character Database.
+ *
+ * <note>Note: newer versions of Unicode may add new values.
+ * Client programs should be ready to handle any value in the 0..254 range
+ * being returned from hb_unicode_combining_class().</note>
+ *
+ **/
 typedef enum
 {
   HB_UNICODE_COMBINING_CLASS_NOT_REORDERED	= 0,
@@ -176,6 +270,18 @@ typedef enum
  * hb_unicode_funcs_t
  */
 
+/**
+ * hb_unicode_funcs_t:
+ *
+ * Data type containing a set of virtual methods used for
+ * accessing various Unicode character properties.
+ *
+ * HarfBuzz provides a default function for each of the
+ * methods in #hb_unicode_funcs_t. Client programs can implement
+ * their own replacements for the individual Unicode functions, as
+ * needed, and replace the default by calling the setter for a
+ * method.
+ **/
 typedef struct hb_unicode_funcs_t hb_unicode_funcs_t;
 
 
@@ -227,40 +333,107 @@ hb_unicode_funcs_get_parent (hb_unicode_funcs_t *ufuncs);
 
 /* typedefs */
 
+/**
+ * hb_unicode_combining_class_func_t:
+ *
+ * A virtual method for the #hb_unicode_funcs_t structure.
+ *
+ * This method should retrieve the Canonical Combining Class (ccc)
+ * property for a specified Unicode code point. 
+ * 
+ **/
 typedef hb_unicode_combining_class_t	(*hb_unicode_combining_class_func_t)	(hb_unicode_funcs_t *ufuncs,
 										 hb_codepoint_t      unicode,
 										 void               *user_data);
+
+/**
+ * hb_unicode_general_category_func_t:
+ *
+ * A virtual method for the #hb_unicode_funcs_t structure.
+ *
+ * This method should retrieve the General Category property for
+ * a specified Unicode code point.
+ * 
+ **/
 typedef hb_unicode_general_category_t	(*hb_unicode_general_category_func_t)	(hb_unicode_funcs_t *ufuncs,
 										 hb_codepoint_t      unicode,
 										 void               *user_data);
+
+/**
+ * hb_unicode_mirroring_func_t:
+ *
+ * A virtual method for the #hb_unicode_funcs_t structure.
+ *
+ * This method should retrieve the Bi-Directional Mirroring Glyph
+ * code point for a specified Unicode code point.
+ *
+ * <note>Note: If a code point does not have a specified
+ * Bi-Directional Mirroring Glyph defined, the method should
+ * return the original code point.</note>
+ * 
+ **/
 typedef hb_codepoint_t			(*hb_unicode_mirroring_func_t)		(hb_unicode_funcs_t *ufuncs,
 										 hb_codepoint_t      unicode,
 										 void               *user_data);
+
+/**
+ * hb_unicode_script_func_t:
+ *
+ * A virtual method for the #hb_unicode_funcs_t structure.
+ *
+ * This method should retrieve the Script property for a 
+ * specified Unicode code point.
+ * 
+ **/
 typedef hb_script_t			(*hb_unicode_script_func_t)		(hb_unicode_funcs_t *ufuncs,
 										 hb_codepoint_t      unicode,
 										 void               *user_data);
 
+/**
+ * hb_unicode_compose_func_t:
+ *
+ * A virtual method for the #hb_unicode_funcs_t structure.
+ *
+ * This method should compose a sequence of two input Unicode code
+ * points by canonical equivalence, returning the composed code
+ * point in a #hb_codepoint_t output parameter (if successful).
+ * The method must return an #hb_bool_t indicating the success
+ * of the composition.
+ * 
+ **/
 typedef hb_bool_t			(*hb_unicode_compose_func_t)		(hb_unicode_funcs_t *ufuncs,
 										 hb_codepoint_t      a,
 										 hb_codepoint_t      b,
 										 hb_codepoint_t     *ab,
 										 void               *user_data);
+
+/**
+ * hb_unicode_decompose_func_t:
+ *
+ * A virtual method for the #hb_unicode_funcs_t structure.
+ *
+ * This method should decompose an input Unicode code point,
+ * returning the two decomposed code points in #hb_codepoint_t
+ * output parameters (if successful). The method must return an
+ * #hb_bool_t indicating the success of the composition.
+ * 
+ **/
 typedef hb_bool_t			(*hb_unicode_decompose_func_t)		(hb_unicode_funcs_t *ufuncs,
 										 hb_codepoint_t      ab,
 										 hb_codepoint_t     *a,
 										 hb_codepoint_t     *b,
 										 void               *user_data);
 
-/* setters */
+/* func setters */
 
 /**
  * hb_unicode_funcs_set_combining_class_func:
- * @ufuncs: a Unicode function structure
- * @func: (closure user_data) (destroy destroy) (scope notified):
- * @user_data:
- * @destroy:
- *
+ * @ufuncs: A Unicode-functions structure
+ * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign
+ * @user_data: Data to pass to @func
+ * @destroy: The function to call when @user_data is not needed anymore
  *
+ * Sets the implementation function for #hb_unicode_combining_class_func_t.
  *
  * Since: 0.9.2
  **/
@@ -271,12 +444,12 @@ hb_unicode_funcs_set_combining_class_func (hb_unicode_funcs_t *ufuncs,
 
 /**
  * hb_unicode_funcs_set_general_category_func:
- * @ufuncs: a Unicode function structure
- * @func: (closure user_data) (destroy destroy) (scope notified):
- * @user_data:
- * @destroy:
- *
+ * @ufuncs: A Unicode-functions structure
+ * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign
+ * @user_data: Data to pass to @func
+ * @destroy: The function to call when @user_data is not needed anymore
  *
+ * Sets the implementation function for #hb_unicode_general_category_func_t.
  *
  * Since: 0.9.2
  **/
@@ -287,12 +460,12 @@ hb_unicode_funcs_set_general_category_func (hb_unicode_funcs_t *ufuncs,
 
 /**
  * hb_unicode_funcs_set_mirroring_func:
- * @ufuncs: a Unicode function structure
- * @func: (closure user_data) (destroy destroy) (scope notified):
- * @user_data:
- * @destroy:
- *
+ * @ufuncs: A Unicode-functions structure
+ * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign
+ * @user_data: Data to pass to @func
+ * @destroy: The function to call when @user_data is not needed anymore
  *
+ * Sets the implementation function for #hb_unicode_mirroring_func_t.
  *
  * Since: 0.9.2
  **/
@@ -303,12 +476,12 @@ hb_unicode_funcs_set_mirroring_func (hb_unicode_funcs_t *ufuncs,
 
 /**
  * hb_unicode_funcs_set_script_func:
- * @ufuncs: a Unicode function structure
- * @func: (closure user_data) (destroy destroy) (scope notified):
- * @user_data:
- * @destroy:
- *
+ * @ufuncs: A Unicode-functions structure
+ * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign
+ * @user_data: Data to pass to @func
+ * @destroy: The function to call when @user_data is not needed anymore
  *
+ * Sets the implementation function for #hb_unicode_script_func_t.
  *
  * Since: 0.9.2
  **/
@@ -319,12 +492,12 @@ hb_unicode_funcs_set_script_func (hb_unicode_funcs_t *ufuncs,
 
 /**
  * hb_unicode_funcs_set_compose_func:
- * @ufuncs: a Unicode function structure
- * @func: (closure user_data) (destroy destroy) (scope notified):
- * @user_data:
- * @destroy:
- *
+ * @ufuncs: A Unicode-functions structure
+ * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign
+ * @user_data: Data to pass to @func
+ * @destroy: The function to call when @user_data is not needed anymore
  *
+ * Sets the implementation function for #hb_unicode_compose_func_t.
  *
  * Since: 0.9.2
  **/
@@ -335,12 +508,12 @@ hb_unicode_funcs_set_compose_func (hb_unicode_funcs_t *ufuncs,
 
 /**
  * hb_unicode_funcs_set_decompose_func:
- * @ufuncs: a Unicode function structure
- * @func: (closure user_data) (destroy destroy) (scope notified):
- * @user_data:
- * @destroy:
- *
+ * @ufuncs: A Unicode-functions structure
+ * @func: (closure user_data) (destroy destroy) (scope notified): The callback function to assign
+ * @user_data: Data to pass to @func
+ * @destroy: The function to call when @user_data is not needed anymore
  *
+ * Sets the implementation function for #hb_unicode_decompose_func_t.
  *
  * Since: 0.9.2
  **/
@@ -353,6 +526,13 @@ hb_unicode_funcs_set_decompose_func (hb_unicode_funcs_t *ufuncs,
 
 /**
  * hb_unicode_combining_class:
+ * @ufuncs: The Unicode-functions structure
+ * @unicode: The code point to query
+ *
+ * Retrieves the Canonical Combining Class (ccc) property
+ * of code point @unicode.
+ *
+ * Return value: The #hb_unicode_combining_class_t of @unicode
  *
  * Since: 0.9.2
  **/
@@ -362,6 +542,13 @@ hb_unicode_combining_class (hb_unicode_funcs_t *ufuncs,
 
 /**
  * hb_unicode_general_category:
+ * @ufuncs: The Unicode-functions structure
+ * @unicode: The code point to query
+ *
+ * Retrieves the General Category (gc) property
+ * of code point @unicode.
+ *
+ * Return value: The #hb_unicode_general_category_t of @unicode
  *
  * Since: 0.9.2
  **/
@@ -371,6 +558,13 @@ hb_unicode_general_category (hb_unicode_funcs_t *ufuncs,
 
 /**
  * hb_unicode_mirroring:
+ * @ufuncs: The Unicode-functions structure
+ * @unicode: The code point to query
+ *
+ * Retrieves the Bi-directional Mirroring Glyph code
+ * point defined for code point @unicode.
+ *
+ * Return value: The #hb_codepoint_t of the Mirroring Glyph for @unicode
  *
  * Since: 0.9.2
  **/
@@ -380,6 +574,13 @@ hb_unicode_mirroring (hb_unicode_funcs_t *ufuncs,
 
 /**
  * hb_unicode_script:
+ * @ufuncs: The Unicode-functions structure
+ * @unicode: The code point to query
+ *
+ * Retrieves the #hb_script_t script to which code
+ * point @unicode belongs.
+ *
+ * Return value: The #hb_script_t of @unicode
  *
  * Since: 0.9.2
  **/
@@ -387,12 +588,40 @@ HB_EXTERN hb_script_t
 hb_unicode_script (hb_unicode_funcs_t *ufuncs,
 		   hb_codepoint_t unicode);
 
+/**
+ * hb_unicode_compose:
+ * @ufuncs: The Unicode-functions structure
+ * @a: The first code point to compose
+ * @b: The second code point to compose
+ * @ab: (out): The composed code point 
+ *
+ * Composes the code point sequence @a,@b by canonical equivalence into
+ * code point @ab.
+ *
+ * Return value: True is @a,@b composed, false otherwise
+ *
+ * Since: 0.9.2
+ **/
 HB_EXTERN hb_bool_t
 hb_unicode_compose (hb_unicode_funcs_t *ufuncs,
 		    hb_codepoint_t      a,
 		    hb_codepoint_t      b,
 		    hb_codepoint_t     *ab);
 
+/**
+ * hb_unicode_decompose:
+ * @ufuncs: The Unicode-functions structure
+ * @ab: The code point to decompose
+ * @a: (out): The first decomposed code point
+ * @b: (out): The second decomposed code point
+ *
+ * Decomposes code point @ab by canonical equivalence, into code points
+ * @a and @b.
+ *
+ * Return value: True if @ab decomposed, false otherwise
+ *
+ * Since: 0.9.2
+ **/
 HB_EXTERN hb_bool_t
 hb_unicode_decompose (hb_unicode_funcs_t *ufuncs,
 		      hb_codepoint_t      ab,