Document new API

2018-10-27 02:35:06 -07:00 · 2018-10-27 02:35:06 -07:00 · 4025ad8043
parent 0353ac6cde
commit 4025ad8043
5 changed files with 113 additions and 11 deletions
--- 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)


--- 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,
--- 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
--- 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,
--- 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;