diff --git a/docs/harfbuzz-sections.txt b/docs/harfbuzz-sections.txt
index 0cb2568..3e7efed 100644
--- a/docs/harfbuzz-sections.txt
+++ b/docs/harfbuzz-sections.txt
@@ -39,26 +39,26 @@
 hb_buffer_add_utf16
 hb_buffer_add_utf8
 hb_buffer_set_content_type
-hb_buffer_set_direction
-hb_buffer_set_flags
-hb_buffer_set_language
-hb_buffer_set_length
-hb_buffer_set_script
-hb_buffer_set_segment_properties
-hb_buffer_set_unicode_funcs
-hb_buffer_set_user_data
-hb_buffer_guess_segment_properties
 hb_buffer_get_content_type
+hb_buffer_set_direction
 hb_buffer_get_direction
+hb_buffer_set_script
+hb_buffer_get_script
+hb_buffer_set_language
+hb_buffer_get_language
+hb_buffer_set_flags
 hb_buffer_get_flags
+hb_buffer_set_length
+hb_buffer_get_length
+hb_buffer_set_segment_properties
+hb_buffer_guess_segment_properties
+hb_buffer_get_segment_properties
+hb_buffer_set_unicode_funcs
+hb_buffer_get_unicode_funcs
+hb_buffer_set_user_data
+hb_buffer_get_user_data
 hb_buffer_get_glyph_infos
 hb_buffer_get_glyph_positions
-hb_buffer_get_language
-hb_buffer_get_length
-hb_buffer_get_script
-hb_buffer_get_segment_properties
-hb_buffer_get_unicode_funcs
-hb_buffer_get_user_data
 hb_buffer_normalize_glyphs
 hb_buffer_reverse
 hb_buffer_reverse_clusters
@@ -81,39 +81,39 @@
 
 <SECTION>
 <FILE>hb-common</FILE>
-HB_DIRECTION_REVERSE
-HB_LANGUAGE_INVALID
+hb_tag_from_string
+hb_tag_to_string
+hb_direction_from_string
+hb_direction_to_string
+hb_script_from_iso15924_tag
+hb_script_from_string
+hb_script_to_iso15924_tag
+hb_script_get_horizontal_direction
+hb_language_from_string
+hb_language_to_string
+hb_language_get_default
+hb_bool_t
+hb_codepoint_t
+hb_destroy_func_t
+hb_direction_t
+hb_language_t
+hb_mask_t
+hb_position_t
+hb_tag_t
+hb_script_t
+hb_user_data_key_t
+hb_var_int_t
 HB_TAG
 HB_TAG_NONE
 HB_TAG_MAX
 HB_UNTAG
-hb_bool_t
-hb_codepoint_t
-hb_destroy_func_t
-hb_direction_from_string
-hb_direction_t
-hb_direction_to_string
-hb_language_from_string
-hb_language_get_default
-hb_language_t
-hb_language_to_string
-hb_mask_t
-hb_position_t
-hb_script_from_iso15924_tag
-hb_script_from_string
-hb_script_get_horizontal_direction
-hb_script_t
-hb_script_to_iso15924_tag
-hb_tag_from_string
-hb_tag_t
-hb_tag_to_string
-hb_user_data_key_t
-hb_var_int_t
+HB_DIRECTION_REVERSE
 HB_DIRECTION_IS_BACKWARD
 HB_DIRECTION_IS_FORWARD
 HB_DIRECTION_IS_HORIZONTAL
 HB_DIRECTION_IS_VALID
 HB_DIRECTION_IS_VERTICAL
+HB_LANGUAGE_INVALID
 <SUBSECTION Private>
 HB_BEGIN_DECLS
 HB_END_DECLS
diff --git a/src/hb-buffer.cc b/src/hb-buffer.cc
index ff3e655..dc7124f 100644
--- a/src/hb-buffer.cc
+++ b/src/hb-buffer.cc
@@ -787,7 +787,7 @@
  * being destroyed until a matching call to hb_buffer_destroy() is made.
  *
  * Return value: (transfer full):
