diff --git a/src/hb-blob.cc b/src/hb-blob.cc
index b312546d0..5c53016b7 100644
--- a/src/hb-blob.cc
+++ b/src/hb-blob.cc
@@ -77,17 +77,17 @@ _hb_blob_destroy_user_data (hb_blob_t *blob)
 }
 
 /**
- * hb_blob_create:
- * @data: (array length=length) (allow-none): Pointer to blob data.
+ * hb_blob_create: (constructor)
+ * @data: (array length=length): Pointer to blob data.
  * @length: Length of @data in bytes.
  * @mode: Memory mode for @data.
- * @user_data: (allow-none): Data parameter to pass to @destroy.
- * @destroy: (allow-none) (closure user_data): Callback to call when @data is not needed anymore.
+ * @user_data: Data parameter to pass to @destroy.
+ * @destroy: (closure user_data): Callback to call when @data is not needed anymore.
  *
  * Creates a new "blob" object wrapping @data.  The @mode parameter is used
  * to negotiate ownership and lifecycle of @data.
  *
- * Returns: New blob, or the empty blob if something failed or if @length is
+ * Return value: New blob, or the empty blob if something failed or if @length is
  * zero.  Destroy with hb_blob_destroy().
  *
  * Since: 1.0
@@ -139,9 +139,9 @@ hb_blob_create (const char        *data,
  *
  * Makes @parent immutable.
  *
- * Returns: New blob, or the empty blob if something failed or if @length is
- * zero or @offset is beyond the end of @parent's data.  Destroy with
- * hb_blob_destroy().
+ * Return value: New blob, or the empty blob if something failed or if
+ * @length is zero or @offset is beyond the end of @parent's data.  Destroy
+ * with hb_blob_destroy().
  *
  * Since: 1.0
  **/
@@ -173,7 +173,7 @@ hb_blob_create_sub_blob (hb_blob_t    *parent,
  *
  * See TODO:link object types for more information.
  *
- * Returns: The empty blob.
+ * Return value: (transfer full): the empty blob.
  *
  * Since: 1.0
  **/
@@ -197,14 +197,14 @@ hb_blob_get_empty (void)
 }
 
 /**
- * hb_blob_reference:
+ * hb_blob_reference: (skip)
  * @blob: a blob.
  *
  * Increases the reference count on @blob.
  *
  * See TODO:link object types for more information.
  *
- * Returns: @blob.
+ * Return value: @blob.
  *
  * Since: 1.0
  **/
@@ -215,7 +215,7 @@ hb_blob_reference (hb_blob_t *blob)
 }
 
 /**
- * hb_blob_destroy:
+ * hb_blob_destroy: (skip)
  * @blob: a blob.
  *
  * Descreases the reference count on @blob, and if it reaches zero, destroys
@@ -237,18 +237,14 @@ hb_blob_destroy (hb_blob_t *blob)
 }
 
 /**
- * hb_blob_set_user_data:
+ * hb_blob_set_user_data: (skip)
  * @blob: a blob.
  * @key: key for data to set.
  * @data: data to set.
  * @destroy: callback to call when @data is not needed anymore.
  * @replace: whether to replace an existing data with the same key.
  *
- * Attaches a piece of data to the object.
- *
- * See TODO:link object types for more information.
- *
- * Returns: TODO
+ * Return value: 
  *
  * Since: 1.0
  **/
@@ -263,15 +259,13 @@ hb_blob_set_user_data (hb_blob_t          *blob,
 }
 
 /**
- * hb_blob_get_user_data:
+ * hb_blob_get_user_data: (skip)
  * @blob: a blob.
  * @key: key for data to get.
  *
- * TODO
+ * 
  *
- * See TODO:link object types for more information.
- *
- * Returns: (transfer none): data, or TODO
+ * Return value: (transfer none): 
  *
  * Since: 1.0
  **/
