Document new API

diff --git a/src/hb-common.h b/src/hb-common.h
index 0858c0e..2532d69 100644 (file)
--- a/src/hb-common.h
+++ b/src/hb-common.h
@@ -449,15 +449,43 @@ hb_variation_to_string (hb_variation_t *variation,
  *
  * Data type for holding color values.
  *
- * Since: REPLACEME
+ * Since: 2.1.0
  */
 typedef uint32_t hb_color_t;
 
 #define HB_COLOR(b,g,r,a) ((hb_color_t) HB_TAG ((b),(g),(r),(a)))
 
+/**
+ * hb_color_get_alpha:
+ *
+ *
+ *
+ * Since: 2.1.0
+ */
 #define hb_color_get_alpha(color)      ((color) & 0xFF)
+/**
+ * hb_color_get_red:
+ *
+ *
+ *
+ * Since: 2.1.0
+ */
 #define hb_color_get_red(color)                (((color) >> 8) & 0xFF)
+/**
+ * hb_color_get_green:
+ *
+ *
+ *
+ * Since: 2.1.0
+ */
 #define hb_color_get_green(color)      (((color) >> 16) & 0xFF)
+/**
+ * hb_color_get_blue:
+ *
+ *
+ *
+ * Since: 2.1.0
+ */
 #define hb_color_get_blue(color)       (((color) >> 24) & 0xFF)
 
 

diff --git a/src/hb-ot-color.cc b/src/hb-ot-color.cc
index 3f492cc..58f5a07 100644 (file)
--- a/src/hb-ot-color.cc
+++ b/src/hb-ot-color.cc
@@ -89,7 +89,7 @@ _get_svg (hb_face_t *face)
  *
  * Returns: whether CPAL table is available.
  *
- * Since: REPLACEME
+ * Since: 2.1.0
  */
 hb_bool_t
 hb_ot_color_has_palettes (hb_face_t *face)
@@ -104,7 +104,7 @@ hb_ot_color_has_palettes (hb_face_t *face)
  * Returns: the number of color palettes in @face, or zero if @face has
  * no colors.
  *
- * Since: REPLACEME
+ * Since: 2.1.0
  */
 unsigned int
 hb_ot_color_palette_get_count (hb_face_t *face)
@@ -123,7 +123,7 @@ hb_ot_color_palette_get_count (hb_face_t *face)
  * Returns: an identifier within @face's `name` table.
  * If the requested palette has no name the result is #HB_NAME_ID_INVALID.
  *
- * Since: REPLACEME
+ * Since: 2.1.0
  */
 hb_name_id_t
 hb_ot_color_palette_get_name_id (hb_face_t *face,
@@ -139,7 +139,7 @@ hb_ot_color_palette_get_name_id (hb_face_t *face,
  *
  * Returns: Name ID associated with a palette entry, e.g. eye color
  *
- * Since: REPLACEME
+ * Since: 2.1.0
  */
 hb_name_id_t
 hb_ot_color_palette_color_get_name_id (hb_face_t *face,
@@ -155,7 +155,7 @@ hb_ot_color_palette_color_get_name_id (hb_face_t *face,
  *
  * Returns: the flags for the requested color palette.
  *
- * Since: REPLACEME
+ * Since: 2.1.0
  */
 hb_ot_color_palette_flags_t
 hb_ot_color_palette_get_flags (hb_face_t *face,
@@ -186,7 +186,7 @@ hb_ot_color_palette_get_flags (hb_face_t *face,
  *
  * Returns: the total number of colors in the palette.
  *
- * Since: REPLACEME
+ * Since: 2.1.0
  */
 unsigned int
 hb_ot_color_palette_get_colors (hb_face_t     *face,
@@ -209,7 +209,7 @@ hb_ot_color_palette_get_colors (hb_face_t     *face,
  *
  * Returns: whether COLR table is available.
  *
- * Since: REPLACEME
+ * Since: 2.1.0
  */
 hb_bool_t
 hb_ot_color_has_layers (hb_face_t *face)
@@ -227,7 +227,7 @@ hb_ot_color_has_layers (hb_face_t *face)
  *
  * Returns:
  *
- * Since: REPLACEME
+ * Since: 2.1.0
  */
 unsigned int
 hb_ot_color_glyph_get_layers (hb_face_t           *face,

diff --git a/src/hb-ot-layout.cc b/src/hb-ot-layout.cc
index 096fda2..27c49df 100644 (file)
--- a/src/hb-ot-layout.cc
+++ b/src/hb-ot-layout.cc
@@ -1174,7 +1174,7 @@ hb_ot_layout_feature_get_name_ids (hb_face_t    *face,
  *                one shot copying).
  * @char_count: (inout) (allow-none): The count of characters for which this feature
  *              provides glyph variants. (May be zero.)
- * @characters: (out) (allow-none): A buffer pointer. The Unicode Scalar Value
+ * @characters: (out caller-allocates) (array length=char_count): A buffer pointer. The Unicode codepoints
  *              of the characters for which this feature provides glyph variants.
  *
  * Fetches characters listed by designer under feature parameters for "Character

diff --git a/src/hb-ot-name.cc b/src/hb-ot-name.cc
index f1c1f76..650d99a 100644 (file)
--- a/src/hb-ot-name.cc
+++ b/src/hb-ot-name.cc
@@ -39,7 +39,18 @@ _get_name (hb_face_t *face)
   return *(hb_ot_face_data (face)->name.get ());
 }
 
-
+/**
+ * hb_ot_name_get_names:
+ * @face: font face.
+ * @entries: (out) (transfer none) (array):
+ *
+ * Enumerates all available name IDs and language combinations. Returned
+ * array is owned by the @face and should not be modified.  It can be
+ * used as long as @face is alive.
+ *
+ * Returns: Number of entries returned.
+ * Since: 2.1.0
+ **/
 unsigned int
 hb_ot_name_get_names (hb_face_t                 *face,
                      const hb_ot_name_entry_t **entries /* OUT */)
@@ -131,6 +142,22 @@ hb_ot_name_get_utf (hb_face_t     *face,
   return 0;
 }
 
+/**
+ * hb_ot_name_get_utf8:
+ * @face: font face.
+ * @name_id: OpenType name identifier to fetch.
+ * @language: language to fetch the name for.
+ * @text_size: (inout) (allow-none): input size of @text buffer, and output size of
+ *                                   text written to buffer.
+ * @text: (out caller-allocates) (array length=text_size): buffer to write fetched name into.
+ *
+ * Fetches a font name from the OpenType 'name' table.
+ * If @language is #HB_LANGUAGE_INVALID, English ("en") is assumed.
+ * Returns string in UTF-8 encoding.
+ *
+ * Returns: full length of the requested string, or 0 if not found.
+ * Since: 2.1.0
+ **/
 unsigned int
 hb_ot_name_get_utf8 (hb_face_t     *face,
                     hb_name_id_t   name_id,
@@ -142,6 +169,22 @@ hb_ot_name_get_utf8 (hb_face_t     *face,
                                        (hb_utf8_t::codepoint_t *) text);
 }
 
+/**
+ * hb_ot_name_get_utf16:
+ * @face: font face.
+ * @name_id: OpenType name identifier to fetch.
+ * @language: language to fetch the name for.
+ * @text_size: (inout) (allow-none): input size of @text buffer, and output size of
+ *                                   text written to buffer.
+ * @text: (out caller-allocates) (array length=text_size): buffer to write fetched name into.
+ *
+ * Fetches a font name from the OpenType 'name' table.
+ * If @language is #HB_LANGUAGE_INVALID, English ("en") is assumed.
+ * Returns string in UTF-16 encoding.
+ *
+ * Returns: full length of the requested string, or 0 if not found.
+ * Since: 2.1.0
+ **/
 unsigned int
 hb_ot_name_get_utf16 (hb_face_t     *face,
                      hb_name_id_t   name_id,
@@ -152,6 +195,22 @@ hb_ot_name_get_utf16 (hb_face_t     *face,
   return hb_ot_name_get_utf<hb_utf16_t> (face, name_id, language, text_size, text);
 }
 
+/**
+ * hb_ot_name_get_utf32:
+ * @face: font face.
+ * @name_id: OpenType name identifier to fetch.
+ * @language: language to fetch the name for.
+ * @text_size: (inout) (allow-none): input size of @text buffer, and output size of
+ *                                   text written to buffer.
+ * @text: (out caller-allocates) (array length=text_size): buffer to write fetched name into.
+ *
+ * Fetches a font name from the OpenType 'name' table.
+ * If @language is #HB_LANGUAGE_INVALID, English ("en") is assumed.
+ * Returns string in UTF-32 encoding.
+ *
+ * Returns: full length of the requested string, or 0 if not found.
+ * Since: 2.1.0
+ **/
 unsigned int
 hb_ot_name_get_utf32 (hb_face_t     *face,
                      hb_name_id_t   name_id,

diff --git a/src/hb-ot-name.h b/src/hb-ot-name.h
index 66af5b6..1847655 100644 (file)
--- a/src/hb-ot-name.h
+++ b/src/hb-ot-name.h
@@ -66,6 +66,10 @@ enum {
 /**
  * hb_name_id_t:
  *
+ * An integral type representing an OpenType 'name' table name identifier.
+ * There are predefined name IDs, as well as name IDs return from other
+ * API.  These can be used to fetch name strings from a font face.
+ *
  * Since: 2.0.0
  */
 typedef unsigned int hb_name_id_t;
@@ -73,6 +77,8 @@ typedef unsigned int hb_name_id_t;
 /**
  * HB_NAME_ID_INVALID
  *
+ * Value to represent a nonexistent name ID.
+ *
  * Since: 2.0.0
  **/
 #define HB_NAME_ID_INVALID 0xFFFF
@@ -100,6 +106,15 @@ hb_ot_name_get_utf32 (hb_face_t     *face,
                      uint32_t      *text      /* OUT */);
 
 
+/**
+ * hb_ot_name_entry_t:
+ * @name_id: name ID
+ * @language: language
+ *
+ * Structure representing a name ID in a particular language.
+ *
+ * Since: 2.1.0
+ **/
 typedef struct hb_ot_name_entry_t
 {
   hb_name_id_t  name_id;