- * the referenced #hb_buffer_t.
+ * The referenced #hb_buffer_t.
  *
  * Since: 0.9.2
  **/
@@ -868,9 +868,10 @@
 /**
  * hb_buffer_set_content_type:
  * @buffer: an #hb_buffer_t.
- * @content_type: 
+ * @content_type: the type of buffer contents to set
  *
- * 
+ * Sets the type of @buffer contents, buffers are either empty, contain
+ * characters (before shaping) or glyphs (the result of shaping).
  *
  * Since: 0.9.5
  **/
@@ -885,9 +886,10 @@
  * hb_buffer_get_content_type:
  * @buffer: an #hb_buffer_t.
  *
- * 
+ * see hb_buffer_set_content_type().
  *
- * Return value: 
+ * Return value:
+ * The type of @buffer contents.
  *
  * Since: 0.9.5
  **/
@@ -942,9 +944,15 @@
 /**
  * hb_buffer_set_direction:
  * @buffer: an #hb_buffer_t.
- * @direction: 
+ * @direction: the #hb_direction_t of the @buffer
  *
- * 
+ * Set the text flow direction of the buffer. No shaping can happen without
+ * setting @buffer direction, and it controls the visual direction for the
+ * output glyphs; for RTL direction the glyphs will be reversed. Many layout
+ * features depend on the proper setting of the direction, for example,
+ * reversing RTL text before shaping, then shaping with LTR direction is not
+ * the same as keeping the text in logical order and shaping with RTL
+ * direction.
  *
  * Since: 0.9.2
  **/
@@ -963,9 +971,10 @@
  * hb_buffer_get_direction:
  * @buffer: an #hb_buffer_t.
  *
- * 
+ * See hb_buffer_set_direction()
  *
- * Return value: 
+ * Return value:
+ * The direction of the @buffer.
  *
  * Since: 0.9.2
  **/
@@ -978,9 +987,17 @@
 /**
  * hb_buffer_set_script:
  * @buffer: an #hb_buffer_t.
- * @script: 
+ * @script: an #hb_script_t to set.
  *
- * 
+ * Sets the script of @buffer to @script.
+ *
+ * Script is crucial for choosing the proper shaping behaviour for scripts that
+ * require it (e.g. Arabic) and the which OpenType features defined in the font
+ * to be applied.
+ *
+ * You can pass one of the predefined #hb_script_t values, or use
+ * hb_script_from_string() or hb_script_from_iso15924_tag() to get the
+ * corresponding script from an ISO 15924 script tag.
  *
  * Since: 0.9.2
  **/
@@ -998,9 +1015,10 @@
  * hb_buffer_get_script:
  * @buffer: an #hb_buffer_t.
  *
- * 
+ * See hb_buffer_set_script().
  *
- * Return value: 
+ * Return value:
+ * The #hb_script_t of the @buffer.
  *
  * Since: 0.9.2
  **/
@@ -1013,9 +1031,17 @@
 /**
  * hb_buffer_set_language:
  * @buffer: an #hb_buffer_t.
- * @language: 
+ * @language: an hb_language_t to set.
  *
- * 
+ * Sets the language of @buffer to @language.
+ *
+ * Languages are crucial for selecting which OpenType feature to apply to the
+ * buffer which can result in applying language-specific behaviour. Languages
+ * are orthogonal to the scripts, and though they are related, they are
+ * different concepts and should not be confused with each other.
+ *
+ * Use hb_language_from_string() to convert from ISO 639 language codes to
+ * #hb_language_t.
  *
  * Since: 0.9.2
  **/
@@ -1033,9 +1059,10 @@
  * hb_buffer_get_language:
  * @buffer: an #hb_buffer_t.
  *
- * 
+ * See hb_buffer_set_language().
  *
  * Return value: (transfer none):
+ * The #hb_language_t of the buffer. Must not be freed by the caller.
  *
  * Since: 0.9.2
  **/
@@ -1192,7 +1219,8 @@
  * hb_buffer_reset:
  * @buffer: an #hb_buffer_t.
  *