@@ -287,9 +281,7 @@ hb_blob_get_user_data (hb_blob_t          *blob,
  * hb_blob_make_immutable:
  * @blob: a blob.
  *
- * TODO
- *
- * See TODO:link object types for more information.
+ * 
  *
  * Since: 1.0
  **/
@@ -306,11 +298,9 @@ hb_blob_make_immutable (hb_blob_t *blob)
  * hb_blob_is_immutable:
  * @blob: a blob.
  *
- * TODO
+ * 
  *
- * See TODO:link object types for more information.
- *
- * Returns: TODO
+ * Return value: TODO
  *
  * Since: 1.0
  **/
@@ -325,9 +315,9 @@ hb_blob_is_immutable (hb_blob_t *blob)
  * hb_blob_get_length:
  * @blob: a blob.
  *
- * TODO
+ * 
  *
- * Returns: the length of blob data in bytes.
+ * Return value: the length of blob data in bytes.
  *
  * Since: 1.0
  **/
@@ -340,11 +330,11 @@ hb_blob_get_length (hb_blob_t *blob)
 /**
  * hb_blob_get_data:
  * @blob: a blob.
- * @length: (out) TODO
+ * @length: (out):
  *
- * TODO
+ * 
  *
- * Returns: (transfer none): TODO
+ * Returns: (transfer none) (array length=length): 
  *
  * Since: 1.0
  **/
@@ -368,7 +358,8 @@ hb_blob_get_data (hb_blob_t *blob, unsigned int *length)
  * Fails if blob has been made immutable, or if memory allocation
  * fails.
  *
- * Returns: (transfer none): Writable blob data, or %NULL if failed.
+ * Returns: (transfer none) (array length=length): Writable blob data,
+ * or %NULL if failed.
  *
  * Since: 1.0
  **/
diff --git a/src/hb-buffer-serialize.cc b/src/hb-buffer-serialize.cc
index eac69000d..b32092cf0 100644
--- a/src/hb-buffer-serialize.cc
+++ b/src/hb-buffer-serialize.cc
@@ -33,12 +33,32 @@ static const char *serialize_formats[] = {
   NULL
 };
 
+/**
+ * hb_buffer_serialize_list_formats:
+ *
+ * 
+ *
+ * Return value: (transfer none):
+ *
+ * Since: 1.0
+ **/
 const char **
 hb_buffer_serialize_list_formats (void)
 {
   return serialize_formats;
 }
 
+/**
+ * hb_buffer_serialize_format_from_string:
+ * @str: 
+ * @len: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_buffer_serialize_format_t
 hb_buffer_serialize_format_from_string (const char *str, int len)
 {
@@ -46,6 +66,16 @@ hb_buffer_serialize_format_from_string (const char *str, int len)
   return (hb_buffer_serialize_format_t) (hb_tag_from_string (str, len) & ~0x20202020);
 }
 
+/**
+ * hb_buffer_serialize_format_to_string:
+ * @format: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 const char *
 hb_buffer_serialize_format_to_string (hb_buffer_serialize_format_t format)
 {
@@ -194,6 +224,24 @@ _hb_buffer_serialize_glyphs_text (hb_buffer_t *buffer,
 }
 
 /* Returns number of items, starting at start, that were serialized. */
+/**
+ * hb_buffer_serialize_glyphs:
+ * @buffer: a buffer.
+ * @start: 
+ * @end: 
+ * @buf: (array length=buf_size):
+ * @buf_size: 
+ * @buf_consumed: (out):
+ * @font: 
+ * @format: 
+ * @flags: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 unsigned int
 hb_buffer_serialize_glyphs (hb_buffer_t *buffer,
 			    unsigned int start,
@@ -286,6 +334,21 @@ parse_int (const char *pp, const char *end, int32_t *pv)
 #include "hb-buffer-deserialize-json.hh"
 #include "hb-buffer-deserialize-text.hh"
 
+/**
+ * hb_buffer_deserialize_glyphs:
+ * @buffer: a buffer.
+ * @buf: (array length=buf_len):
+ * @buf_len: 
+ * @end_ptr: (out):
+ * @font: 
+ * @format: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_buffer_deserialize_glyphs (hb_buffer_t *buffer,
 			      const char *buf,
diff --git a/src/hb-buffer.cc b/src/hb-buffer.cc
index 2bfdfad39..8143a1ef1 100644
--- a/src/hb-buffer.cc
+++ b/src/hb-buffer.cc
@@ -603,6 +603,15 @@ void hb_buffer_t::deallocate_var_all (void)
 
 /* Public API */
 
+/**
+ * hb_buffer_create: (constructor)
+ *
+ * 
+ *
+ * Return value: (transfer full)
+ *
+ * Since: 1.0
+ **/
 hb_buffer_t *
 hb_buffer_create (void)
 {
@@ -616,6 +625,15 @@ hb_buffer_create (void)
   return buffer;
 }
 
+/**
+ * hb_buffer_get_empty:
+ *
+ * 
+ *
+ * Return value: (transfer full):
+ *
+ * Since: 1.0
+ **/
 hb_buffer_t *
 hb_buffer_get_empty (void)
 {
@@ -637,12 +655,30 @@ hb_buffer_get_empty (void)
   return const_cast<hb_buffer_t *> (&_hb_buffer_nil);
 }
 
+/**
+ * hb_buffer_reference: (skip)
+ * @buffer: a buffer.
+ *
+ * 
+ *
+ * Return value: (transfer full):
+ *
+ * Since: 1.0
+ **/
 hb_buffer_t *
 hb_buffer_reference (hb_buffer_t *buffer)
 {
   return hb_object_reference (buffer);
 }
 
+/**
+ * hb_buffer_destroy: (skip)
+ * @buffer: a buffer.
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_destroy (hb_buffer_t *buffer)
 {
@@ -656,6 +692,20 @@ hb_buffer_destroy (hb_buffer_t *buffer)
   free (buffer);
 }
 
+/**
+ * hb_buffer_set_user_data: (skip)
+ * @buffer: a buffer.
+ * @key: 
+ * @data: 
+ * @destroy: 
+ * @replace: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_buffer_set_user_data (hb_buffer_t        *buffer,
 			 hb_user_data_key_t *key,
@@ -666,6 +716,17 @@ hb_buffer_set_user_data (hb_buffer_t        *buffer,
   return hb_object_set_user_data (buffer, key, data, destroy, replace);
 }
 
+/**
+ * hb_buffer_get_user_data: (skip)
+ * @buffer: a buffer.
+ * @key: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 void *
 hb_buffer_get_user_data (hb_buffer_t        *buffer,
 			 hb_user_data_key_t *key)
@@ -674,6 +735,15 @@ hb_buffer_get_user_data (hb_buffer_t        *buffer,
 }
 
 
+/**
+ * hb_buffer_set_content_type:
+ * @buffer: a buffer.
+ * @content_type: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_set_content_type (hb_buffer_t              *buffer,
 			    hb_buffer_content_type_t  content_type)
@@ -681,6 +751,16 @@ hb_buffer_set_content_type (hb_buffer_t              *buffer,
   buffer->content_type = content_type;
 }
 
+/**
+ * hb_buffer_get_content_type:
+ * @buffer: a buffer.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_buffer_content_type_t
 hb_buffer_get_content_type (hb_buffer_t *buffer)
 {
@@ -688,28 +768,56 @@ hb_buffer_get_content_type (hb_buffer_t *buffer)
 }
 
 
+/**
+ * hb_buffer_set_unicode_funcs:
+ * @buffer: a buffer.
+ * @unicode_funcs: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_set_unicode_funcs (hb_buffer_t        *buffer,
-			     hb_unicode_funcs_t *unicode)
+			     hb_unicode_funcs_t *unicode_funcs)
 {
   if (unlikely (hb_object_is_inert (buffer)))
     return;
 
-  if (!unicode)
-    unicode = hb_unicode_funcs_get_default ();
+  if (!unicode_funcs)
+    unicode_funcs = hb_unicode_funcs_get_default ();
 
 
-  hb_unicode_funcs_reference (unicode);
+  hb_unicode_funcs_reference (unicode_funcs);
   hb_unicode_funcs_destroy (buffer->unicode);
-  buffer->unicode = unicode;
+  buffer->unicode = unicode_funcs;
 }
 
+/**
+ * hb_buffer_get_unicode_funcs:
+ * @buffer: a buffer.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_unicode_funcs_t *
 hb_buffer_get_unicode_funcs (hb_buffer_t        *buffer)
 {
   return buffer->unicode;
 }
 
+/**
+ * hb_buffer_set_direction:
+ * @buffer: a buffer.
+ * @direction: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_set_direction (hb_buffer_t    *buffer,
 			 hb_direction_t  direction)
@@ -721,12 +829,31 @@ hb_buffer_set_direction (hb_buffer_t    *buffer,
   buffer->props.direction = direction;
 }
 
+/**
+ * hb_buffer_get_direction:
+ * @buffer: a buffer.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_direction_t
 hb_buffer_get_direction (hb_buffer_t    *buffer)
 {
   return buffer->props.direction;
 }
 
+/**
+ * hb_buffer_set_script:
+ * @buffer: a buffer.
+ * @script: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_set_script (hb_buffer_t *buffer,
 		      hb_script_t  script)
@@ -737,12 +864,31 @@ hb_buffer_set_script (hb_buffer_t *buffer,
   buffer->props.script = script;
 }
 
+/**
+ * hb_buffer_get_script:
+ * @buffer: a buffer.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_script_t
 hb_buffer_get_script (hb_buffer_t *buffer)
 {
   return buffer->props.script;
 }
 
+/**
+ * hb_buffer_set_language:
+ * @buffer: a buffer.
+ * @language: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_set_language (hb_buffer_t   *buffer,
 			hb_language_t  language)
@@ -753,12 +899,31 @@ hb_buffer_set_language (hb_buffer_t   *buffer,
   buffer->props.language = language;
 }
 
+/**
+ * hb_buffer_get_language:
+ * @buffer: a buffer.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_language_t
 hb_buffer_get_language (hb_buffer_t *buffer)
 {
   return buffer->props.language;
 }
 
+/**
+ * hb_buffer_set_segment_properties:
+ * @buffer: a buffer.
+ * @props: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_set_segment_properties (hb_buffer_t *buffer,
 				  const hb_segment_properties_t *props)
@@ -769,6 +934,15 @@ hb_buffer_set_segment_properties (hb_buffer_t *buffer,
   buffer->props = *props;
 }
 
+/**
+ * hb_buffer_get_segment_properties:
+ * @buffer: a buffer.
+ * @props: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_get_segment_properties (hb_buffer_t *buffer,
 				  hb_segment_properties_t *props)
@@ -777,6 +951,15 @@ hb_buffer_get_segment_properties (hb_buffer_t *buffer,
 }
 
 
+/**
+ * hb_buffer_set_flags:
+ * @buffer: a buffer.
+ * @flags: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_set_flags (hb_buffer_t       *buffer,
 		     hb_buffer_flags_t  flags)
@@ -787,6 +970,16 @@ hb_buffer_set_flags (hb_buffer_t       *buffer,
   buffer->flags = flags;
 }
 
+/**
+ * hb_buffer_get_flags:
+ * @buffer: a buffer.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_buffer_flags_t
 hb_buffer_get_flags (hb_buffer_t *buffer)
 {
@@ -794,30 +987,77 @@ hb_buffer_get_flags (hb_buffer_t *buffer)
 }
 
 
+/**
+ * hb_buffer_reset:
+ * @buffer: a buffer.
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_reset (hb_buffer_t *buffer)
 {
   buffer->reset ();
 }
 
+/**
+ * hb_buffer_clear_contents:
+ * @buffer: a buffer.
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_clear_contents (hb_buffer_t *buffer)
 {
   buffer->clear ();
 }
 
+/**
+ * hb_buffer_pre_allocate:
+ * @buffer: a buffer.
+ * @size: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_buffer_pre_allocate (hb_buffer_t *buffer, unsigned int size)
 {
   return buffer->ensure (size);
 }
 
+/**
+ * hb_buffer_allocation_successful:
+ * @buffer: a buffer.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_buffer_allocation_successful (hb_buffer_t  *buffer)
 {
   return !buffer->in_error;
 }
 
+/**
+ * hb_buffer_add:
+ * @buffer: a buffer.
+ * @codepoint: 
+ * @cluster: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_add (hb_buffer_t    *buffer,
 	       hb_codepoint_t  codepoint,
@@ -827,6 +1067,17 @@ hb_buffer_add (hb_buffer_t    *buffer,
   buffer->clear_context (1);
 }
 
+/**
+ * hb_buffer_set_length:
+ * @buffer: a buffer.
+ * @length: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_buffer_set_length (hb_buffer_t  *buffer,
 		      unsigned int  length)
@@ -1042,6 +1293,18 @@ hb_buffer_add_utf (hb_buffer_t  *buffer,
   buffer->content_type = HB_BUFFER_CONTENT_TYPE_UNICODE;
 }
 
+/**
+ * hb_buffer_add_utf8:
+ * @buffer: a buffer.
+ * @text: (array length=text_length):
+ * @text_length: 
+ * @item_offset: 
+ * @item_length: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_add_utf8 (hb_buffer_t  *buffer,
 		    const char   *text,
@@ -1052,16 +1315,40 @@ hb_buffer_add_utf8 (hb_buffer_t  *buffer,
   hb_buffer_add_utf (buffer, (const uint8_t *) text, text_length, item_offset, item_length);
 }
 
+/**
+ * hb_buffer_add_utf16:
+ * @buffer: a buffer.
+ * @text: (array length=text_length):
+ * @text_length: 
+ * @item_offset: 
+ * @item_length: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_add_utf16 (hb_buffer_t    *buffer,
 		     const uint16_t *text,
 		     int             text_length,
 		     unsigned int    item_offset,
-		     int            item_length)
+		     int             item_length)
 {
   hb_buffer_add_utf (buffer, text, text_length, item_offset, item_length);
 }
 
+/**
+ * hb_buffer_add_utf32:
+ * @buffer: a buffer.
+ * @text: (array length=text_length):
+ * @text_length: 
+ * @item_offset: 
+ * @item_length: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_add_utf32 (hb_buffer_t    *buffer,
 		     const uint32_t *text,
@@ -1128,6 +1415,14 @@ normalize_glyphs_cluster (hb_buffer_t *buffer,
   }
 }
 
+/**
+ * hb_buffer_normalize_glyphs:
+ * @buffer: a buffer.
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_buffer_normalize_glyphs (hb_buffer_t *buffer)
 {
diff --git a/src/hb-face.cc b/src/hb-face.cc
index d8b9ed8c3..10f4302a5 100644
--- a/src/hb-face.cc
+++ b/src/hb-face.cc
@@ -68,6 +68,18 @@ const hb_face_t _hb_face_nil = {
 };
 
 
+/**
+ * hb_face_create_for_tables:
+ * @reference_table_func: 
+ * @user_data: 
+ * @destroy: 
+ *
+ * 
+ *
+ * Return value: (transfer full)
+ *
+ * Since: 1.0
+ **/
 hb_face_t *
 hb_face_create_for_tables (hb_reference_table_func_t  reference_table_func,
 			   void                      *user_data,
@@ -137,6 +149,17 @@ _hb_face_for_data_reference_table (hb_face_t *face HB_UNUSED, hb_tag_t tag, void
   return blob;
 }
 
+/**
+ * hb_face_create: (constructor)
+ * @blob: 
+ * @index: 
+ *
+ * 
+ *
+ * Return value: (transfer full):
+ *
+ * Since: 1.0
+ **/
 hb_face_t *
 hb_face_create (hb_blob_t    *blob,
 		unsigned int  index)
@@ -160,6 +183,15 @@ hb_face_create (hb_blob_t    *blob,
   return face;
 }
 
+/**
+ * hb_face_get_empty:
+ *
+ * 
+ *
+ * Return value: (transfer full)
+ *
+ * Since: 1.0
+ **/
 hb_face_t *
 hb_face_get_empty (void)
 {
@@ -167,12 +199,30 @@ hb_face_get_empty (void)
 }
 
 
+/**
+ * hb_face_reference: (skip)
+ * @face: a face.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_face_t *
 hb_face_reference (hb_face_t *face)
 {
   return hb_object_reference (face);
 }
 
+/**
+ * hb_face_destroy: (skip)
+ * @face: a face.
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_face_destroy (hb_face_t *face)
 {
@@ -196,6 +246,20 @@ hb_face_destroy (hb_face_t *face)
   free (face);
 }
 
+/**
+ * hb_face_set_user_data: (skip)
+ * @face: a face.
+ * @key: 
+ * @data: 
+ * @destroy: 
+ * @replace: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_face_set_user_data (hb_face_t          *face,
 		       hb_user_data_key_t *key,
@@ -206,6 +270,17 @@ hb_face_set_user_data (hb_face_t          *face,
   return hb_object_set_user_data (face, key, data, destroy, replace);
 }
 
+/**
+ * hb_face_get_user_data: (skip)
+ * @face: a face.
+ * @key: 
+ *
+ * 
+ *
+ * Return value: (transfer none):
+ *
+ * Since: 1.0
+ **/
 void *
 hb_face_get_user_data (hb_face_t          *face,
 		       hb_user_data_key_t *key)
@@ -213,6 +288,14 @@ hb_face_get_user_data (hb_face_t          *face,
   return hb_object_get_user_data (face, key);
 }
 
+/**
+ * hb_face_make_immutable:
+ * @face: a face.
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_face_make_immutable (hb_face_t *face)
 {
@@ -222,6 +305,16 @@ hb_face_make_immutable (hb_face_t *face)
   face->immutable = true;
 }
 
+/**
+ * hb_face_is_immutable:
+ * @face: a face.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_face_is_immutable (hb_face_t *face)
 {
@@ -229,6 +322,17 @@ hb_face_is_immutable (hb_face_t *face)
 }
 
 
+/**
+ * hb_face_reference_table:
+ * @face: a face.
+ * @tag: 
+ *
+ * 
+ *
+ * Return value: (transfer full):
+ *
+ * Since: 1.0
+ **/
 hb_blob_t *
 hb_face_reference_table (hb_face_t *face,
 			 hb_tag_t   tag)
@@ -236,12 +340,31 @@ hb_face_reference_table (hb_face_t *face,
   return face->reference_table (tag);
 }
 
+/**
+ * hb_face_reference_blob:
+ * @face: a face.
+ *
+ * 
+ *
+ * Return value: (transfer full):
+ *
+ * Since: 1.0
+ **/
 hb_blob_t *
 hb_face_reference_blob (hb_face_t *face)
 {
   return face->reference_table (HB_TAG_NONE);
 }
 
+/**
+ * hb_face_set_index:
+ * @face: a face.
+ * @index: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_face_set_index (hb_face_t    *face,
 		   unsigned int  index)
@@ -252,12 +375,31 @@ hb_face_set_index (hb_face_t    *face,
   face->index = index;
 }
 
+/**
+ * hb_face_get_index:
+ * @face: a face.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 unsigned int
 hb_face_get_index (hb_face_t    *face)
 {
   return face->index;
 }
 
+/**
+ * hb_face_set_upem:
+ * @face: a face.
+ * @upem: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_face_set_upem (hb_face_t    *face,
 		  unsigned int  upem)
@@ -268,6 +410,16 @@ hb_face_set_upem (hb_face_t    *face,
   face->upem = upem;
 }
 
+/**
+ * hb_face_get_upem:
+ * @face: a face.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 unsigned int
 hb_face_get_upem (hb_face_t *face)
 {
@@ -283,6 +435,15 @@ hb_face_t::load_upem (void) const
   hb_blob_destroy (head_blob);
 }
 
+/**
+ * hb_face_set_glyph_count:
+ * @face: a face.
+ * @glyph_count: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_face_set_glyph_count (hb_face_t    *face,
 			 unsigned int  glyph_count)
@@ -293,6 +454,16 @@ hb_face_set_glyph_count (hb_face_t    *face,
   face->num_glyphs = glyph_count;
 }
 
+/**
+ * hb_face_get_glyph_count:
+ * @face: a face.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 unsigned int
 hb_face_get_glyph_count (hb_face_t *face)
 {
diff --git a/src/hb-font-private.hh b/src/hb-font-private.hh
index 9638839f9..00c0cc3f2 100644
--- a/src/hb-font-private.hh
+++ b/src/hb-font-private.hh
@@ -193,10 +193,10 @@ struct hb_font_t {
 				       klass->user_data.glyph_h_kerning);
   }
 
-  inline hb_position_t get_glyph_v_kerning (hb_codepoint_t left_glyph, hb_codepoint_t right_glyph)
+  inline hb_position_t get_glyph_v_kerning (hb_codepoint_t top_glyph, hb_codepoint_t bottom_glyph)
   {
     return klass->get.glyph_v_kerning (this, user_data,
-				       left_glyph, right_glyph,
+				       top_glyph, bottom_glyph,
 				       klass->user_data.glyph_v_kerning);
   }
 
diff --git a/src/hb-font.cc b/src/hb-font.cc
index c2f6f6ddd..34c3ba003 100644
--- a/src/hb-font.cc
+++ b/src/hb-font.cc
@@ -230,6 +230,15 @@ static const hb_font_funcs_t _hb_font_funcs_nil = {
 };
 
 
+/**
+ * hb_font_funcs_create: (constructor)
+ *
+ * 
+ *
+ * Return value: (transfer full): 
+ *
+ * Since: 1.0
+ **/
 hb_font_funcs_t *
 hb_font_funcs_create (void)
 {
@@ -243,18 +252,45 @@ hb_font_funcs_create (void)
   return ffuncs;
 }
 
+/**
+ * hb_font_funcs_get_empty:
+ *
+ * 
+ *
+ * Return value: (transfer full): 
+ *
+ * Since: 1.0
+ **/
 hb_font_funcs_t *
 hb_font_funcs_get_empty (void)
 {
   return const_cast<hb_font_funcs_t *> (&_hb_font_funcs_nil);
 }
 
+/**
+ * hb_font_funcs_reference: (skip)
+ * @ffuncs: font functions.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_font_funcs_t *
 hb_font_funcs_reference (hb_font_funcs_t *ffuncs)
 {
   return hb_object_reference (ffuncs);
 }
 
+/**
+ * hb_font_funcs_destroy: (skip)
+ * @ffuncs: font functions.
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_funcs_destroy (hb_font_funcs_t *ffuncs)
 {
@@ -268,6 +304,20 @@ hb_font_funcs_destroy (hb_font_funcs_t *ffuncs)
   free (ffuncs);
 }
 
+/**
+ * hb_font_funcs_set_user_data: (skip)
+ * @ffuncs: font functions.
+ * @key: 
+ * @data: 
+ * @destroy: 
+ * @replace: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_font_funcs_set_user_data (hb_font_funcs_t    *ffuncs,
 			     hb_user_data_key_t *key,
@@ -278,6 +328,17 @@ hb_font_funcs_set_user_data (hb_font_funcs_t    *ffuncs,
   return hb_object_set_user_data (ffuncs, key, data, destroy, replace);
 }
 
+/**
+ * hb_font_funcs_get_user_data: (skip)
+ * @ffuncs: font functions.
+ * @key: 
+ *
+ * 
+ *
+ * Return value: (transfer none): 
+ *
+ * Since: 1.0
+ **/
 void *
 hb_font_funcs_get_user_data (hb_font_funcs_t    *ffuncs,
 			     hb_user_data_key_t *key)
@@ -286,6 +347,14 @@ hb_font_funcs_get_user_data (hb_font_funcs_t    *ffuncs,
 }
 
 
+/**
+ * hb_font_funcs_make_immutable:
+ * @ffuncs: font functions.
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_funcs_make_immutable (hb_font_funcs_t *ffuncs)
 {
@@ -295,6 +364,16 @@ hb_font_funcs_make_immutable (hb_font_funcs_t *ffuncs)
   ffuncs->immutable = true;
 }
 
+/**
+ * hb_font_funcs_is_immutable:
+ * @ffuncs: font functions.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_font_funcs_is_immutable (hb_font_funcs_t *ffuncs)
 {
@@ -336,6 +415,19 @@ HB_FONT_FUNCS_IMPLEMENT_CALLBACKS
 
 /* Public getters */
 
+/**
+ * hb_font_get_glyph:
+ * @font: a font.
+ * @unicode: 
+ * @variation_selector: 
+ * @glyph: (out): 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_font_get_glyph (hb_font_t *font,
 		   hb_codepoint_t unicode, hb_codepoint_t variation_selector,
@@ -344,6 +436,17 @@ hb_font_get_glyph (hb_font_t *font,
   return font->get_glyph (unicode, variation_selector, glyph);
 }
 
+/**
+ * hb_font_get_glyph_h_advance:
+ * @font: a font.
+ * @glyph: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_position_t
 hb_font_get_glyph_h_advance (hb_font_t *font,
 			     hb_codepoint_t glyph)
@@ -351,6 +454,17 @@ hb_font_get_glyph_h_advance (hb_font_t *font,
   return font->get_glyph_h_advance (glyph);
 }
 
+/**
+ * hb_font_get_glyph_v_advance:
+ * @font: a font.
+ * @glyph: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_position_t
 hb_font_get_glyph_v_advance (hb_font_t *font,
 			     hb_codepoint_t glyph)
@@ -358,6 +472,19 @@ hb_font_get_glyph_v_advance (hb_font_t *font,
   return font->get_glyph_v_advance (glyph);
 }
 
+/**
+ * hb_font_get_glyph_h_origin:
+ * @font: a font.
+ * @glyph: 
+ * @x: (out): 
+ * @y: (out): 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_font_get_glyph_h_origin (hb_font_t *font,
 			    hb_codepoint_t glyph,
@@ -366,6 +493,19 @@ hb_font_get_glyph_h_origin (hb_font_t *font,
   return font->get_glyph_h_origin (glyph, x, y);
 }
 
+/**
+ * hb_font_get_glyph_v_origin:
+ * @font: a font.
+ * @glyph: 
+ * @x: (out): 
+ * @y: (out): 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_font_get_glyph_v_origin (hb_font_t *font,
 			    hb_codepoint_t glyph,
@@ -374,6 +514,18 @@ hb_font_get_glyph_v_origin (hb_font_t *font,
   return font->get_glyph_v_origin (glyph, x, y);
 }
 
+/**
+ * hb_font_get_glyph_h_kerning:
+ * @font: a font.
+ * @left_glyph: 
+ * @right_glyph: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_position_t
 hb_font_get_glyph_h_kerning (hb_font_t *font,
 			     hb_codepoint_t left_glyph, hb_codepoint_t right_glyph)
@@ -381,13 +533,37 @@ hb_font_get_glyph_h_kerning (hb_font_t *font,
   return font->get_glyph_h_kerning (left_glyph, right_glyph);
 }
 
+/**
+ * hb_font_get_glyph_v_kerning:
+ * @font: a font.
+ * @top_glyph: 
+ * @bottom_glyph: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_position_t
 hb_font_get_glyph_v_kerning (hb_font_t *font,
-			     hb_codepoint_t left_glyph, hb_codepoint_t right_glyph)
+			     hb_codepoint_t top_glyph, hb_codepoint_t bottom_glyph)
 {
-  return font->get_glyph_v_kerning (left_glyph, right_glyph);
+  return font->get_glyph_v_kerning (top_glyph, bottom_glyph);
 }
 
+/**
+ * hb_font_get_glyph_extents:
+ * @font: a font.
+ * @glyph: 
+ * @extents: (out): 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_font_get_glyph_extents (hb_font_t *font,
 			   hb_codepoint_t glyph,
@@ -396,6 +572,20 @@ hb_font_get_glyph_extents (hb_font_t *font,
   return font->get_glyph_extents (glyph, extents);
 }
 
+/**
+ * hb_font_get_glyph_contour_point:
+ * @font: a font.
+ * @glyph: 
+ * @point_index: 
+ * @x: (out): 
+ * @y: (out): 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_font_get_glyph_contour_point (hb_font_t *font,
 				 hb_codepoint_t glyph, unsigned int point_index,
@@ -404,6 +594,19 @@ hb_font_get_glyph_contour_point (hb_font_t *font,
   return font->get_glyph_contour_point (glyph, point_index, x, y);
 }
 
+/**
+ * hb_font_get_glyph_name:
+ * @font: a font.
+ * @glyph: 
+ * @name: (array length=size): 
+ * @size: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_font_get_glyph_name (hb_font_t *font,
 			hb_codepoint_t glyph,
@@ -412,6 +615,19 @@ hb_font_get_glyph_name (hb_font_t *font,
   return font->get_glyph_name (glyph, name, size);
 }
 
+/**
+ * hb_font_get_glyph_from_name:
+ * @font: a font.
+ * @name: (array length=len): 
+ * @len: 
+ * @glyph: (out): 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_font_get_glyph_from_name (hb_font_t *font,
 			     const char *name, int len, /* -1 means nul-terminated */
@@ -423,6 +639,18 @@ hb_font_get_glyph_from_name (hb_font_t *font,
 
 /* A bit higher-level, and with fallback */
 
+/**
+ * hb_font_get_glyph_advance_for_direction:
+ * @font: a font.
+ * @glyph: 
+ * @direction: 
+ * @x: (out): 
+ * @y: (out): 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_get_glyph_advance_for_direction (hb_font_t *font,
 					 hb_codepoint_t glyph,
@@ -432,6 +660,18 @@ hb_font_get_glyph_advance_for_direction (hb_font_t *font,
   return font->get_glyph_advance_for_direction (glyph, direction, x, y);
 }
 
+/**
+ * hb_font_get_glyph_origin_for_direction:
+ * @font: a font.
+ * @glyph: 
+ * @direction: 
+ * @x: (out): 
+ * @y: (out): 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_get_glyph_origin_for_direction (hb_font_t *font,
 					hb_codepoint_t glyph,
@@ -441,6 +681,18 @@ hb_font_get_glyph_origin_for_direction (hb_font_t *font,
   return font->get_glyph_origin_for_direction (glyph, direction, x, y);
 }
 
+/**
+ * hb_font_add_glyph_origin_for_direction:
+ * @font: a font.
+ * @glyph: 
+ * @direction: 
+ * @x: (out): 
+ * @y: (out): 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_add_glyph_origin_for_direction (hb_font_t *font,
 					hb_codepoint_t glyph,
@@ -450,6 +702,18 @@ hb_font_add_glyph_origin_for_direction (hb_font_t *font,
   return font->add_glyph_origin_for_direction (glyph, direction, x, y);
 }
 
+/**
+ * hb_font_subtract_glyph_origin_for_direction:
+ * @font: a font.
+ * @glyph: 
+ * @direction: 
+ * @x: (out): 
+ * @y: (out): 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_subtract_glyph_origin_for_direction (hb_font_t *font,
 					     hb_codepoint_t glyph,
@@ -459,6 +723,19 @@ hb_font_subtract_glyph_origin_for_direction (hb_font_t *font,
   return font->subtract_glyph_origin_for_direction (glyph, direction, x, y);
 }
 
+/**
+ * hb_font_get_glyph_kerning_for_direction:
+ * @font: a font.
+ * @first_glyph: 
+ * @second_glyph: 
+ * @direction: 
+ * @x: (out): 
+ * @y: (out): 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_get_glyph_kerning_for_direction (hb_font_t *font,
 					 hb_codepoint_t first_glyph, hb_codepoint_t second_glyph,
@@ -468,6 +745,19 @@ hb_font_get_glyph_kerning_for_direction (hb_font_t *font,
   return font->get_glyph_kerning_for_direction (first_glyph, second_glyph, direction, x, y);
 }
 
+/**
+ * hb_font_get_glyph_extents_for_origin:
+ * @font: a font.
+ * @glyph: 
+ * @direction: 
+ * @extents: (out): 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_font_get_glyph_extents_for_origin (hb_font_t *font,
 				      hb_codepoint_t glyph,
@@ -477,6 +767,21 @@ hb_font_get_glyph_extents_for_origin (hb_font_t *font,
   return font->get_glyph_extents_for_origin (glyph, direction, extents);
 }
 
+/**
+ * hb_font_get_glyph_contour_point_for_origin:
+ * @font: a font.
+ * @glyph: 
+ * @point_index: 
+ * @direction: 
+ * @x: (out): 
+ * @y: (out): 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_font_get_glyph_contour_point_for_origin (hb_font_t *font,
 					    hb_codepoint_t glyph, unsigned int point_index,
@@ -487,6 +792,17 @@ hb_font_get_glyph_contour_point_for_origin (hb_font_t *font,
 }
 
 /* Generates gidDDD if glyph has no name. */
+/**
+ * hb_font_glyph_to_string:
+ * @font: a font.
+ * @glyph: 
+ * @s: (array length=size): 
+ * @size: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_glyph_to_string (hb_font_t *font,
 			 hb_codepoint_t glyph,
@@ -496,6 +812,19 @@ hb_font_glyph_to_string (hb_font_t *font,
 }
 
 /* Parses gidDDD and uniUUUU strings automatically. */
+/**
+ * hb_font_glyph_from_string:
+ * @font: a font.
+ * @s: (array length=len): 
+ * @len: 
+ * @glyph: (out): 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_font_glyph_from_string (hb_font_t *font,
 			   const char *s, int len, /* -1 means nul-terminated */
@@ -509,6 +838,16 @@ hb_font_glyph_from_string (hb_font_t *font,
  * hb_font_t
  */
 
+/**
+ * hb_font_create: (constructor)
+ * @face: a face.
+ *
+ * 
+ *
+ * Return value: (transfer full): 
+ *
+ * Since: 1.0
+ **/
 hb_font_t *
 hb_font_create (hb_face_t *face)
 {
@@ -528,6 +867,16 @@ hb_font_create (hb_face_t *face)
   return font;
 }
 
+/**
+ * hb_font_create_sub_font:
+ * @parent: parent font.
+ *
+ * 
+ *
+ * Return value: (transfer full): 
+ *
+ * Since: 1.0
+ **/
 hb_font_t *
 hb_font_create_sub_font (hb_font_t *parent)
 {
@@ -550,6 +899,15 @@ hb_font_create_sub_font (hb_font_t *parent)
   return font;
 }
 
+/**
+ * hb_font_get_empty:
+ *
+ * 
+ *
+ * Return value: (transfer full)
+ *
+ * Since: 1.0
+ **/
 hb_font_t *
 hb_font_get_empty (void)
 {
@@ -581,12 +939,30 @@ hb_font_get_empty (void)
   return const_cast<hb_font_t *> (&_hb_font_nil);
 }
 
+/**
+ * hb_font_reference: (skip)
+ * @font: a font.
+ *
+ * 
+ *
+ * Return value: (transfer full): 
+ *
+ * Since: 1.0
+ **/
 hb_font_t *
 hb_font_reference (hb_font_t *font)
 {
   return hb_object_reference (font);
 }
 
+/**
+ * hb_font_destroy: (skip)
+ * @font: a font.
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_destroy (hb_font_t *font)
 {
@@ -606,6 +982,20 @@ hb_font_destroy (hb_font_t *font)
   free (font);
 }
 
+/**
+ * hb_font_set_user_data: (skip)
+ * @font: a font.
+ * @key: 
+ * @data: 
+ * @destroy: 
+ * @replace: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_font_set_user_data (hb_font_t          *font,
 		       hb_user_data_key_t *key,
@@ -616,6 +1006,17 @@ hb_font_set_user_data (hb_font_t          *font,
   return hb_object_set_user_data (font, key, data, destroy, replace);
 }
 
+/**
+ * hb_font_get_user_data: (skip)
+ * @font: a font.
+ * @key: 
+ *
+ * 
+ *
+ * Return value: (transfer none): 
+ *
+ * Since: 1.0
+ **/
 void *
 hb_font_get_user_data (hb_font_t          *font,
 		       hb_user_data_key_t *key)
@@ -623,6 +1024,14 @@ hb_font_get_user_data (hb_font_t          *font,
   return hb_object_get_user_data (font, key);
 }
 
+/**
+ * hb_font_make_immutable:
+ * @font: a font.
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_make_immutable (hb_font_t *font)
 {
@@ -632,18 +1041,48 @@ hb_font_make_immutable (hb_font_t *font)
   font->immutable = true;
 }
 
+/**
+ * hb_font_is_immutable:
+ * @font: a font.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_font_is_immutable (hb_font_t *font)
 {
   return font->immutable;
 }
 
+/**
+ * hb_font_get_parent:
+ * @font: a font.
+ *
+ * 
+ *
+ * Return value: (transfer none): 
+ *
+ * Since: 1.0
+ **/
 hb_font_t *
 hb_font_get_parent (hb_font_t *font)
 {
   return font->parent;
 }
 
+/**
+ * hb_font_get_face:
+ * @font: a font.
+ *
+ * 
+ *
+ * Return value: (transfer none): 
+ *
+ * Since: 1.0
+ **/
 hb_face_t *
 hb_font_get_face (hb_font_t *font)
 {
@@ -651,6 +1090,17 @@ hb_font_get_face (hb_font_t *font)
 }
 
 
+/**
+ * hb_font_set_funcs:
+ * @font: a font.
+ * @klass: 
+ * @user_data: 
+ * @destroy: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_set_funcs (hb_font_t         *font,
 		   hb_font_funcs_t   *klass,
@@ -676,6 +1126,16 @@ hb_font_set_funcs (hb_font_t         *font,
   font->destroy = destroy;
 }
 
+/**
+ * hb_font_set_funcs_data:
+ * @font: a font.
+ * @user_data: 
+ * @destroy: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_set_funcs_data (hb_font_t         *font,
 		        void              *user_data,
@@ -696,6 +1156,16 @@ hb_font_set_funcs_data (hb_font_t         *font,
 }
 
 
+/**
+ * hb_font_set_scale:
+ * @font: a font.
+ * @x_scale: 
+ * @y_scale: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_set_scale (hb_font_t *font,
 		   int x_scale,
@@ -708,6 +1178,16 @@ hb_font_set_scale (hb_font_t *font,
   font->y_scale = y_scale;
 }
 
+/**
+ * hb_font_get_scale:
+ * @font: a font.
+ * @x_scale: (out): 
+ * @y_scale: (out): 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_get_scale (hb_font_t *font,
 		   int *x_scale,
@@ -717,6 +1197,16 @@ hb_font_get_scale (hb_font_t *font,
   if (y_scale) *y_scale = font->y_scale;
 }
 
+/**
+ * hb_font_set_ppem:
+ * @font: a font.
+ * @x_ppem: 
+ * @y_ppem: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_set_ppem (hb_font_t *font,
 		  unsigned int x_ppem,
@@ -729,6 +1219,16 @@ hb_font_set_ppem (hb_font_t *font,
   font->y_ppem = y_ppem;
 }
 
+/**
+ * hb_font_get_ppem:
+ * @font: a font.
+ * @x_ppem: (out): 
+ * @y_ppem: (out): 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_font_get_ppem (hb_font_t *font,
 		  unsigned int *x_ppem,
diff --git a/src/hb-set.cc b/src/hb-set.cc
index 054eb5ad3..161924e08 100644
--- a/src/hb-set.cc
+++ b/src/hb-set.cc
@@ -53,7 +53,7 @@ hb_set_create (void)
 /**
  * hb_set_get_empty:
  *
- * Return value: (transfer none):
+ * Return value: (transfer full):
  *
  * Since: 1.0
  **/
diff --git a/src/hb-shape-plan.cc b/src/hb-shape-plan.cc
index a6d2d2621..4e734d70d 100644
--- a/src/hb-shape-plan.cc
+++ b/src/hb-shape-plan.cc
@@ -83,6 +83,20 @@ hb_shape_plan_plan (hb_shape_plan_t    *shape_plan,
  * hb_shape_plan_t
  */
 
+/**
+ * hb_shape_plan_create: (constructor)
+ * @face: 
+ * @props: 
+ * @user_features: (array length=num_user_features):
+ * @num_user_features: 
+ * @shaper_list: (array zero-terminated=1):
+ *
+ * 
+ *
+ * Return value: (transfer full):
+ *
+ * Since: 1.0
+ **/
 hb_shape_plan_t *
 hb_shape_plan_create (hb_face_t                     *face,
 		      const hb_segment_properties_t *props,
@@ -111,6 +125,15 @@ hb_shape_plan_create (hb_face_t                     *face,
   return shape_plan;
 }
 
+/**
+ * hb_shape_plan_get_empty:
+ *
+ * 
+ *
+ * Return value: (transfer full):
+ *
+ * Since: 1.0
+ **/
 hb_shape_plan_t *
 hb_shape_plan_get_empty (void)
 {
@@ -134,12 +157,30 @@ hb_shape_plan_get_empty (void)
   return const_cast<hb_shape_plan_t *> (&_hb_shape_plan_nil);
 }
 
+/**
+ * hb_shape_plan_reference: (skip)
+ * @shape_plan: a shape plan.
+ *
+ * 
+ *
+ * Return value: (transfer full):
+ *
+ * Since: 1.0
+ **/
 hb_shape_plan_t *
 hb_shape_plan_reference (hb_shape_plan_t *shape_plan)
 {
   return hb_object_reference (shape_plan);
 }
 
+/**
+ * hb_shape_plan_destroy: (skip)
+ * @shape_plan: a shape plan.
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_shape_plan_destroy (hb_shape_plan_t *shape_plan)
 {
@@ -154,6 +195,20 @@ hb_shape_plan_destroy (hb_shape_plan_t *shape_plan)
   free (shape_plan);
 }
 
+/**
+ * hb_shape_plan_set_user_data: (skip)
+ * @shape_plan: a shape plan.
+ * @key: 
+ * @data: 
+ * @destroy: 
+ * @replace: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_shape_plan_set_user_data (hb_shape_plan_t    *shape_plan,
 			     hb_user_data_key_t *key,
@@ -164,6 +219,17 @@ hb_shape_plan_set_user_data (hb_shape_plan_t    *shape_plan,
   return hb_object_set_user_data (shape_plan, key, data, destroy, replace);
 }
 
+/**
+ * hb_shape_plan_get_user_data: (skip)
+ * @shape_plan: a shape plan.
+ * @key: 
+ *
+ * 
+ *
+ * Return value: (transfer none):
+ *
+ * Since: 1.0
+ **/
 void *
 hb_shape_plan_get_user_data (hb_shape_plan_t    *shape_plan,
 			     hb_user_data_key_t *key)
@@ -172,6 +238,20 @@ hb_shape_plan_get_user_data (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: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_shape_plan_execute (hb_shape_plan_t    *shape_plan,
 		       hb_font_t          *font,
@@ -238,6 +318,20 @@ hb_shape_plan_matches (const hb_shape_plan_t          *shape_plan,
 	  (shape_plan->shaper_func == proposal->shaper_func));
 }
 
+/**
+ * hb_shape_plan_create_cached:
+ * @face: 
+ * @props: 
+ * @user_features: (array length=num_user_features):
+ * @num_user_features: 
+ * @shaper_list: (array zero-terminated=1):
+ *
+ * 
+ *
+ * Return value: (transfer full):
+ *
+ * Since: 1.0
+ **/
 hb_shape_plan_t *
 hb_shape_plan_create_cached (hb_face_t                     *face,
 			     const hb_segment_properties_t *props,
@@ -307,6 +401,16 @@ retry:
   return hb_shape_plan_reference (shape_plan);
 }
 
+/**
+ * hb_shape_plan_get_shaper:
+ * @shape_plan: a shape plan.
+ *
+ * 
+ *
+ * Return value: (transfer none):
+ *
+ * Since: 1.0
+ **/
 const char *
 hb_shape_plan_get_shaper (hb_shape_plan_t *shape_plan)
 {
diff --git a/src/hb-shape.cc b/src/hb-shape.cc
index 80d8c1306..c1b752405 100644
--- a/src/hb-shape.cc
+++ b/src/hb-shape.cc
@@ -153,6 +153,18 @@ parse_one_feature (const char **pp, const char *end, hb_feature_t *feature)
 	 *pp == end;
 }
 
+/**
+ * hb_feature_from_string:
+ * @str: (array length=len):
+ * @len: 
+ * @feature: (out):
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_feature_from_string (const char *str, int len,
 			hb_feature_t *feature)
@@ -163,6 +175,16 @@ hb_feature_from_string (const char *str, int len,
   return parse_one_feature (&str, str + len, feature);
 }
 
+/**
+ * hb_feature_to_string:
+ * @feature: 
+ * @buf: (array length=size):
+ * @size: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_feature_to_string (hb_feature_t *feature,
 		      char *buf, unsigned int size)
@@ -209,6 +231,15 @@ void free_static_shaper_list (void)
   free (static_shaper_list);
 }
 
+/**
+ * hb_shape_list_shapers:
+ *
+ * 
+ *
+ * Return value: (transfer none):
+ *
+ * Since: 1.0
+ **/
 const char **
 hb_shape_list_shapers (void)
 {
@@ -244,6 +275,20 @@ retry:
 }
 
 
+/**
+ * hb_shape_full:
+ * @font: a font.
+ * @buffer: a buffer.
+ * @features: (array length=num_features):
+ * @num_features: 
+ * @shaper_list: (array zero-terminated=1):
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_shape_full (hb_font_t          *font,
 	       hb_buffer_t        *buffer,
@@ -265,6 +310,17 @@ hb_shape_full (hb_font_t          *font,
   return res;
 }
 
+/**
+ * hb_shape:
+ * @font: a font.
+ * @buffer: a buffer.
+ * @features: (array length=num_features):
+ * @num_features: 
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_shape (hb_font_t           *font,
 	  hb_buffer_t         *buffer,
diff --git a/src/hb-unicode.cc b/src/hb-unicode.cc
index b7e098737..807d5c1ff 100644
--- a/src/hb-unicode.cc
+++ b/src/hb-unicode.cc
@@ -150,6 +150,16 @@ hb_unicode_funcs_get_default (void)
 #pragma message("To suppress this warnings, define HB_NO_UNICODE_FUNCS.")
 #endif
 
+/**
+ * hb_unicode_funcs_create: (constructor)
+ * @parent: (allow-none):
+ *
+ * 
+ *
+ * Return value: (transfer full):
+ *
+ * Since: 1.0
+ **/
 hb_unicode_funcs_t *
 hb_unicode_funcs_create (hb_unicode_funcs_t *parent)
 {
@@ -187,18 +197,45 @@ const hb_unicode_funcs_t _hb_unicode_funcs_nil = {
   }
 };
 
+/**
+ * hb_unicode_funcs_get_empty:
+ *
+ * 
+ *
+ * Return value: (transfer full):
+ *
+ * Since: 1.0
+ **/
 hb_unicode_funcs_t *
 hb_unicode_funcs_get_empty (void)
 {
   return const_cast<hb_unicode_funcs_t *> (&_hb_unicode_funcs_nil);
 }
 
+/**
+ * hb_unicode_funcs_reference: (skip)
+ * @ufuncs: Unicode functions.
+ *
+ * 
+ *
+ * Return value: (transfer full):
+ *
+ * Since: 1.0
+ **/
 hb_unicode_funcs_t *
 hb_unicode_funcs_reference (hb_unicode_funcs_t *ufuncs)
 {
   return hb_object_reference (ufuncs);
 }
 
+/**
+ * hb_unicode_funcs_destroy: (skip)
+ * @ufuncs: Unicode functions.
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_unicode_funcs_destroy (hb_unicode_funcs_t *ufuncs)
 {
@@ -214,6 +251,20 @@ hb_unicode_funcs_destroy (hb_unicode_funcs_t *ufuncs)
   free (ufuncs);
 }
 
+/**
+ * hb_unicode_funcs_set_user_data: (skip)
+ * @ufuncs: Unicode functions.
+ * @key: 
+ * @data: 
+ * @destroy: 
+ * @replace: 
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_unicode_funcs_set_user_data (hb_unicode_funcs_t *ufuncs,
 			        hb_user_data_key_t *key,
@@ -224,6 +275,17 @@ hb_unicode_funcs_set_user_data (hb_unicode_funcs_t *ufuncs,
   return hb_object_set_user_data (ufuncs, key, data, destroy, replace);
 }
 
+/**
+ * hb_unicode_funcs_get_user_data: (skip)
+ * @ufuncs: Unicode functions.
+ * @key: 
+ *
+ * 
+ *
+ * Return value: (transfer none):
+ *
+ * Since: 1.0
+ **/
 void *
 hb_unicode_funcs_get_user_data (hb_unicode_funcs_t *ufuncs,
 			        hb_user_data_key_t *key)
@@ -232,6 +294,14 @@ hb_unicode_funcs_get_user_data (hb_unicode_funcs_t *ufuncs,
 }
 
 
+/**
+ * hb_unicode_funcs_make_immutable:
+ * @ufuncs: Unicode functions.
+ *
+ * 
+ *
+ * Since: 1.0
+ **/
 void
 hb_unicode_funcs_make_immutable (hb_unicode_funcs_t *ufuncs)
 {
@@ -241,12 +311,32 @@ hb_unicode_funcs_make_immutable (hb_unicode_funcs_t *ufuncs)
   ufuncs->immutable = true;
 }
 
+/**
+ * hb_unicode_funcs_is_immutable:
+ * @ufuncs: Unicode functions.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_unicode_funcs_is_immutable (hb_unicode_funcs_t *ufuncs)
 {
   return ufuncs->immutable;
 }
 
+/**
+ * hb_unicode_funcs_get_parent:
+ * @ufuncs: Unicode functions.
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_unicode_funcs_t *
 hb_unicode_funcs_get_parent (hb_unicode_funcs_t *ufuncs)
 {
@@ -294,6 +384,19 @@ hb_unicode_##name (hb_unicode_funcs_t *ufuncs,					\
 HB_UNICODE_FUNCS_IMPLEMENT_CALLBACKS_SIMPLE
 #undef HB_UNICODE_FUNC_IMPLEMENT
 
+/**
+ * hb_unicode_compose:
+ * @ufuncs: Unicode functions.
+ * @a: 
+ * @b: 
+ * @ab: (out):
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_unicode_compose (hb_unicode_funcs_t *ufuncs,
 		    hb_codepoint_t      a,
@@ -303,6 +406,19 @@ hb_unicode_compose (hb_unicode_funcs_t *ufuncs,
   return ufuncs->compose (a, b, ab);
 }
 
+/**
+ * hb_unicode_decompose:
+ * @ufuncs: Unicode functions.
+ * @ab: 
+ * @a: (out):
+ * @b: (out):
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 hb_bool_t
 hb_unicode_decompose (hb_unicode_funcs_t *ufuncs,
 		      hb_codepoint_t      ab,
@@ -312,6 +428,18 @@ hb_unicode_decompose (hb_unicode_funcs_t *ufuncs,
   return ufuncs->decompose (ab, a, b);
 }
 
+/**
+ * hb_unicode_decompose_compatibility:
+ * @ufuncs: Unicode functions.
+ * @u: 
+ * @decomposed: (out):
+ *
+ * 
+ *
+ * Return value: 
+ *
+ * Since: 1.0
+ **/
 unsigned int
 hb_unicode_decompose_compatibility (hb_unicode_funcs_t *ufuncs,
 				    hb_codepoint_t      u,