[docs] Fill in some sections

diff --git a/docs/harfbuzz-docs.xml b/docs/harfbuzz-docs.xml
index 0057a2a..6e3000d 100644 (file)
--- a/docs/harfbuzz-docs.xml
+++ b/docs/harfbuzz-docs.xml
@@ -61,22 +61,15 @@
     <title>Reference manual</title>
       <chapter>
         <title>HarfBuzz API</title>
-        <xi:include href="xml/hb.xml"/>
         <xi:include href="xml/hb-common.xml"/>
-        <xi:include href="xml/hb-unicode.xml"/>
-        <xi:include href="xml/hb-buffer.xml"/>
         <xi:include href="xml/hb-blob.xml"/>
         <xi:include href="xml/hb-face.xml"/>
         <xi:include href="xml/hb-font.xml"/>
+        <xi:include href="xml/hb-buffer.xml"/>
         <xi:include href="xml/hb-shape.xml"/>
-
+        <xi:include href="xml/hb-unicode.xml"/>
         <xi:include href="xml/hb-version.xml"/>
-        <xi:include href="xml/hb-deprecated.xml"/>
-
-        <xi:include href="xml/hb-set.xml"/>
-        <xi:include href="xml/hb-map.xml"/>
 
-        <xi:include href="xml/hb-ot.xml"/>
         <xi:include href="xml/hb-ot-font.xml"/>
         <xi:include href="xml/hb-ot-layout.xml"/>
         <xi:include href="xml/hb-ot-tag.xml"/>
@@ -87,16 +80,19 @@
 
         <xi:include href="xml/hb-shape-plan.xml"/>
 
-        <xi:include href="xml/hb-glib.xml"/>
-        <xi:include href="xml/hb-icu.xml"/>
+        <xi:include href="xml/hb-set.xml"/>
+        <xi:include href="xml/hb-map.xml"/>
 
         <xi:include href="xml/hb-ft.xml"/>
+        <xi:include href="xml/hb-icu.xml"/>
+        <xi:include href="xml/hb-glib.xml"/>
+        <xi:include href="xml/hb-gobject.xml"/>
 
         <xi:include href="xml/hb-graphite2.xml"/>
         <xi:include href="xml/hb-uniscribe.xml"/>
         <xi:include href="xml/hb-coretext.xml"/>
 
-        <xi:include href="xml/hb-gobject.xml"/>
+        <xi:include href="xml/hb-deprecated.xml"/>
 
       </chapter>
       <chapter id="object-tree">

diff --git a/docs/harfbuzz-sections.txt b/docs/harfbuzz-sections.txt
index 7f2ff2d..f20c7d9 100644 (file)
--- a/docs/harfbuzz-sections.txt
+++ b/docs/harfbuzz-sections.txt
@@ -1,10 +1,6 @@
-<SECTION>
-<FILE>hb</FILE>
 <SUBSECTION Private>
 HB_H_IN
-HB_EXTERN
-HB_DEPRECATED
-HB_DEPRECATED_FOR
+HB_OT_H_IN
 </SECTION>
 
 <SECTION>
@@ -148,6 +144,10 @@ uint16_t
 uint32_t
 uint64_t
 uint8_t
+<SUBSECTION Private>
+HB_EXTERN
+HB_DEPRECATED
+HB_DEPRECATED_FOR
 </SECTION>
 
 <SECTION>
@@ -419,11 +419,6 @@ HB_GOBJECT_H_IN
 </SECTION>
 
 <SECTION>
-<FILE>hb-gobject</FILE>
-
-</SECTION>
-
-<SECTION>
 <FILE>hb-graphite2</FILE>
 HB_GRAPHITE2_TAG_SILF
 hb_graphite2_face_get_gr_face
@@ -458,12 +453,6 @@ hb_map_t
 </SECTION>
 
 <SECTION>
-<FILE>hb-ot</FILE>
-<SUBSECTION Private>
-HB_OT_H_IN
-</SECTION>
-
-<SECTION>
 <FILE>hb-ot-color</FILE>
 hb_color_t
 HB_COLOR
@@ -499,11 +488,6 @@ hb_ot_name_get_utf8
 </SECTION>
 
 <SECTION>
-<FILE>hb-ot-shape</FILE>
-hb_ot_shape_glyphs_closure
-</SECTION>
-
-<SECTION>
 <FILE>hb-ot-layout</FILE>
 HB_OT_LAYOUT_DEFAULT_LANGUAGE_INDEX
 HB_OT_LAYOUT_NO_FEATURE_INDEX
@@ -555,23 +539,6 @@ Xhb_ot_layout_lookup_substitute
 </SECTION>
 
 <SECTION>
-<FILE>hb-ot-var</FILE>
-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
-</SECTION>
-
-<SECTION>
 <FILE>hb-ot-math</FILE>
 HB_OT_TAG_MATH
 HB_OT_MATH_SCRIPT
@@ -592,6 +559,11 @@ hb_ot_math_get_glyph_assembly
 </SECTION>
 
 <SECTION>
+<FILE>hb-ot-shape</FILE>
+hb_ot_shape_glyphs_closure
+</SECTION>
+
+<SECTION>
 <FILE>hb-ot-tag</FILE>
 HB_OT_MAX_TAGS_PER_LANGUAGE
 HB_OT_MAX_TAGS_PER_SCRIPT
@@ -604,6 +576,23 @@ hb_ot_tags_to_script_and_language
 </SECTION>
 
 <SECTION>
+<FILE>hb-ot-var</FILE>
+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
+</SECTION>
+
+<SECTION>
 <FILE>hb-set</FILE>
 HB_SET_VALUE_INVALID
 hb_set_add

diff --git a/src/hb-blob.cc b/src/hb-blob.cc
index 368491c..4b741ca 100644 (file)
--- a/src/hb-blob.cc
+++ b/src/hb-blob.cc
@@ -40,6 +40,19 @@
 #include <stdlib.h>
 
 
+/**
+ * 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 f905c63..7286202 100644 (file)
--- 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 86d07cf..2a61fcc 100644 (file)
--- 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 74c7772..4695267 100644 (file)
--- a/src/hb-face.cc
+++ b/src/hb-face.cc
@@ -36,6 +36,19 @@
 
 
 /**
+ * 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 e38c2fb..3c7b4a5 100644 (file)
--- 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 dea2c8c..3eacd58 100644 (file)
--- 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 e8eeff5..00c6139 100644 (file)
--- 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 a08f888..bfa4ca2 100644 (file)
--- 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