Merge pull request #3072 from harfbuzz/subset-docs

[docs] Improve subset documentation

docs/harfbuzz-sections.txt

@@ -710,6 +710,7 @@ hb_version_string
 <SECTION>
 <FILE>hb-subset</FILE>
 hb_subset_flag_t
+hb_subset_input_t
 hb_subset_input_create_or_fail
 hb_subset_input_reference
 hb_subset_input_destroy

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,

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)
 {

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)
 {

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<hb_subset_input_t>();
 
@@ -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

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
  **/

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.
  */