Merge pull request #2774 from harfbuzz/misc-doc

Doc fixes

.github/workflows/msys2-ci.yml

@@ -39,9 +39,12 @@ jobs:
             mingw-w64-${{ matrix.MSYS2_ARCH }}-meson
             mingw-w64-${{ matrix.MSYS2_ARCH }}-ninja
             mingw-w64-${{ matrix.MSYS2_ARCH }}-pkg-config
-            mingw-w64-${{ matrix.MSYS2_ARCH }}-python-fonttools
             mingw-w64-${{ matrix.MSYS2_ARCH }}-python3
+            mingw-w64-${{ matrix.MSYS2_ARCH }}-python3-pip
             mingw-w64-${{ matrix.MSYS2_ARCH }}-ragel
+      - name: Install Python Dependencies
+        run: |
+          pip install --upgrade fonttools
       - name: Build
         run: |
           meson build \

docs/harfbuzz-docs.xml

@@ -104,6 +104,8 @@
         <xi:include href="xml/hb-ot-font.xml"/>
         <xi:include href="xml/hb-ot-layout.xml"/>
         <xi:include href="xml/hb-ot-math.xml"/>
+        <xi:include href="xml/hb-ot-meta.xml"/>
+        <xi:include href="xml/hb-ot-metrics.xml"/>
         <xi:include href="xml/hb-ot-name.xml"/>
         <xi:include href="xml/hb-ot-shape.xml"/>
         <xi:include href="xml/hb-ot-var.xml"/>
@@ -123,6 +125,8 @@
         <xi:include href="xml/hb-graphite2.xml"/>
         <xi:include href="xml/hb-icu.xml"/>
         <xi:include href="xml/hb-uniscribe.xml"/>
+        <xi:include href="xml/hb-gdi.xml"/>
+        <xi:include href="xml/hb-directwrite.xml"/>
       </chapter>
 
       <!--chapter id="object-tree">
@@ -133,6 +137,7 @@
       <index id="api-index-full"><title>API Index</title><xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include></index>
       <index id="deprecated-api-index" role="deprecated"><title>Index of deprecated API</title><xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include></index>
 
+      <index id="api-index-2-7-3" role="2.7.3"><title>Index of new symbols in 2.7.3</title><xi:include href="xml/api-index-2.7.3.xml"><xi:fallback /></xi:include></index>
       <index id="api-index-2-6-0" role="2.6.0"><title>Index of new symbols in 2.6.0</title><xi:include href="xml/api-index-2.6.0.xml"><xi:fallback /></xi:include></index>
       <index id="api-index-2-5-0" role="2.5.0"><title>Index of new symbols in 2.5.0</title><xi:include href="xml/api-index-2.5.0.xml"><xi:fallback /></xi:include></index>
       <index id="api-index-2-4-0" role="2.4.0"><title>Index of new symbols in 2.4.0</title><xi:include href="xml/api-index-2.4.0.xml"><xi:fallback /></xi:include></index>
@@ -151,6 +156,7 @@
       <index id="api-index-1-5-0" role="1.5.0"><title>Index of new symbols in 1.5.0</title><xi:include href="xml/api-index-1.5.0.xml"><xi:fallback /></xi:include></index>
       <index id="api-index-1-4-3" role="1.4.3"><title>Index of new symbols in 1.4.3</title><xi:include href="xml/api-index-1.4.3.xml"><xi:fallback /></xi:include></index>
       <index id="api-index-1-4-2" role="1.4.2"><title>Index of new symbols in 1.4.2</title><xi:include href="xml/api-index-1.4.2.xml"><xi:fallback /></xi:include></index>
+      <index id="api-index-1-4-0" role="1.4.0"><title>Index of new symbols in 1.4.0</title><xi:include href="xml/api-index-1.4.0.xml"><xi:fallback /></xi:include></index>
       <index id="api-index-1-3-3" role="1.3.3"><title>Index of new symbols in 1.3.3</title><xi:include href="xml/api-index-1.3.3.xml"><xi:fallback /></xi:include></index>
       <index id="api-index-1-2-3" role="1.2.3"><title>Index of new symbols in 1.2.3</title><xi:include href="xml/api-index-1.2.3.xml"><xi:fallback /></xi:include></index>
       <index id="api-index-1-1-3" role="1.1.3"><title>Index of new symbols in 1.1.3</title><xi:include href="xml/api-index-1.1.3.xml"><xi:fallback /></xi:include></index>