- * 
+ * Resets the buffer to its initial status, just like new buffers returned from
+ * hb_buffer_create().
  *
  * Since: 0.9.2
  **/
@@ -1206,7 +1234,7 @@
  * hb_buffer_clear_contents:
  * @buffer: an #hb_buffer_t.
  *
- * 
+ * Clears the contents of the buffer without resetting other properties.
  *
  * Since: 0.9.11
  **/
@@ -1219,11 +1247,12 @@
 /**
  * hb_buffer_pre_allocate:
  * @buffer: an #hb_buffer_t.
- * @size: 
+ * @size: number of items to pre allocate.
  *
- * 
+ * Pre allocates memory for @buffer to fit at least @size number of items.
  *
- * Return value: 
+ * Return value:
+ * %true if the memory pre allocation succeeded, %false otherwise.
  *
  * Since: 0.9.2
  **/
@@ -1237,9 +1266,10 @@
  * hb_buffer_allocation_successful:
  * @buffer: an #hb_buffer_t.
  *
- * 
+ * Check if allocating memory for the buffer succeeded.
  *
- * Return value: 
+ * Return value:
+ * %true if memory allocation succeeded, %false otherwise.
  *
  * Since: 0.9.2
  **/
@@ -1318,7 +1348,8 @@
  *
  * Returns the number of items in the buffer.
  *
- * Return value: buffer length.
+ * Return value:
+ * The @buffer length.
  *
  * Since: 0.9.2
  **/
@@ -1333,10 +1364,11 @@
  * @buffer: an #hb_buffer_t.
  * @length: (out): output array length.
  *
- * Returns buffer glyph information array.  Returned pointer
- * is valid as long as buffer contents are not modified.
+ * Returns @buffer glyph information array.  Returned pointer
+ * is valid as long as @buffer contents are not modified.
  *
- * Return value: (transfer none) (array length=length): buffer glyph information array.
+ * Return value: (transfer none) (array length=length):
+ * The @buffer glyph information array.
  *
  * Since: 0.9.2
  **/
@@ -1355,10 +1387,11 @@
  * @buffer: an #hb_buffer_t.
  * @length: (out): output length.
  *
- * Returns buffer glyph position array.  Returned pointer
- * is valid as long as buffer contents are not modified.
+ * Returns @buffer glyph position array.  Returned pointer
+ * is valid as long as @buffer contents are not modified.
  *
- * Return value: (transfer none) (array length=length): buffer glyph position array.
+ * Return value: (transfer none) (array length=length):
+ * The @buffer glyph position array.
  *
  * Since: 0.9.2
  **/
diff --git a/src/hb-buffer.h b/src/hb-buffer.h
index a28d47f..e24ffa4 100644
--- a/src/hb-buffer.h
+++ b/src/hb-buffer.h
@@ -115,7 +115,12 @@
 hb_buffer_get_user_data (hb_buffer_t        *buffer,
 			 hb_user_data_key_t *key);
 
