From 3e2734cf9131dc075ac120209c803d55720672b3 Mon Sep 17 00:00:00 2001 From: Khaled Hosny Date: Mon, 26 Jul 2021 02:12:21 +0200 Subject: [PATCH 1/2] =?UTF-8?q?[docs]=20Don=E2=80=99t=20use=20GTK-Doc=20sy?= =?UTF-8?q?ntax=20for=20internal=20functions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We don’t generate docs for them, reduces the number of warnings. --- src/hb-subset-cff-common.cc | 12 ++++-------- src/hb-subset-cff1.cc | 6 ------ src/hb-subset-cff2.cc | 4 ---- 3 files changed, 4 insertions(+), 18 deletions(-) diff --git a/src/hb-subset-cff-common.cc b/src/hb-subset-cff-common.cc index 04e1db24a..711b2236d 100644 --- a/src/hb-subset-cff-common.cc +++ b/src/hb-subset-cff-common.cc @@ -38,13 +38,12 @@ using namespace CFF; -/** - * hb_plan_subset_cff_fdselect - * Determine an optimal FDSelect format according to a provided plan. + +/* Determine an optimal FDSelect format according to a provided plan. * * Return value: FDSelect format, size, and ranges for the most compact subset FDSelect * along with a font index remapping table - **/ + */ bool hb_plan_subset_cff_fdselect (const hb_subset_plan_t *plan, @@ -169,10 +168,7 @@ serialize_fdselect_3_4 (hb_serialize_context_t *c, return_trace (true); } -/** - * hb_serialize_cff_fdselect - * Serialize a subset FDSelect format planned above. - **/ +/* Serialize a subset FDSelect format planned above. */ bool hb_serialize_cff_fdselect (hb_serialize_context_t *c, const unsigned int num_glyphs, diff --git a/src/hb-subset-cff1.cc b/src/hb-subset-cff1.cc index 35dae7b1f..1d492c615 100644 --- a/src/hb-subset-cff1.cc +++ b/src/hb-subset-cff1.cc @@ -917,12 +917,6 @@ _hb_subset_cff1 (const OT::cff1::accelerator_subset_t &acc, return _serialize_cff1 (c->serializer, cff_plan, acc, c->plan->num_output_glyphs ()); } -/** - * hb_subset_cff1: - * Subsets the CFF table according to a provided plan. - * - * Return value: subsetted cff table. - **/ bool hb_subset_cff1 (hb_subset_context_t *c) { diff --git a/src/hb-subset-cff2.cc b/src/hb-subset-cff2.cc index 17ee040de..1082be4ae 100644 --- a/src/hb-subset-cff2.cc +++ b/src/hb-subset-cff2.cc @@ -470,10 +470,6 @@ _hb_subset_cff2 (const OT::cff2::accelerator_subset_t &acc, return _serialize_cff2 (c->serializer, cff2_plan, acc, c->plan->num_output_glyphs ()); } -/** - * hb_subset_cff2: - * Subsets the CFF2 table according to a provided subset context. - **/ bool hb_subset_cff2 (hb_subset_context_t *c) { From acc7100a3f37fd72cfcd5953cf9446b04ef387b6 Mon Sep 17 00:00:00 2001 From: Khaled Hosny Date: Mon, 26 Jul 2021 02:13:49 +0200 Subject: [PATCH 2/2] [docs] Improve subset documentation --- docs/harfbuzz-sections.txt | 1 + src/hb-subset-input.cc | 58 +++++++++++++++++++++++++++++--------- src/hb-subset-plan.cc | 9 ++++-- src/hb-subset.h | 4 +-- 4 files changed, 54 insertions(+), 18 deletions(-) diff --git a/docs/harfbuzz-sections.txt b/docs/harfbuzz-sections.txt index f5a3579ee..4c02eac57 100644 --- a/docs/harfbuzz-sections.txt +++ b/docs/harfbuzz-sections.txt @@ -710,6 +710,7 @@ hb_version_string
hb-subset hb_subset_flag_t +hb_subset_input_t hb_subset_input_create_or_fail hb_subset_input_reference hb_subset_input_destroy diff --git a/src/hb-subset-input.cc b/src/hb-subset-input.cc index ce6f9625b..619e61f0b 100644 --- a/src/hb-subset-input.cc +++ b/src/hb-subset-input.cc @@ -30,12 +30,15 @@ /** * hb_subset_input_create_or_fail: * - * Return value: New subset input. + * Creates a new subset input object. + * + * Return value: (transfer full): New subset input, or %NULL if failed. Destroy + * with hb_subset_input_destroy(). * * Since: 1.8.0 **/ hb_subset_input_t * -hb_subset_input_create_or_fail () +hb_subset_input_create_or_fail (void) { hb_subset_input_t *input = hb_object_create(); @@ -198,7 +201,9 @@ hb_subset_input_create_or_fail () * hb_subset_input_reference: (skip) * @input: a #hb_subset_input_t object. * - * Return value: + * Increases the reference count on @input. + * + * Return value: @input. * * Since: 1.8.0 **/ @@ -212,6 +217,9 @@ hb_subset_input_reference (hb_subset_input_t *input) * hb_subset_input_destroy: * @input: a #hb_subset_input_t object. * + * Decreases the reference count on @input, and if it reaches zero, destroys + * @input, freeing all memory. + * * Since: 1.8.0 **/ void @@ -234,7 +242,11 @@ hb_subset_input_destroy (hb_subset_input_t *input) * hb_subset_input_unicode_set: * @input: a #hb_subset_input_t object. * - * Return value: pointer to the set of unicode codepoints to retain. + * Gets the set of Unicode code points to retain, the caller should modify the + * set as needed. + * + * Return value: (transfer none): pointer to the #hb_set_t of Unicode code + * points. * * Since: 1.8.0 **/ @@ -248,7 +260,10 @@ hb_subset_input_unicode_set (hb_subset_input_t *input) * hb_subset_input_glyph_set: * @input: a #hb_subset_input_t object. * - * Return value: pointer to the set of glyph ids to retain. + * Gets the set of glyph IDs to retain, the caller should modify the set as + * needed. + * + * Return value: (transfer none): pointer to the #hb_set_t of glyph IDs. * * Since: 1.8.0 **/ @@ -262,7 +277,10 @@ hb_subset_input_glyph_set (hb_subset_input_t *input) * hb_subset_input_nameid_set: * @input: a #hb_subset_input_t object. * - * Return value: pointer to the set of name ids to retain. + * Gets the set of name table name IDs to retain, the caller should modify the + * set as needed. + * + * Return value: (transfer none): pointer to the #hb_set_t of name IDs. * * Since: REPLACE **/ @@ -276,7 +294,10 @@ hb_subset_input_nameid_set (hb_subset_input_t *input) * hb_subset_input_namelangid_set: * @input: a #hb_subset_input_t object. * - * Return value: pointer to the set of name language ids to retain. + * Gets the set of name table language IDs to retain, the caller should modify + * the set as needed. + * + * Return value: (transfer none): pointer to the #hb_set_t of language IDs. * * Since: REPLACE **/ @@ -291,7 +312,10 @@ hb_subset_input_namelangid_set (hb_subset_input_t *input) * hb_subset_input_layout_features_set: * @input: a #hb_subset_input_t object. * - * Return value: pointer to the set of feature tags to retain. + * Gets the set of layout feature tags to retain, the caller should modify the + * set as needed. + * + * Return value: (transfer none): pointer to the #hb_set_t of feature tags. * * Since: REPLACE **/ @@ -316,11 +340,13 @@ hb_subset_input_get_retain_all_features (hb_subset_input_t *input) /** - * hb_subset_input_drop_tabes_set: + * hb_subset_input_drop_tables_set: * @input: a #hb_subset_input_t object. * - * Return value: pointer to the set of table tags which specifies tables - * to be dropped. + * Gets the set of table tags to drop, the caller should modify the set as + * needed. + * + * Return value: (transfer none): pointer to the #hb_set_t of table tags. * * Since: REPLACE **/ @@ -331,11 +357,13 @@ hb_subset_input_drop_tables_set (hb_subset_input_t *input) } /** - * hb_subset_input_no_subset_tabes_set: + * hb_subset_input_no_subset_tables_set: * @input: a #hb_subset_input_t object. * - * Return value: pointer to the set of table tags which specifies tables - * that should not have subsetting applied to them. + * Gets the set of table tags which specifies tables that should not be + * subsetted, the caller should modify the set as needed. + * + * Return value: (transfer none): pointer to the #hb_set_t of table tags. * * Since: REPLACE **/ @@ -351,6 +379,8 @@ hb_subset_input_no_subset_tables_set (hb_subset_input_t *input) * @input: a #hb_subset_input_t object. * @flag: which flag to check. * + * Get the value of the specified flag. + * * Return value: value of the specified flag. * * Since: REPLACE diff --git a/src/hb-subset-plan.cc b/src/hb-subset-plan.cc index 470917280..5749068de 100644 --- a/src/hb-subset-plan.cc +++ b/src/hb-subset-plan.cc @@ -403,13 +403,14 @@ _nameid_closure (hb_face_t *face, /** * hb_subset_plan_create: * @face: font face to create the plan for. - * @input: a subset input. + * @input: a #hb_subset_input_t input. * * Computes a plan for subsetting the supplied face according * to a provided input. The plan describes * which tables and glyphs should be retained. * - * Return value: New subset plan. + * Return value: (transfer full): New subset plan. Destroy with + * hb_subset_plan_destroy(). * * Since: 1.7.5 **/ @@ -487,6 +488,10 @@ hb_subset_plan_create (hb_face_t *face, /** * hb_subset_plan_destroy: + * @plan: a #hb_subset_plan_t + * + * Decreases the reference count on @plan, and if it reaches zero, destroys + * @plan, freeing all memory. * * Since: 1.7.5 **/ diff --git a/src/hb-subset.h b/src/hb-subset.h index 4f666f05b..64148adee 100644 --- a/src/hb-subset.h +++ b/src/hb-subset.h @@ -31,8 +31,8 @@ HB_BEGIN_DECLS -/* - * hb_subset_input_t +/** + * hb_subset_input_t: * * Things that change based on the input. Characters to keep, etc. */