docs/harfbuzz-sections.txt

@@ -89,8 +89,11 @@ hb_buffer_normalize_glyphs
 hb_buffer_reverse
 hb_buffer_reverse_range
 hb_buffer_reverse_clusters
+hb_buffer_serialize
 hb_buffer_serialize_glyphs
 hb_buffer_deserialize_glyphs
+hb_buffer_serialize_unicode
+hb_buffer_deserialize_unicode
 hb_buffer_serialize_format_from_string
 hb_buffer_serialize_format_to_string
 hb_buffer_serialize_list_formats

src/hb-aat-layout.cc

@@ -218,7 +218,7 @@ hb_aat_layout_compile_map (const hb_aat_map_builder_t *mapper,
 }
 
 
-/*
+/**
  * hb_aat_layout_has_substitution:
  * @face: #hb_face_t to work upon
  *
@@ -285,7 +285,7 @@ hb_aat_layout_remove_deleted_glyphs (hb_buffer_t *buffer)
   hb_ot_layout_delete_glyphs_inplace (buffer, is_deleted_glyph);
 }
 
-/*
+/**
  * hb_aat_layout_has_positioning:
  * @face: #hb_face_t to work upon
  *
@@ -318,7 +318,7 @@ hb_aat_layout_position (const hb_ot_shape_plan_t *plan,
 }
 
 
-/*
+/**
  * hb_aat_layout_has_tracking:
  * @face:: #hb_face_t to work upon
  *

src/hb-aat-layout.h

@@ -732,8 +732,7 @@ HB_EXTERN hb_ot_name_id_t
 hb_aat_layout_feature_type_get_name_id (hb_face_t                    *face,
 					hb_aat_layout_feature_type_t  feature_type);
 
-typedef struct hb_aat_layout_feature_selector_info_t
+typedef struct hb_aat_layout_feature_selector_info_t {
-{
   hb_ot_name_id_t			name_id;
   hb_aat_layout_feature_selector_t	enable;
   hb_aat_layout_feature_selector_t	disable;

src/hb-buffer-serialize.cc

@@ -418,6 +418,7 @@ _hb_buffer_serialize_unicode_text (hb_buffer_t *buffer,
  * ```
  * [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
@@ -426,9 +427,7 @@ _hb_buffer_serialize_unicode_text (hb_buffer_t *buffer,
  *   - 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
+ *   - If #HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS is set, the #hb_glyph_extents_t in the format `<x_bearing,y_bearing,width,height>`
- *     #hb_glyph_extents_t in the format
- *     `&lt;x_bearing,y_bearing,width,height&gt;`
  *
  * ## json
  * A machine-readable, structured format.
@@ -438,6 +437,7 @@ _hb_buffer_serialize_unicode_text (hb_buffer_t *buffer,
  * [{"g":"uni0651","cl":0,"dx":518,"dy":0,"ax":0,"ay":0},
  * {"g":"uni0628","cl":0,"dx":0,"dy":0,"ax":1897,"ay":0}]
  * ```
+ *
  * Each glyph is a JSON object, with the following properties:
  * - `g`: the glyph name or glyph index if
  *   #HB_BUFFER_SERIALIZE_FLAG_NO_GLYPH_NAMES flag is set.
@@ -527,8 +527,9 @@ hb_buffer_serialize_glyphs (hb_buffer_t *buffer,
  * The serialized codepoints will look something like:
  *
  * ```
- * <U+0651=0|U+0628=1>
+ *  <U+0651=0|U+0628=1>
  * ```
+ *
  * - Glyphs are separated with `|`
  * - Unicode codepoints are expressed as zero-padded four (or more)
  *   digit hexadecimal numbers preceded by `U+`
@@ -544,6 +545,7 @@ hb_buffer_serialize_glyphs (hb_buffer_t *buffer,
  *   #HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS is not set.
  *
  * For example:
+ *
  * ```
  * [{u:1617,cl:0},{u:1576,cl:1}]
  * ```

src/hb-buffer.h

@@ -59,8 +59,7 @@ HB_BEGIN_DECLS
  * The #hb_glyph_info_t is the structure that holds information about the
  * glyphs and their relation to input text.
  */
