From 6392d83a778f782533c1a882efb80aa1567f6418 Mon Sep 17 00:00:00 2001 From: Colin Rofls Date: Tue, 31 Oct 2023 14:36:11 -0400 Subject: [PATCH] [codegen] Improve generated docs for typed offset getters [codegen] Also just reproduce the original docs when needed More improvements to offset getter docs - manually update codegen inputs to name parent field where it was missing - simplify docs in case where manual data is required --- font-codegen/src/fields.rs | 31 ++++++++++++--- read-fonts/generated/generated_base.rs | 22 +++++++++-- read-fonts/generated/generated_cmap.rs | 38 ++++++++++++------- read-fonts/generated/generated_colr.rs | 18 ++++++--- read-fonts/generated/generated_gpos.rs | 38 ++++++++++++++++--- read-fonts/generated/generated_layout.rs | 27 ++++++++++--- .../generated/generated_test_records.rs | 8 +++- resources/codegen_inputs/cmap.rs | 10 ++--- resources/codegen_inputs/colr.rs | 4 +- write-fonts/generated/generated_cmap.rs | 10 ++--- 10 files changed, 153 insertions(+), 53 deletions(-) diff --git a/font-codegen/src/fields.rs b/font-codegen/src/fields.rs index ccce0039d..f1f68463d 100644 --- a/font-codegen/src/fields.rs +++ b/font-codegen/src/fields.rs @@ -779,6 +779,29 @@ impl Field { quote!( self.shape.#shape_range_fn_name() #try_op ) } + fn typed_offset_getter_docs(&self, has_data_arg: bool) -> TokenStream { + let raw_name = &self.name; + // If there's no arguments than we just link to the raw offset method + if !has_data_arg { + let docs = if self.is_array() { + format!(" A dynamically resolving wrapper for [`{raw_name}`][Self::{raw_name}].") + } else { + format!(" Attempt to resolve [`{raw_name}`][Self::{raw_name}].") + }; + return quote!(#[doc = #docs]); + } + + // if there is a data argument than we want to be more explicit + let original_docs = &self.attrs.docs; + + quote! { + #(#original_docs)* + #[doc = ""] + #[doc = " The `data` argument should be retrieved from the parent table"] + #[doc = " By calling its `offset_data` method."] + } + } + fn typed_offset_field_getter( &self, generic: Option<&syn::Ident>, @@ -811,6 +834,7 @@ impl Field { let args = args.to_tokens_for_table_getter(); quote!(let args = #args;) }); + let docs = self.typed_offset_getter_docs(record.is_some()); if self.is_array() { let OffsetTarget::Table(target_ident) = target else { @@ -838,11 +862,9 @@ impl Field { } let bind_offsets = quote!( let offsets = self.#raw_name(); ); - let docs = - format!(" A dynamically resolving wrapper for [`{raw_name}`][Self::{raw_name}]."); Some(quote! { - #[doc = #docs] + #docs pub fn #getter_name (&self #input_data_if_needed) -> #return_type #where_read_clause { #data_alias_if_needed #bind_offsets @@ -859,7 +881,6 @@ impl Field { None => quote!(resolve(data)), Some(_) => quote!(resolve_with_args(data, &args)), }; - let docs = format!(" Attempt to resolve [`{raw_name}`][Self::{raw_name}]."); let getter_impl = if self.is_version_dependent() { // if this is nullable *and* version dependent we add a `?` // to avoid returning Option> @@ -869,7 +890,7 @@ impl Field { quote!( self. #raw_name () .#resolve ) }; Some(quote! { - #[doc = #docs] + #docs pub fn #getter_name #decl_lifetime_if_needed (&self #input_data_if_needed) -> #return_type #where_read_clause { #data_alias_if_needed #args_if_needed diff --git a/read-fonts/generated/generated_base.rs b/read-fonts/generated/generated_base.rs index d4058b7f7..8ed1964c1 100644 --- a/read-fonts/generated/generated_base.rs +++ b/read-fonts/generated/generated_base.rs @@ -389,7 +389,10 @@ impl BaseScriptRecord { self.base_script_offset.get() } - /// Attempt to resolve [`base_script_offset`][Self::base_script_offset]. + /// Offset to BaseScript table, from beginning of BaseScriptList + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn base_script<'a>(&self, data: FontData<'a>) -> Result, ReadError> { self.base_script_offset().resolve(data) } @@ -568,7 +571,10 @@ impl BaseLangSysRecord { self.min_max_offset.get() } - /// Attempt to resolve [`min_max_offset`][Self::min_max_offset]. + /// Offset to MinMax table, from beginning of BaseScript table + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn min_max<'a>(&self, data: FontData<'a>) -> Result, ReadError> { self.min_max_offset().resolve(data) } @@ -861,7 +867,11 @@ impl FeatMinMaxRecord { self.min_coord_offset.get() } - /// Attempt to resolve [`min_coord_offset`][Self::min_coord_offset]. + /// Offset to BaseCoord table that defines the minimum extent + /// value, from beginning of MinMax table (may be NULL) + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn min_coord<'a>(&self, data: FontData<'a>) -> Option, ReadError>> { self.min_coord_offset().resolve(data) } @@ -872,7 +882,11 @@ impl FeatMinMaxRecord { self.max_coord_offset.get() } - /// Attempt to resolve [`max_coord_offset`][Self::max_coord_offset]. + /// Offset to BaseCoord table that defines the maximum extent + /// value, from beginning of MinMax table (may be NULL) + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn max_coord<'a>(&self, data: FontData<'a>) -> Option, ReadError>> { self.max_coord_offset().resolve(data) } diff --git a/read-fonts/generated/generated_cmap.rs b/read-fonts/generated/generated_cmap.rs index 31aa2bc46..d7651188b 100644 --- a/read-fonts/generated/generated_cmap.rs +++ b/read-fonts/generated/generated_cmap.rs @@ -105,7 +105,7 @@ pub struct EncodingRecord { pub platform_id: BigEndian, /// Platform-specific encoding ID. pub encoding_id: BigEndian, - /// Byte offset from beginning of table to the subtable for this + /// Byte offset from beginning of the [`Cmap`] table to the subtable for this /// encoding. pub subtable_offset: BigEndian, } @@ -121,13 +121,17 @@ impl EncodingRecord { self.encoding_id.get() } - /// Byte offset from beginning of table to the subtable for this + /// Byte offset from beginning of the [`Cmap`] table to the subtable for this /// encoding. pub fn subtable_offset(&self) -> Offset32 { self.subtable_offset.get() } - /// Attempt to resolve [`subtable_offset`][Self::subtable_offset]. + /// Byte offset from beginning of the [`Cmap`] table to the subtable for this + /// encoding. + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn subtable<'a>(&self, data: FontData<'a>) -> Result, ReadError> { self.subtable_offset().resolve(data) } @@ -1614,11 +1618,11 @@ impl<'a> std::fmt::Debug for Cmap14<'a> { pub struct VariationSelector { /// Variation selector pub var_selector: BigEndian, - /// Offset from the start of the format 14 subtable to Default UVS - /// Table. May be 0. + /// Offset from the start of the [`Cmap14`] subtable to Default UVS + /// Table. May be NULL. pub default_uvs_offset: BigEndian>, - /// Offset from the start of the format 14 subtable to Non-Default - /// UVS Table. May be 0. + /// Offset from the start of the [`Cmap14`] subtable to Non-Default + /// UVS Table. May be NULL. pub non_default_uvs_offset: BigEndian>, } @@ -1628,24 +1632,32 @@ impl VariationSelector { self.var_selector.get() } - /// Offset from the start of the format 14 subtable to Default UVS - /// Table. May be 0. + /// Offset from the start of the [`Cmap14`] subtable to Default UVS + /// Table. May be NULL. pub fn default_uvs_offset(&self) -> Nullable { self.default_uvs_offset.get() } - /// Attempt to resolve [`default_uvs_offset`][Self::default_uvs_offset]. + /// Offset from the start of the [`Cmap14`] subtable to Default UVS + /// Table. May be NULL. + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn default_uvs<'a>(&self, data: FontData<'a>) -> Option, ReadError>> { self.default_uvs_offset().resolve(data) } - /// Offset from the start of the format 14 subtable to Non-Default - /// UVS Table. May be 0. + /// Offset from the start of the [`Cmap14`] subtable to Non-Default + /// UVS Table. May be NULL. pub fn non_default_uvs_offset(&self) -> Nullable { self.non_default_uvs_offset.get() } - /// Attempt to resolve [`non_default_uvs_offset`][Self::non_default_uvs_offset]. + /// Offset from the start of the [`Cmap14`] subtable to Non-Default + /// UVS Table. May be NULL. + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn non_default_uvs<'a>( &self, data: FontData<'a>, diff --git a/read-fonts/generated/generated_colr.rs b/read-fonts/generated/generated_colr.rs index 5ae8cd44b..fcb740f3f 100644 --- a/read-fonts/generated/generated_colr.rs +++ b/read-fonts/generated/generated_colr.rs @@ -484,7 +484,7 @@ impl<'a> std::fmt::Debug for BaseGlyphList<'a> { pub struct BaseGlyphPaint { /// Glyph ID of the base glyph. pub glyph_id: BigEndian, - /// Offset to a Paint table. + /// Offset to a Paint table, from the beginning of the [`BaseGlyphList`] table. pub paint_offset: BigEndian, } @@ -494,12 +494,15 @@ impl BaseGlyphPaint { self.glyph_id.get() } - /// Offset to a Paint table. + /// Offset to a Paint table, from the beginning of the [`BaseGlyphList`] table. pub fn paint_offset(&self) -> Offset32 { self.paint_offset.get() } - /// Attempt to resolve [`paint_offset`][Self::paint_offset]. + /// Offset to a Paint table, from the beginning of the [`BaseGlyphList`] table. + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn paint<'a>(&self, data: FontData<'a>) -> Result, ReadError> { self.paint_offset().resolve(data) } @@ -715,7 +718,7 @@ pub struct Clip { pub start_glyph_id: BigEndian, /// Last glyph ID in the range. pub end_glyph_id: BigEndian, - /// Offset to a ClipBox table. + /// Offset to a ClipBox table, from the beginning of the [`ClipList`] table. pub clip_box_offset: BigEndian, } @@ -730,12 +733,15 @@ impl Clip { self.end_glyph_id.get() } - /// Offset to a ClipBox table. + /// Offset to a ClipBox table, from the beginning of the [`ClipList`] table. pub fn clip_box_offset(&self) -> Offset24 { self.clip_box_offset.get() } - /// Attempt to resolve [`clip_box_offset`][Self::clip_box_offset]. + /// Offset to a ClipBox table, from the beginning of the [`ClipList`] table. + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn clip_box<'a>(&self, data: FontData<'a>) -> Result, ReadError> { self.clip_box_offset().resolve(data) } diff --git a/read-fonts/generated/generated_gpos.rs b/read-fonts/generated/generated_gpos.rs index bd7953293..2e3bfe6a2 100644 --- a/read-fonts/generated/generated_gpos.rs +++ b/read-fonts/generated/generated_gpos.rs @@ -1008,7 +1008,10 @@ impl MarkRecord { self.mark_anchor_offset.get() } - /// Attempt to resolve [`mark_anchor_offset`][Self::mark_anchor_offset]. + /// Offset to Anchor table, from beginning of MarkArray table. + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn mark_anchor<'a>(&self, data: FontData<'a>) -> Result, ReadError> { self.mark_anchor_offset().resolve(data) } @@ -2233,7 +2236,11 @@ impl EntryExitRecord { self.entry_anchor_offset.get() } - /// Attempt to resolve [`entry_anchor_offset`][Self::entry_anchor_offset]. + /// Offset to entryAnchor table, from beginning of CursivePos + /// subtable (may be NULL). + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn entry_anchor<'a>( &self, data: FontData<'a>, @@ -2247,7 +2254,11 @@ impl EntryExitRecord { self.exit_anchor_offset.get() } - /// Attempt to resolve [`exit_anchor_offset`][Self::exit_anchor_offset]. + /// Offset to exitAnchor table, from beginning of CursivePos + /// subtable (may be NULL). + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn exit_anchor<'a>( &self, data: FontData<'a>, @@ -2561,7 +2572,12 @@ impl<'a> BaseRecord<'a> { self.base_anchor_offsets } - /// A dynamically resolving wrapper for [`base_anchor_offsets`][Self::base_anchor_offsets]. + /// Array of offsets (one per mark class) to Anchor tables. Offsets + /// are from beginning of BaseArray table, ordered by class + /// (offsets may be NULL). + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn base_anchors( &self, data: FontData<'a>, @@ -3016,7 +3032,12 @@ impl<'a> ComponentRecord<'a> { self.ligature_anchor_offsets } - /// A dynamically resolving wrapper for [`ligature_anchor_offsets`][Self::ligature_anchor_offsets]. + /// Array of offsets (one per class) to Anchor tables. Offsets are + /// from beginning of LigatureAttach table, ordered by class + /// (offsets may be NULL). + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn ligature_anchors( &self, data: FontData<'a>, @@ -3357,7 +3378,12 @@ impl<'a> Mark2Record<'a> { self.mark2_anchor_offsets } - /// A dynamically resolving wrapper for [`mark2_anchor_offsets`][Self::mark2_anchor_offsets]. + /// Array of offsets (one per class) to Anchor tables. Offsets are + /// from beginning of Mark2Array table, in class order (offsets may + /// be NULL). + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn mark2_anchors( &self, data: FontData<'a>, diff --git a/read-fonts/generated/generated_layout.rs b/read-fonts/generated/generated_layout.rs index 706843802..0d25554ad 100644 --- a/read-fonts/generated/generated_layout.rs +++ b/read-fonts/generated/generated_layout.rs @@ -102,7 +102,10 @@ impl ScriptRecord { self.script_offset.get() } - /// Attempt to resolve [`script_offset`][Self::script_offset]. + /// Offset to Script table, from beginning of ScriptList + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn script<'a>(&self, data: FontData<'a>) -> Result, ReadError> { self.script_offset().resolve(data) } @@ -256,7 +259,10 @@ impl LangSysRecord { self.lang_sys_offset.get() } - /// Attempt to resolve [`lang_sys_offset`][Self::lang_sys_offset]. + /// Offset to LangSys table, from beginning of Script table + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn lang_sys<'a>(&self, data: FontData<'a>) -> Result, ReadError> { self.lang_sys_offset().resolve(data) } @@ -482,7 +488,10 @@ impl FeatureRecord { self.feature_offset.get() } - /// Attempt to resolve [`feature_offset`][Self::feature_offset]. + /// Offset to Feature table, from beginning of FeatureList + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn feature<'a>(&self, data: FontData<'a>) -> Result, ReadError> { let args = self.feature_tag(); self.feature_offset().resolve_with_args(data, &args) @@ -3910,7 +3919,11 @@ impl FeatureVariationRecord { self.condition_set_offset.get() } - /// Attempt to resolve [`condition_set_offset`][Self::condition_set_offset]. + /// Offset to a condition set table, from beginning of + /// FeatureVariations table. + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn condition_set<'a>( &self, data: FontData<'a>, @@ -3924,7 +3937,11 @@ impl FeatureVariationRecord { self.feature_table_substitution_offset.get() } - /// Attempt to resolve [`feature_table_substitution_offset`][Self::feature_table_substitution_offset]. + /// Offset to a feature table substitution table, from beginning of + /// the FeatureVariations table. + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn feature_table_substitution<'a>( &self, data: FontData<'a>, diff --git a/read-fonts/generated/generated_test_records.rs b/read-fonts/generated/generated_test_records.rs index f93b560b5..6f9a7c509 100644 --- a/read-fonts/generated/generated_test_records.rs +++ b/read-fonts/generated/generated_test_records.rs @@ -258,7 +258,9 @@ impl ContainsOffests { self.array_offset.get() } - /// Attempt to resolve [`array_offset`][Self::array_offset]. + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn array<'a>(&self, data: FontData<'a>) -> Result<&'a [SimpleRecord], ReadError> { let args = self.off_array_count(); self.array_offset().resolve_with_args(data, &args) @@ -268,7 +270,9 @@ impl ContainsOffests { self.other_offset.get() } - /// Attempt to resolve [`other_offset`][Self::other_offset]. + /// + /// The `data` argument should be retrieved from the parent table + /// By calling its `offset_data` method. pub fn other<'a>(&self, data: FontData<'a>) -> Result, ReadError> { self.other_offset().resolve(data) } diff --git a/resources/codegen_inputs/cmap.rs b/resources/codegen_inputs/cmap.rs index d301b6307..72f979eec 100644 --- a/resources/codegen_inputs/cmap.rs +++ b/resources/codegen_inputs/cmap.rs @@ -19,7 +19,7 @@ record EncodingRecord { platform_id: PlatformId, /// Platform-specific encoding ID. encoding_id: u16, - /// Byte offset from beginning of table to the subtable for this + /// Byte offset from beginning of the [`Cmap`] table to the subtable for this /// encoding. subtable_offset: Offset32, } @@ -297,12 +297,12 @@ table Cmap14 { record VariationSelector { /// Variation selector var_selector: Uint24, - /// Offset from the start of the format 14 subtable to Default UVS - /// Table. May be 0. + /// Offset from the start of the [`Cmap14`] subtable to Default UVS + /// Table. May be NULL. #[nullable] default_uvs_offset: Offset32, - /// Offset from the start of the format 14 subtable to Non-Default - /// UVS Table. May be 0. + /// Offset from the start of the [`Cmap14`] subtable to Non-Default + /// UVS Table. May be NULL. #[nullable] non_default_uvs_offset: Offset32, } diff --git a/resources/codegen_inputs/colr.rs b/resources/codegen_inputs/colr.rs index 60f5a0ad3..8d92b8665 100644 --- a/resources/codegen_inputs/colr.rs +++ b/resources/codegen_inputs/colr.rs @@ -70,7 +70,7 @@ table BaseGlyphList { record BaseGlyphPaint { /// Glyph ID of the base glyph. glyph_id: GlyphId, - /// Offset to a Paint table. + /// Offset to a Paint table, from the beginning of the [`BaseGlyphList`] table. paint_offset: Offset32, } @@ -99,7 +99,7 @@ record Clip { start_glyph_id: GlyphId, /// Last glyph ID in the range. end_glyph_id: GlyphId, - /// Offset to a ClipBox table. + /// Offset to a ClipBox table, from the beginning of the [`ClipList`] table. clip_box_offset: Offset24, } diff --git a/write-fonts/generated/generated_cmap.rs b/write-fonts/generated/generated_cmap.rs index 8b8a2772a..b719f3eff 100644 --- a/write-fonts/generated/generated_cmap.rs +++ b/write-fonts/generated/generated_cmap.rs @@ -77,7 +77,7 @@ pub struct EncodingRecord { pub platform_id: PlatformId, /// Platform-specific encoding ID. pub encoding_id: u16, - /// Byte offset from beginning of table to the subtable for this + /// Byte offset from beginning of the [`Cmap`] table to the subtable for this /// encoding. pub subtable: OffsetMarker, } @@ -1263,11 +1263,11 @@ impl<'a> FontRead<'a> for Cmap14 { pub struct VariationSelector { /// Variation selector pub var_selector: Uint24, - /// Offset from the start of the format 14 subtable to Default UVS - /// Table. May be 0. + /// Offset from the start of the [`Cmap14`] subtable to Default UVS + /// Table. May be NULL. pub default_uvs: NullableOffsetMarker, - /// Offset from the start of the format 14 subtable to Non-Default - /// UVS Table. May be 0. + /// Offset from the start of the [`Cmap14`] subtable to Non-Default + /// UVS Table. May be NULL. pub non_default_uvs: NullableOffsetMarker, }