[docs] More buffers documentation

docs/harfbuzz-sections.txt

@@ -56,8 +56,8 @@ hb_buffer_get_cluster_level
 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_guess_segment_properties
 hb_buffer_set_unicode_funcs
 hb_buffer_get_unicode_funcs
 hb_buffer_set_user_data
@@ -84,9 +84,9 @@ hb_glyph_position_t
 hb_buffer_content_type_t
 hb_buffer_flags_t
 hb_buffer_cluster_level_t
-hb_buffer_serialize_flags_t
 hb_segment_properties_t
 hb_buffer_serialize_format_t
+hb_buffer_serialize_flags_t
 hb_buffer_message_func_t
 </SECTION>
 

src/hb-buffer-serialize.cc

@@ -36,11 +36,12 @@ static const char *serialize_formats[] = {
 /**
  * hb_buffer_serialize_list_formats:
  *
- * 
+ * Returns a list of supported buffer serialization formats.
  *
  * Return value: (transfer none):
+ * A string array of buffer serialization formats. Should not be freed.
  *
- * Since: 0.9.2
+ * Since: 0.9.7
  **/
 const char **
 hb_buffer_serialize_list_formats (void)
@@ -50,14 +51,17 @@ hb_buffer_serialize_list_formats (void)
 
 /**
  * hb_buffer_serialize_format_from_string:
- * @str: 
+ * @str: (array length=len) (element-type uint8_t): a string to parse
- * @len: 
+ * @len: length of @str, or -1 if string is %NULL terminated
- *
  *
+ * Parses a string into an #hb_buffer_serialize_format_t. Does not check if
+ * @str is a valid buffer serialization format, use
+ * hb_buffer_serialize_list_formats() to get the list of supported formats.
  *
  * Return value: 
+ * The parsed #hb_buffer_serialize_format_t.
  *
- * Since: 0.9.2
+ * Since: 0.9.7
  **/
 hb_buffer_serialize_format_t
 hb_buffer_serialize_format_from_string (const char *str, int len)
@@ -68,13 +72,15 @@ hb_buffer_serialize_format_from_string (const char *str, int len)
 
 /**
  * hb_buffer_serialize_format_to_string:
- * @format: 
+ * @format: an #hb_buffer_serialize_format_t to convert.
  *
+ * Converts @format to the string corresponding it, or %NULL if it is not a valid
+ * #hb_buffer_serialize_format_t.
  *
+ * Return value: (transfer none):
+ * A %NULL terminated string corresponding to @format. Should not be freed.
  *
- * Return value: 
+ * Since: 0.9.7
- *
- * Since: 0.9.2
  **/
 const char *
 hb_buffer_serialize_format_to_string (hb_buffer_serialize_format_t format)
@@ -242,24 +248,51 @@ _hb_buffer_serialize_glyphs_text (hb_buffer_t *buffer,
   return end - start;
 }
 
-/* Returns number of items, starting at start, that were serialized. */
 /**
  * hb_buffer_serialize_glyphs:
- * @buffer: a buffer.
+ * @buffer: an #hb_buffer_t buffer.
- * @start: 
+ * @start: the first item in @buffer to serialize.
- * @end: 
+ * @end: the last item in @buffer to serialize.
- * @buf: (array length=buf_size):
+ * @buf: (out) (array length=buf_size) (element-type uint8_t): output string to
- * @buf_size: 
+ *       write serialized buffer into.
- * @buf_consumed: (out):
+ * @buf_size: the size of @buf.
- * @font: 
+ * @buf_consumed: (out) (allow-none): if not %NULL, will be set to the number of byes written into @buf.
- * @format: 
+ * @font: (allow-none): the #hb_font_t used to shape this buffer, needed to
- * @flags: 
+ *        read glyph names and extents. If %NULL, and empty font will be used.
+ * @format: the #hb_buffer_serialize_format_t to use for formatting the output.
+ * @flags: the #hb_buffer_serialize_flags_t that control what glyph properties
+ *         to serialize.
  *
+ * Serializes @buffer into a textual representation of its glyph content,
+ * useful for showing the contents of the buffer, for example during debugging.
+ * There are currently two supported serialization formats:
  *
+ * ## text
+ * A human-readable, plain text format.
+ * The serialized glyphs will look something like:
+ *
+ * ```
+ * [uni0651=0@518,0+0|uni0628=0+1897]
+ * ```
+ * - The serialized glyphs are delimited with `[` and `]`.
+ * - Glyphs are separated with `|`
+ * - Each glyph starts with glyph name, or glyph index if
+ *   #HB_BUFFER_SERIALIZE_FLAG_NO_GLYPH_NAMES flag is set. Then,
+ *   - If #HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS is not set, `=` then #hb_glyph_info_t.cluster.
+ *   - If #HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS is not set, the #hb_glyph_position_t in the format:
+ *     - If both #hb_glyph_position_t.x_offset and #hb_glyph_position_t.y_offset are not 0, `@x_offset,y_offset`. Then,
+ *     - `+x_advance`, then `,y_advance` if #hb_glyph_position_t.y_advance is not 0. Then,
+ *   - If #HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS is set, the
+ *     #hb_glyph_extents_t in the format
+ *     `<x_bearing,y_bearing,width,height>`
+ *
+ * ## json
+ * TODO.
  *
  * Return value: 
+ * The number of serialized items.
  *
- * Since: 0.9.2
+ * Since: 0.9.7
  **/
 unsigned int
 hb_buffer_serialize_glyphs (hb_buffer_t *buffer,
@@ -267,8 +300,8 @@ hb_buffer_serialize_glyphs (hb_buffer_t *buffer,
 			    unsigned int end,
 			    char *buf,
 			    unsigned int buf_size,
-			    unsigned int *buf_consumed, /* May be NULL */
+			    unsigned int *buf_consumed,
-			    hb_font_t *font, /* May be NULL */
+			    hb_font_t *font,
 			    hb_buffer_serialize_format_t format,
 			    hb_buffer_serialize_flags_t flags)
 {
@@ -358,7 +391,7 @@ parse_int (const char *pp, const char *end, int32_t *pv)
 
 /**
  * hb_buffer_deserialize_glyphs:
- * @buffer: a buffer.
+ * @buffer: an #hb_buffer_t buffer.
  * @buf: (array length=buf_len):
  * @buf_len: 
  * @end_ptr: (out):
@@ -369,7 +402,7 @@ parse_int (const char *pp, const char *end, int32_t *pv)
  *
  * Return value: 
  *
- * Since: 0.9.2
+ * Since: 0.9.7
  **/
 hb_bool_t
 hb_buffer_deserialize_glyphs (hb_buffer_t *buffer,

src/hb-buffer.cc

@@ -47,6 +47,13 @@
 
 /**
  * hb_segment_properties_equal:
+ * @a: first #hb_segment_properties_t to compare.
+ * @b: second #hb_segment_properties_t to compare.
+ *
+ * Checks the equality of two #hb_segment_properties_t's.
+ *
+ * Return value: (transfer full):
+ * %true if all properties of @a equal those of @b, false otherwise.
  *
  * Since: 0.9.7
  **/
@@ -64,6 +71,12 @@ hb_segment_properties_equal (const hb_segment_properties_t *a,
 
 /**
  * hb_segment_properties_hash:
+ * @p: #hb_segment_properties_t to hash.
+ *
+ * Creates a hash representing @p.
+ *
+ * Return value:
+ * A hash of @p.
  *
  * Since: 0.9.7
  **/
@@ -1075,9 +1088,11 @@ hb_buffer_get_language (hb_buffer_t *buffer)
 /**
  * hb_buffer_set_segment_properties:
  * @buffer: an #hb_buffer_t.
- * @props: 
+ * @props: an #hb_segment_properties_t to use.
- *
  *
+ * Sets the segment properties of the buffer, a shortcut for calling
+ * hb_buffer_set_direction(), hb_buffer_set_script() and
+ * hb_buffer_set_language() individually.
  *
  * Since: 0.9.7
  **/
@@ -1094,9 +1109,9 @@ hb_buffer_set_segment_properties (hb_buffer_t *buffer,
 /**
  * hb_buffer_get_segment_properties:
  * @buffer: an #hb_buffer_t.
- * @props: (out):
+ * @props: (out): the output #hb_segment_properties_t.
- *
  *
+ * Sets @props to the #hb_segment_properties_t of @buffer.
  *
  * Since: 0.9.7
  **/
@@ -1183,9 +1198,12 @@ hb_buffer_get_cluster_level (hb_buffer_t *buffer)
 /**
  * hb_buffer_set_replacement_codepoint:
  * @buffer: an #hb_buffer_t.
- * @replacement: 
+ * @replacement: the replacement #hb_codepoint_t
  *
+ * Sets the #hb_codepoint_t that replaces invalid entries for a given encoding
+ * when adding text to @buffer.
  *
+ * Default is %HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT.
  *
  * Since: 0.9.31
  **/
@@ -1203,9 +1221,10 @@ hb_buffer_set_replacement_codepoint (hb_buffer_t    *buffer,
  * hb_buffer_get_replacement_codepoint:
  * @buffer: an #hb_buffer_t.
  *
- * 
+ * See hb_buffer_set_replacement_codepoint().
  *
  * Return value: 
+ * The @buffer replacement #hb_codepoint_t.
  *
  * Since: 0.9.31
  **/
@@ -1220,8 +1239,8 @@ hb_buffer_get_replacement_codepoint (hb_buffer_t    *buffer)
  * hb_buffer_reset:
  * @buffer: an #hb_buffer_t.
  *
- * Resets the buffer to its initial status, just like new buffers returned from
+ * Resets the buffer to its initial status, as if it was just newly created
- * hb_buffer_create().
+ * with hb_buffer_create().
  *
  * Since: 0.9.2
  **/
@@ -1235,7 +1254,8 @@ hb_buffer_reset (hb_buffer_t *buffer)
  * hb_buffer_clear_contents:
  * @buffer: an #hb_buffer_t.
  *
- * Clears the contents of the buffer without resetting other properties.
+ * Similar to hb_buffer_reset(), but does not clear the Unicode functions and
+ * the replacement code point.
  *
  * Since: 0.9.11
  **/
@@ -1253,7 +1273,7 @@ hb_buffer_clear_contents (hb_buffer_t *buffer)
  * Pre allocates memory for @buffer to fit at least @size number of items.
  *
  * Return value:
- * %true if the memory pre allocation succeeded, %false otherwise.
+ * %true if @buffer memory allocation succeeded, %false otherwise.
  *
  * Since: 0.9.2
  **/
@@ -1270,7 +1290,7 @@ hb_buffer_pre_allocate (hb_buffer_t *buffer, unsigned int size)
  * Check if allocating memory for the buffer succeeded.
  *
  * Return value:
- * %true if memory allocation succeeded, %false otherwise.
+ * %true if @buffer memory allocation succeeded, %false otherwise.
  *
  * Since: 0.9.2
  **/
@@ -1292,6 +1312,9 @@ hb_buffer_allocation_successful (hb_buffer_t  *buffer)
  * character in the input text stream and are output in
  * #hb_glyph_info_t.cluster field.
  *
+ * This function does not check the validity of @codepoint, it is up to the
+ * caller to ensure it is a valid Unicode code point.
+ *
  * Since: 0.9.7
  **/
 void
@@ -1306,11 +1329,13 @@ hb_buffer_add (hb_buffer_t    *buffer,
 /**
  * hb_buffer_set_length:
  * @buffer: an #hb_buffer_t.
- * @length: 
+ * @length: the new length of @buffer.
- *
  *
+ * Similar to hb_buffer_pre_allocate(), but clears any new items added at the
+ * end.
  *
  * Return value: 
+ * %true if @buffer memory allocation succeeded, %false otherwise.
  *
  * Since: 0.9.2
  **/
@@ -1351,6 +1376,7 @@ hb_buffer_set_length (hb_buffer_t  *buffer,
  *
  * Return value:
  * The @buffer length.
+ * The value valid as long as buffer has not been modified.
  *
  * Since: 0.9.2
  **/
@@ -1370,6 +1396,7 @@ hb_buffer_get_length (hb_buffer_t *buffer)
  *
  * Return value: (transfer none) (array length=length):
  * The @buffer glyph information array.
+ * The value valid as long as buffer has not been modified.
  *
  * Since: 0.9.2
  **/
@@ -1393,6 +1420,7 @@ hb_buffer_get_glyph_infos (hb_buffer_t  *buffer,
  *
  * Return value: (transfer none) (array length=length):
  * The @buffer glyph position array.
+ * The value valid as long as buffer has not been modified.
  *
  * Since: 0.9.2
  **/
@@ -1558,7 +1586,8 @@ hb_buffer_add_utf (hb_buffer_t  *buffer,
 /**
  * hb_buffer_add_utf8:
  * @buffer: an #hb_buffer_t.
- * @text: (array length=text_length): an array of UTF-8 characters to append.
+ * @text: (array length=text_length) (element-type uint8_t): an array of UTF-8
+ *               characters to append.
  * @text_length: the length of the @text, or -1 if it is %NULL terminated.
  * @item_offset: the offset of the first character to add to the @buffer.
  * @item_length: the number of characters to add to the @buffer, or -1 for the
@@ -1566,6 +1595,9 @@ hb_buffer_add_utf (hb_buffer_t  *buffer,
  *
  * See hb_buffer_add_codepoints().
  *
+ * Replaces invalid UTF-8 characters with the @buffer replacement code point,
+ * see hb_buffer_set_replacement_codepoint().
+ *
  * Since: 0.9.2
  **/
 void
@@ -1589,6 +1621,9 @@ hb_buffer_add_utf8 (hb_buffer_t  *buffer,
  *
  * See hb_buffer_add_codepoints().
  *
+ * Replaces invalid UTF-16 characters with the @buffer replacement code point,
+ * see hb_buffer_set_replacement_codepoint().
+ *
  * Since: 0.9.2
  **/
 void
@@ -1612,6 +1647,9 @@ hb_buffer_add_utf16 (hb_buffer_t    *buffer,
  *
  * See hb_buffer_add_codepoints().
  *
+ * Replaces invalid UTF-32 characters with the @buffer replacement code point,
+ * see hb_buffer_set_replacement_codepoint().
+ *
  * Since: 0.9.2
  **/
 void
@@ -1627,12 +1665,17 @@ hb_buffer_add_utf32 (hb_buffer_t    *buffer,
 /**
  * hb_buffer_add_latin1:
  * @buffer: an #hb_buffer_t.
- * @text: (array length=text_length) (element-type uint8_t):
+ * @text: (array length=text_length) (element-type uint8_t): an array of UTF-8
- * @text_length: 
+ *               characters to append.
- * @item_offset: 
+ * @text_length: the length of the @text, or -1 if it is %NULL terminated.
- * @item_length: 
+ * @item_offset: the offset of the first character to add to the @buffer.
+ * @item_length: the number of characters to add to the @buffer, or -1 for the
+ *               end of @text (assuming it is %NULL terminated).
  *
+ * Similar to hb_buffer_add_codepoints(), but allows only access to first 256
+ * Unicode code points that can fit in 8-bit strings.
  *
+ * <note>Has nothing to do with non-Unicode Latin-1 encoding.</note>
  *
  * Since: 0.9.39
  **/
@@ -1665,6 +1708,9 @@ hb_buffer_add_latin1 (hb_buffer_t   *buffer,
  * for example, to do cross-run Arabic shaping or properly handle combining
  * marks at stat of run.
  *
+ * This function does not check the validity of @text, it is up to the caller
+ * to ensure it contains a valid Unicode code points.
+ *
  * Since: 0.9.31
  **/
 void
@@ -1737,7 +1783,10 @@ normalize_glyphs_cluster (hb_buffer_t *buffer,
  * hb_buffer_normalize_glyphs:
  * @buffer: an #hb_buffer_t.
  *
+ * Reorders a glyph buffer to have canonical in-cluster glyph order / position.
+ * The resulting clusters should behave identical to pre-reordering clusters.
  *
+ * <note>This has nothing to do with Unicode normalization.</note>
  *
  * Since: 0.9.2
  **/

src/hb-buffer.h

@@ -58,7 +58,7 @@ HB_BEGIN_DECLS
  *           hb_buffer_set_cluster_level() allow selecting more fine-grained
  *           cluster handling.
  *
- * The #hb_glyph_info_t is the structure that holds informations about the
+ * The #hb_glyph_info_t is the structure that holds information about the
  * glyphs and their relation to input text.
  *
  */
@@ -98,7 +98,16 @@ typedef struct hb_glyph_position_t {
   hb_var_int_t   var;
 } hb_glyph_position_t;
 
-
+/**
+ * hb_segment_properties_t:
+ * @direction: the #hb_direction_t of the buffer, see hb_buffer_set_direction().
+ * @script: the #hb_script_t of the buffer, see hb_buffer_set_script().
+ * @language: the #hb_language_t of the buffer, see hb_buffer_set_language().
+ *
+ * The structure that holds various text properties of an #hb_buffer_t. Can be
+ * set and retrieved using hb_buffer_set_segment_properties() and
+ * hb_buffer_get_segment_properties(), respectively.
+ */
 typedef struct hb_segment_properties_t {
   hb_direction_t  direction;
   hb_script_t     script;
@@ -123,8 +132,11 @@ hb_segment_properties_hash (const hb_segment_properties_t *p);
 
 
 
-/*
+/**
- * hb_buffer_t
+ * hb_buffer_t:
+ *
+ * The main structure holding the input text and its properties before shaping,
+ * and output glyphs and their information after shaping.
  */
 
 typedef struct hb_buffer_t hb_buffer_t;
@@ -262,10 +274,16 @@ hb_buffer_set_cluster_level (hb_buffer_t               *buffer,
 HB_EXTERN hb_buffer_cluster_level_t
 hb_buffer_get_cluster_level (hb_buffer_t *buffer);
 
+/**
+ * HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT:
+ *
+ * The default code point for replacing invalid characters in a given encoding.
+ * Set to U+FFFD REPLACEMENT CHARACTER.
+ *
+ * Since: 0.9.31
+ */
 #define HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT 0xFFFDu
 
-/* Sets codepoint used to replace invalid UTF-8/16/32 entries.
- * Default is 0xFFFDu. */
 HB_EXTERN void
 hb_buffer_set_replacement_codepoint (hb_buffer_t    *buffer,
 				     hb_codepoint_t  replacement);
@@ -274,22 +292,17 @@ HB_EXTERN hb_codepoint_t
 hb_buffer_get_replacement_codepoint (hb_buffer_t    *buffer);
 
 
-/* Resets the buffer.  Afterwards it's as if it was just created,
- * except that it has a larger buffer allocated perhaps... */
 HB_EXTERN void
 hb_buffer_reset (hb_buffer_t *buffer);
 
-/* Like reset, but does NOT clear unicode_funcs and replacement_codepoint. */
 HB_EXTERN void
 hb_buffer_clear_contents (hb_buffer_t *buffer);
 
-/* Returns false if allocation failed */
 HB_EXTERN hb_bool_t
 hb_buffer_pre_allocate (hb_buffer_t  *buffer,
 		        unsigned int  size);
 
 
-/* Returns false if allocation has failed before */
 HB_EXTERN hb_bool_t
 hb_buffer_allocation_successful (hb_buffer_t  *buffer);
 
@@ -332,7 +345,6 @@ hb_buffer_add_utf32 (hb_buffer_t    *buffer,
 		     unsigned int    item_offset,
 		     int             item_length);
 
-/* Allows only access to first 256 Unicode codepoints. */
 HB_EXTERN void
 hb_buffer_add_latin1 (hb_buffer_t   *buffer,
 		      const uint8_t *text,
@@ -340,7 +352,6 @@ hb_buffer_add_latin1 (hb_buffer_t   *buffer,
 		      unsigned int   item_offset,
 		      int            item_length);
 
-/* Like add_utf32 but does NOT check for invalid Unicode codepoints. */
 HB_EXTERN void
 hb_buffer_add_codepoints (hb_buffer_t          *buffer,
 			  const hb_codepoint_t *text,
@@ -349,31 +360,24 @@ hb_buffer_add_codepoints (hb_buffer_t          *buffer,
 			  int                   item_length);
 
 
-/* Clears any new items added at the end */
 HB_EXTERN hb_bool_t
 hb_buffer_set_length (hb_buffer_t  *buffer,
 		      unsigned int  length);
 
-/* Return value valid as long as buffer not modified */
 HB_EXTERN unsigned int
 hb_buffer_get_length (hb_buffer_t *buffer);
 
 /* Getting glyphs out of the buffer */
 
-/* Return value valid as long as buffer not modified */
 HB_EXTERN hb_glyph_info_t *
 hb_buffer_get_glyph_infos (hb_buffer_t  *buffer,
                            unsigned int *length);
 
-/* Return value valid as long as buffer not modified */
 HB_EXTERN hb_glyph_position_t *
 hb_buffer_get_glyph_positions (hb_buffer_t  *buffer,
                                unsigned int *length);
 
 
-/* Reorders a glyph buffer to have canonical in-cluster glyph order / position.
- * The resulting clusters should behave identical to pre-reordering clusters.
- * NOTE: This has nothing to do with Unicode normalization. */
 HB_EXTERN void
 hb_buffer_normalize_glyphs (hb_buffer_t *buffer);
 
@@ -382,7 +386,16 @@ hb_buffer_normalize_glyphs (hb_buffer_t *buffer);
  * Serialize
  */
 
-/*
+/**
+ * hb_buffer_serialize_flags_t:
+ * @HB_BUFFER_SERIALIZE_FLAG_DEFAULT: serialize glyph names, clusters and positions.
+ * @HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS: do not serialize glyph cluster.
+ * @HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS: do not serialize glyph position information.
+ * @HB_BUFFER_SERIALIZE_FLAG_NO_GLYPH_NAMES: do no serialize glyph name.
+ * @HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS: serialize glyph extents.
+ *
+ * Flags that control what glyph information are serialized in hb_buffer_serialize_glyphs().
+ *
  * Since: 0.9.20
  */
 typedef enum { /*< flags >*/
@@ -393,13 +406,23 @@ typedef enum { /*< flags >*/
   HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS	= 0x00000008u
 } hb_buffer_serialize_flags_t;
 
+/**
+ * hb_buffer_serialize_format_t:
+ * @HB_BUFFER_SERIALIZE_FORMAT_TEXT: a human-readable, plain text format.
+ * @HB_BUFFER_SERIALIZE_FORMAT_JSON: a machine-readable JSON format.
+ * @HB_BUFFER_SERIALIZE_FORMAT_INVALID: invalid format. 
+ *
+ * The buffer serialization and de-serialization format used in
+ * hb_buffer_serialize_glyphs() and hb_buffer_deserialize_glyphs().
+ *
+ * Since: 0.9.2
+ */
 typedef enum {
   HB_BUFFER_SERIALIZE_FORMAT_TEXT	= HB_TAG('T','E','X','T'),
   HB_BUFFER_SERIALIZE_FORMAT_JSON	= HB_TAG('J','S','O','N'),
   HB_BUFFER_SERIALIZE_FORMAT_INVALID	= HB_TAG_NONE
 } hb_buffer_serialize_format_t;
 
-/* len=-1 means str is NUL-terminated. */
 HB_EXTERN hb_buffer_serialize_format_t
 hb_buffer_serialize_format_from_string (const char *str, int len);
 
@@ -409,24 +432,23 @@ hb_buffer_serialize_format_to_string (hb_buffer_serialize_format_t format);
 HB_EXTERN const char **
 hb_buffer_serialize_list_formats (void);
 
-/* Returns number of items, starting at start, that were serialized. */
 HB_EXTERN unsigned int
 hb_buffer_serialize_glyphs (hb_buffer_t *buffer,
 			    unsigned int start,
 			    unsigned int end,
 			    char *buf,
 			    unsigned int buf_size,
-			    unsigned int *buf_consumed, /* May be NULL */
+			    unsigned int *buf_consumed,
-			    hb_font_t *font, /* May be NULL */
+			    hb_font_t *font,
 			    hb_buffer_serialize_format_t format,
 			    hb_buffer_serialize_flags_t flags);
 
 HB_EXTERN hb_bool_t
 hb_buffer_deserialize_glyphs (hb_buffer_t *buffer,
 			      const char *buf,
-			      int buf_len, /* -1 means nul-terminated */
+			      int buf_len,
-			      const char **end_ptr, /* May be NULL */
+			      const char **end_ptr,
-			      hb_font_t *font, /* May be NULL */
+			      hb_font_t *font,
 			      hb_buffer_serialize_format_t format);
 
 

src/hb-shape.cc

@@ -210,13 +210,15 @@ parse_one_feature (const char **pp, const char *end, hb_feature_t *feature)
 /**
  * hb_feature_from_string:
  * @str: (array length=len) (element-type uint8_t): a string to parse
- * @len: length of @str, or -1 if string is nul-terminated
+ * @len: length of @str, or -1 if string is %NULL terminated
  * @feature: (out): the #hb_feature_t to initialize with the parsed values
  *
- * Parses a string into a #hb_feature_t. If @len is -1 then @str is
+ * Parses a string into a #hb_feature_t.
- * %NULL-terminated.
  *
- * Return value: %TRUE if @str is successfully parsed, %FALSE otherwise
+ * TODO: document the syntax here.
+ *
+ * Return value:
+ * %true if @str is successfully parsed, %false otherwise.
  *
  * Since: 0.9.5
  **/