-typedef struct hb_glyph_info_t
+typedef struct hb_glyph_info_t {
-{
   hb_codepoint_t codepoint;
   /*< private >*/
   hb_mask_t      mask;

src/hb-directwrite.cc

@@ -33,6 +33,15 @@
 #include "hb-directwrite.h"
 
 
+/**
+ * SECTION:hb-directwrite
+ * @title: hb-directwrite
+ * @short_description: DirectWrite integration
+ * @include: hb-directwrite.h
+ *
+ * Functions for using HarfBuzz with DirectWrite fonts.
+ **/
+
 /* Declare object creator for dynamic support of DWRITE */
 typedef HRESULT (* WINAPI t_DWriteCreateFactory)(
   DWRITE_FACTORY_TYPE factoryType,

src/hb-font.h

@@ -82,8 +82,7 @@ hb_font_funcs_is_immutable (hb_font_funcs_t *ffuncs);
 /* font and glyph extents */
 
 /* Note that typically ascender is positive and descender negative in coordinate systems that grow up. */
-typedef struct hb_font_extents_t
+typedef struct hb_font_extents_t {
-{
   hb_position_t ascender; /* typographic ascender. */
   hb_position_t descender; /* typographic descender. */
   hb_position_t line_gap; /* suggested line spacing gap. */
@@ -100,8 +99,7 @@ typedef struct hb_font_extents_t
 } hb_font_extents_t;
 
 /* Note that height is negative in coordinate systems that grow up. */
-typedef struct hb_glyph_extents_t
+typedef struct hb_glyph_extents_t {
-{
   hb_position_t x_bearing; /* left side of glyph from origin. */
   hb_position_t y_bearing; /* top side of glyph from origin. */
   hb_position_t width; /* distance from left to right side. */

src/hb-gdi.cc

@@ -28,6 +28,16 @@
 
 #include "hb-gdi.h"
 
+
+/**
+ * SECTION:hb-gdi
+ * @title: hb-gdi
+ * @short_description: GDI integration
+ * @include: hb-gdi.h
+ *
+ * Functions for using HarfBuzz with GDI fonts.
+ **/
+
 static hb_blob_t *
 _hb_gdi_reference_table (hb_face_t *face HB_UNUSED, hb_tag_t tag, void *user_data)
 {

src/hb-ot-color.h

@@ -100,8 +100,7 @@ hb_ot_color_has_layers (hb_face_t *face);
  *
  * Since: 2.1.0
  **/
-typedef struct hb_ot_color_layer_t
+typedef struct hb_ot_color_layer_t {
-{
   hb_codepoint_t glyph;
   unsigned int   color_index;
 } hb_ot_color_layer_t;

src/hb-ot-deprecated.h

@@ -82,8 +82,7 @@ hb_ot_tag_from_language (hb_language_t language);
  * Since: 1.4.2
  * Deprecated: 2.2.0
  */
-typedef struct hb_ot_var_axis_t
+typedef struct hb_ot_var_axis_t {
-{
   hb_tag_t tag;
   hb_ot_name_id_t name_id;
   float min_value;

src/hb-ot-metrics.cc

@@ -33,6 +33,15 @@
 #include "hb-ot-face.hh"
 
 
+/**
+ * SECTION:hb-ot-metrics
+ * @title: hb-ot-metrics
+ * @short_description: OpenType Metrics
+ * @include: hb-ot.h
+ *
+ * Functions for fetching metrics from fonts.
+ **/
+
 static float
 _fix_ascender_descender (float value, hb_ot_metrics_tag_t metrics_tag)
 {

src/hb-ot-name.h

@@ -88,8 +88,7 @@ typedef unsigned int hb_ot_name_id_t;
  *
  * Since: 2.1.0
  **/
-typedef struct hb_ot_name_entry_t
+typedef struct hb_ot_name_entry_t {
-{
   hb_ot_name_id_t name_id;
   /*< private >*/
   hb_var_int_t    var;

src/hb-ot-var.h

@@ -115,8 +115,7 @@ typedef enum { /*< flags >*/
  *
  * Since: 2.2.0
  */
-typedef struct hb_ot_var_axis_info_t
+typedef struct hb_ot_var_axis_info_t {
-{
   unsigned int			axis_index;
   hb_tag_t			tag;
   hb_ot_name_id_t		name_id;