From 00cf4e5eb6dcb04406d5a519712da799277cec2e Mon Sep 17 00:00:00 2001 From: Behdad Esfahbod Date: Sat, 27 Oct 2018 04:07:33 -0700 Subject: [PATCH] [docs] Fill in some sections --- docs/harfbuzz-docs.xml | 20 +++++------- docs/harfbuzz-sections.txt | 65 ++++++++++++++++---------------------- src/hb-blob.cc | 13 ++++++++ src/hb-buffer.cc | 3 +- src/hb-common.cc | 23 ++++++++++++++ src/hb-face.cc | 13 ++++++++ src/hb-font.cc | 13 ++++++++ src/hb-shape-plan.cc | 13 ++++++++ src/hb-shape.cc | 4 ++- src/hb-unicode.cc | 14 ++++++++ 10 files changed, 129 insertions(+), 52 deletions(-) diff --git a/docs/harfbuzz-docs.xml b/docs/harfbuzz-docs.xml index 0057a2a9d..6e3000df4 100644 --- a/docs/harfbuzz-docs.xml +++ b/docs/harfbuzz-docs.xml @@ -61,22 +61,15 @@ Reference manual HarfBuzz API - - - + - + - - - - - @@ -87,16 +80,19 @@ - - + + + + + - + diff --git a/docs/harfbuzz-sections.txt b/docs/harfbuzz-sections.txt index 7f2ff2d2f..f20c7d9f7 100644 --- a/docs/harfbuzz-sections.txt +++ b/docs/harfbuzz-sections.txt @@ -1,10 +1,6 @@ -
-hb HB_H_IN -HB_EXTERN -HB_DEPRECATED -HB_DEPRECATED_FOR +HB_OT_H_IN
@@ -148,6 +144,10 @@ uint16_t uint32_t uint64_t uint8_t + +HB_EXTERN +HB_DEPRECATED +HB_DEPRECATED_FOR
@@ -418,11 +418,6 @@ hb_gobject_user_data_key_get_type HB_GOBJECT_H_IN
-
-hb-gobject - -
-
hb-graphite2 HB_GRAPHITE2_TAG_SILF @@ -457,12 +452,6 @@ hb_map_set_user_data hb_map_t
-
-hb-ot - -HB_OT_H_IN -
-
hb-ot-color hb_color_t @@ -498,11 +487,6 @@ hb_ot_name_get_utf32 hb_ot_name_get_utf8
-
-hb-ot-shape -hb_ot_shape_glyphs_closure -
-
hb-ot-layout HB_OT_LAYOUT_DEFAULT_LANGUAGE_INDEX @@ -554,23 +538,6 @@ Xhb_ot_layout_lookup_position Xhb_ot_layout_lookup_substitute
-
-hb-ot-var -HB_OT_TAG_VAR_AXIS_ITALIC -HB_OT_TAG_VAR_AXIS_OPTICAL_SIZE -HB_OT_TAG_VAR_AXIS_SLANT -HB_OT_TAG_VAR_AXIS_WEIGHT -HB_OT_TAG_VAR_AXIS_WIDTH -HB_OT_VAR_NO_AXIS_INDEX -hb_ot_var_axis_t -hb_ot_var_has_data -hb_ot_var_find_axis -hb_ot_var_get_axis_count -hb_ot_var_get_axes -hb_ot_var_normalize_variations -hb_ot_var_normalize_coords -
-
hb-ot-math HB_OT_TAG_MATH @@ -591,6 +558,11 @@ hb_ot_math_get_min_connector_overlap hb_ot_math_get_glyph_assembly
+
+hb-ot-shape +hb_ot_shape_glyphs_closure +
+
hb-ot-tag HB_OT_MAX_TAGS_PER_LANGUAGE @@ -603,6 +575,23 @@ hb_ot_tags_from_script_and_language hb_ot_tags_to_script_and_language
+
+hb-ot-var +HB_OT_TAG_VAR_AXIS_ITALIC +HB_OT_TAG_VAR_AXIS_OPTICAL_SIZE +HB_OT_TAG_VAR_AXIS_SLANT +HB_OT_TAG_VAR_AXIS_WEIGHT +HB_OT_TAG_VAR_AXIS_WIDTH +HB_OT_VAR_NO_AXIS_INDEX +hb_ot_var_axis_t +hb_ot_var_has_data +hb_ot_var_find_axis +hb_ot_var_get_axis_count +hb_ot_var_get_axes +hb_ot_var_normalize_variations +hb_ot_var_normalize_coords +
+
hb-set HB_SET_VALUE_INVALID diff --git a/src/hb-blob.cc b/src/hb-blob.cc index 368491c05..4b741cae6 100644 --- a/src/hb-blob.cc +++ b/src/hb-blob.cc @@ -40,6 +40,19 @@ #include +/** + * SECTION: hb-blob + * @title: Blobs + * @short_description: Binary data containers + * @include: hb.h + * + * Blobs wrap a chunk of binary data to handle lifecycle management of data + * while it is passed between client and HarfBuzz. Blobs are primarily used + * to create font faces, but also to access font face tables, as well as + * pass around other binary data. + **/ + + DEFINE_NULL_INSTANCE (hb_blob_t) = { HB_OBJECT_HEADER_STATIC, diff --git a/src/hb-buffer.cc b/src/hb-buffer.cc index f905c63a9..7286202a3 100644 --- a/src/hb-buffer.cc +++ b/src/hb-buffer.cc @@ -38,9 +38,10 @@ * @include: hb.h * * Buffers serve dual role in HarfBuzz; they hold the input characters that are - * passed hb_shape(), and after shaping they hold the output glyphs. + * passed to hb_shape(), and after shaping they hold the output glyphs. **/ + /** * hb_segment_properties_equal: * @a: first #hb_segment_properties_t to compare. diff --git a/src/hb-common.cc b/src/hb-common.cc index 86d07cf16..2a61fcc33 100644 --- a/src/hb-common.cc +++ b/src/hb-common.cc @@ -36,6 +36,16 @@ #endif +/** + * SECTION:hb-common + * @title: Common types + * @short_description: Common data types + * @include: hb.h + * + * Common data types used across HarfBuzz are defined here. + **/ + + /* hb_options_t */ hb_atomic_int_t _hb_options; @@ -615,6 +625,19 @@ hb_user_data_array_t::get (hb_user_data_key_t *key) /* hb_version */ + +/** + * SECTION:hb-version + * @title: Version + * @short_description: Information about the version of HarfBuzz in use + * @include: hb.h + * + * These functions and macros allow accessing version of the HarfBuzz + * library used at compile- as well as run-time, and to direct code + * conditionally based on those versions, again, at compile- or run-time. + **/ + + /** * hb_version: * @major: (out): Library major version component. diff --git a/src/hb-face.cc b/src/hb-face.cc index 74c77721f..4695267a3 100644 --- a/src/hb-face.cc +++ b/src/hb-face.cc @@ -35,6 +35,19 @@ #include "hb-ot-cmap-table.hh" +/** + * SECTION:hb-face + * @title: Face + * @short_description: Font face object + * @include: hb.h + * + * Font face is objects represent a single face in a font family. + * More exactly, a font face represents a single face in a binary font file. + * Font faces are typically built from a binary blob and a face index. + * Font faces are used to create fonts. + **/ + + /** * hb_face_count: * @blob: a blob. diff --git a/src/hb-font.cc b/src/hb-font.cc index e38c2fbd3..3c7b4a5b0 100644 --- a/src/hb-font.cc +++ b/src/hb-font.cc @@ -34,6 +34,19 @@ #include "hb-ot.h" +/** + * SECTION:hb-font + * @title: Font + * @short_description: Font object + * @include: hb.h + * + * Font objects represent a font face at a certain size and other + * parameters (pixels per EM, points per EM, variation settings.) + * Fonts are created from font faces, and are used as input to + * hb_shape() among other things. + **/ + + /* * hb_font_funcs_t */ diff --git a/src/hb-shape-plan.cc b/src/hb-shape-plan.cc index dea2c8c7b..3eacd587b 100644 --- a/src/hb-shape-plan.cc +++ b/src/hb-shape-plan.cc @@ -31,6 +31,19 @@ #include "hb-buffer.hh" +/** + * SECTION:hb-shape-plan + * @title: Shape plan + * @short_description: Object representing a shaping plan + * @include: hb.h + * + * Shape plans are not used for shaping directly, but can be access to query + * certain information about how shaping will perform given a set of input + * parameters (script, language, direction, features, etc.) + * Most client would not need to deal with shape plans directly. + **/ + + static void hb_shape_plan_plan (hb_shape_plan_t *shape_plan, const hb_feature_t *user_features, diff --git a/src/hb-shape.cc b/src/hb-shape.cc index e8eeff5b3..00c61397e 100644 --- a/src/hb-shape.cc +++ b/src/hb-shape.cc @@ -34,6 +34,7 @@ #include "hb-font.hh" #include "hb-machinery.hh" + /** * SECTION:hb-shape * @title: Shaping @@ -42,10 +43,11 @@ * * Shaping is the central operation of HarfBuzz. Shaping operates on buffers, * which are sequences of Unicode characters that use the same font and have - * the same text direction, script and language. After shaping the buffer + * the same text direction, script, and language. After shaping the buffer * contains the output glyphs and their positions. **/ + #ifdef HB_USE_ATEXIT static void free_static_shaper_list (void); #endif diff --git a/src/hb-unicode.cc b/src/hb-unicode.cc index a08f88829..bfa4ca2bc 100644 --- a/src/hb-unicode.cc +++ b/src/hb-unicode.cc @@ -33,6 +33,20 @@ #include "hb-unicode.hh" +/** + * SECTION: hb-unicode + * @title: Unicode functions + * @short_description: Unicode character property access + * @include: hb.h + * + * Unicode functions are used to access Unicode character properties. + * Client can pass its own Unicode functions to HarfBuzz, or access + * the built-in Unicode functions that come with HarfBuzz. + * + * With the Unicode functions, one can query variour Unicode character + * properties, such as General Category, Script, Combining Class, etc. + **/ + /* * hb_unicode_funcs_t