-
+/**
+ * hb_buffer_content_type_t:
+ * @HB_BUFFER_CONTENT_TYPE_INVALID: Initial value for new buffer.
+ * @HB_BUFFER_CONTENT_TYPE_UNICODE: The buffer contains input characters (before shaping).
+ * @HB_BUFFER_CONTENT_TYPE_GLYPHS: The buffer contains output glyphs (after shaping).
+ */
 typedef enum {
   HB_BUFFER_CONTENT_TYPE_INVALID = 0,
   HB_BUFFER_CONTENT_TYPE_UNICODE,
diff --git a/src/hb-common.cc b/src/hb-common.cc
index 710b36e..e091190 100644
--- a/src/hb-common.cc
+++ b/src/hb-common.cc
@@ -281,12 +281,15 @@
 
 /**
  * hb_language_from_string:
- * @str: (array length=len) (element-type uint8_t): 
- * @len: 
+ * @str: (array length=len) (element-type uint8_t): a string representing
+ *       ISO 639 language code
+ * @len: length of the @str, or -1 if it is %NULL-terminated.
  *
- * 
+ * Converts @str representing an ISO 639 language code to the corresponding
+ * #hb_language_t.
  *
  * Return value: (transfer none):
+ * The #hb_language_t corresponding to the ISO 639 language code.
  *
  * Since: 0.9.2
  **/
@@ -314,11 +317,13 @@
 
 /**
  * hb_language_to_string:
- * @language: 
+ * @language: an #hb_language_t to convert.
  *
- * 
+ * See hb_language_from_string().
  *
- * Return value: (transfer none): 
+ * Return value: (transfer none):
+ * A %NULL-terminated string representing the @language. Must not be freed by
+ * the caller.
  *
  * Since: 0.9.2
  **/
@@ -357,11 +362,12 @@
 
 /**
  * hb_script_from_iso15924_tag:
- * @tag: 
+ * @tag: an #hb_tag_t representing an ISO 15924 tag.
  *
- * 
+ * Converts an ISO 15924 script tag to a corresponding #hb_script_t.
  *
  * Return value: 
+ * An #hb_script_t corresponding to the ISO 15924 tag.
  *
  * Since: 0.9.2
  **/
@@ -401,28 +407,33 @@
 
 /**
  * hb_script_from_string:
- * @s: (array length=len) (element-type uint8_t): 
- * @len: 
+ * @str: (array length=len) (element-type uint8_t): a string representing an
+ *       ISO 15924 tag.
+ * @len: length of the @str, or -1 if it is %NULL-terminated.
  *
- * 
+ * Converts a string @str representing an ISO 15924 script tag to a
+ * corresponding #hb_script_t. Shorthand for hb_tag_from_string() then
+ * hb_script_from_iso15924_tag().
  *
  * Return value: 
+ * An #hb_script_t corresponding to the ISO 15924 tag.
  *
  * Since: 0.9.2
  **/
 hb_script_t
-hb_script_from_string (const char *s, int len)
+hb_script_from_string (const char *str, int len)
 {
-  return hb_script_from_iso15924_tag (hb_tag_from_string (s, len));
+  return hb_script_from_iso15924_tag (hb_tag_from_string (str, len));
 }
 
 /**
  * hb_script_to_iso15924_tag:
- * @script: 
+ * @script: an #hb_script_ to convert.
  *
- * 
+ * See hb_script_from_iso15924_tag().
  *
- * Return value: 
+ * Return value:
+ * An #hb_tag_t representing an ISO 15924 script tag.
  *
  * Since: 0.9.2
  **/
diff --git a/src/hb-common.h b/src/hb-common.h
index af17d78..5b0a0b6 100644
--- a/src/hb-common.h
+++ b/src/hb-common.h
@@ -106,8 +106,14 @@
 hb_tag_to_string (hb_tag_t tag, char *buf);
 
 
-/* hb_direction_t */
-
+/**
+ * hb_direction_t:
+ * @HB_DIRECTION_INVALID: Initial, unset direction.
+ * @HB_DIRECTION_LTR: Text is set horizontally from left to right.
+ * @HB_DIRECTION_RTL: Text is set horizontally from right to left.
+ * @HB_DIRECTION_TTB: Text is set vertically from top to bottom.
+ * @HB_DIRECTION_BTT: Text is set vertically from bottom to top.
+ */
 typedef enum {
   HB_DIRECTION_INVALID = 0,
   HB_DIRECTION_LTR = 4,
@@ -136,7 +142,6 @@
 
 typedef const struct hb_language_impl_t *hb_language_t;
 
-/* len=-1 means str is NUL-terminated */
 HB_EXTERN hb_language_t
 hb_language_from_string (const char *str, int len);
 
@@ -327,10 +332,8 @@
 HB_EXTERN hb_script_t
 hb_script_from_iso15924_tag (hb_tag_t tag);
 
-/* sugar for tag_from_string() then script_from_iso15924_tag */
-/* len=-1 means s is NUL-terminated */
 HB_EXTERN hb_script_t
-hb_script_from_string (const char *s, int len);
+hb_script_from_string (const char *str, int len);
 
 HB_EXTERN hb_tag_t
 hb_script_to_iso15924_tag (hb_script_t script);