[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

@@ -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<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

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<BaseScript<'a>, 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<MinMax<'a>, 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<Result<MinMax<'a>, 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<Result<MinMax<'a>, ReadError>> {
         self.max_coord_offset().resolve(data)
     }

read-fonts/generated/generated_cmap.rs

@@ -105,7 +105,7 @@ pub struct EncodingRecord {
     pub platform_id: BigEndian<PlatformId>,
     /// Platform-specific encoding ID.
     pub encoding_id: BigEndian<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_offset: BigEndian<Offset32>,
 }
@@ -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<CmapSubtable<'a>, 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<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_offset: BigEndian<Nullable<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.
     pub non_default_uvs_offset: BigEndian<Nullable<Offset32>>,
 }
 
@@ -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<Offset32> {
         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<Result<DefaultUvs<'a>, 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<Offset32> {
         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>,

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<GlyphId>,
-    /// Offset to a Paint table.
+    /// Offset to a Paint table, from the beginning of the [`BaseGlyphList`] table.
     pub paint_offset: BigEndian<Offset32>,
 }
 
@@ -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<Paint<'a>, ReadError> {
         self.paint_offset().resolve(data)
     }
@@ -715,7 +718,7 @@ pub struct Clip {
     pub start_glyph_id: BigEndian<GlyphId>,
     /// Last glyph ID in the range.
     pub end_glyph_id: BigEndian<GlyphId>,
-    /// Offset to a ClipBox table.
+    /// Offset to a ClipBox table, from the beginning of the [`ClipList`] table.
     pub clip_box_offset: BigEndian<Offset24>,
 }
 
@@ -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<ClipBox<'a>, ReadError> {
         self.clip_box_offset().resolve(data)
     }

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<AnchorTable<'a>, 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>,

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<Script<'a>, 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<LangSys<'a>, 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<Feature<'a>, 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>,