[codegen] Improve generated docs for typed offset getters

font-codegen/src/fields.rs

@@ -812,6 +812,14 @@ impl Field {
             quote!(let args = #args;)
         });
 
+        let extra_docs_if_input_data = input_data_if_needed.is_some().then(|| {
+            quote! {
+                #[doc = ""]
+                #[doc = " The `data` argument should generally be retrieved via the `offset_data`"]
+                #[doc = " method of the parent table, but you should consult the docs of the"]
+                #[doc = " referenced method for more information."]
+            }
+        });
         if self.is_array() {
             let OffsetTarget::Table(target_ident) = target else {
                 panic!("I don't think arrays of offsets to arrays are in the spec?");
@@ -843,6 +851,7 @@ impl Field {
 
             Some(quote! {
                 #[doc = #docs]
+                #extra_docs_if_input_data
                 pub fn #getter_name (&self #input_data_if_needed) -> #return_type #where_read_clause  {
                     #data_alias_if_needed
                     #bind_offsets
@@ -870,6 +879,7 @@ impl Field {
             };
             Some(quote! {
                 #[doc = #docs]
+                #extra_docs_if_input_data
                 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

@@ -390,6 +390,10 @@ impl BaseScriptRecord {
     }
 
     /// Attempt to resolve [`base_script_offset`][Self::base_script_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn base_script<'a>(&self, data: FontData<'a>) -> Result<BaseScript<'a>, ReadError> {
         self.base_script_offset().resolve(data)
     }
@@ -569,6 +573,10 @@ impl BaseLangSysRecord {
     }
 
     /// Attempt to resolve [`min_max_offset`][Self::min_max_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn min_max<'a>(&self, data: FontData<'a>) -> Result<MinMax<'a>, ReadError> {
         self.min_max_offset().resolve(data)
     }
@@ -862,6 +870,10 @@ impl FeatMinMaxRecord {
     }
 
     /// Attempt to resolve [`min_coord_offset`][Self::min_coord_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn min_coord<'a>(&self, data: FontData<'a>) -> Option<Result<MinMax<'a>, ReadError>> {
         self.min_coord_offset().resolve(data)
     }
@@ -873,6 +885,10 @@ impl FeatMinMaxRecord {
     }
 
     /// Attempt to resolve [`max_coord_offset`][Self::max_coord_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     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

@@ -128,6 +128,10 @@ impl EncodingRecord {
     }
 
     /// Attempt to resolve [`subtable_offset`][Self::subtable_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn subtable<'a>(&self, data: FontData<'a>) -> Result<CmapSubtable<'a>, ReadError> {
         self.subtable_offset().resolve(data)
     }
@@ -1635,6 +1639,10 @@ impl VariationSelector {
     }
 
     /// Attempt to resolve [`default_uvs_offset`][Self::default_uvs_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn default_uvs<'a>(&self, data: FontData<'a>) -> Option<Result<DefaultUvs<'a>, ReadError>> {
         self.default_uvs_offset().resolve(data)
     }
@@ -1646,6 +1654,10 @@ impl VariationSelector {
     }
 
     /// Attempt to resolve [`non_default_uvs_offset`][Self::non_default_uvs_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn non_default_uvs<'a>(
         &self,
         data: FontData<'a>,

read-fonts/generated/generated_colr.rs

@@ -500,6 +500,10 @@ impl BaseGlyphPaint {
     }
 
     /// Attempt to resolve [`paint_offset`][Self::paint_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn paint<'a>(&self, data: FontData<'a>) -> Result<Paint<'a>, ReadError> {
         self.paint_offset().resolve(data)
     }
@@ -736,6 +740,10 @@ impl Clip {
     }
 
     /// Attempt to resolve [`clip_box_offset`][Self::clip_box_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     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

@@ -1009,6 +1009,10 @@ impl MarkRecord {
     }
 
     /// Attempt to resolve [`mark_anchor_offset`][Self::mark_anchor_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn mark_anchor<'a>(&self, data: FontData<'a>) -> Result<AnchorTable<'a>, ReadError> {
         self.mark_anchor_offset().resolve(data)
     }
@@ -2234,6 +2238,10 @@ impl EntryExitRecord {
     }
 
     /// Attempt to resolve [`entry_anchor_offset`][Self::entry_anchor_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn entry_anchor<'a>(
         &self,
         data: FontData<'a>,
@@ -2248,6 +2256,10 @@ impl EntryExitRecord {
     }
 
     /// Attempt to resolve [`exit_anchor_offset`][Self::exit_anchor_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn exit_anchor<'a>(
         &self,
         data: FontData<'a>,
@@ -2562,6 +2574,10 @@ impl<'a> BaseRecord<'a> {
     }
 
     /// A dynamically resolving wrapper for [`base_anchor_offsets`][Self::base_anchor_offsets].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn base_anchors(
         &self,
         data: FontData<'a>,
@@ -3017,6 +3033,10 @@ impl<'a> ComponentRecord<'a> {
     }
 
     /// A dynamically resolving wrapper for [`ligature_anchor_offsets`][Self::ligature_anchor_offsets].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn ligature_anchors(
         &self,
         data: FontData<'a>,
@@ -3358,6 +3378,10 @@ impl<'a> Mark2Record<'a> {
     }
 
     /// A dynamically resolving wrapper for [`mark2_anchor_offsets`][Self::mark2_anchor_offsets].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn mark2_anchors(
         &self,
         data: FontData<'a>,

read-fonts/generated/generated_layout.rs

@@ -103,6 +103,10 @@ impl ScriptRecord {
     }
 
     /// Attempt to resolve [`script_offset`][Self::script_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn script<'a>(&self, data: FontData<'a>) -> Result<Script<'a>, ReadError> {
         self.script_offset().resolve(data)
     }
@@ -257,6 +261,10 @@ impl LangSysRecord {
     }
 
     /// Attempt to resolve [`lang_sys_offset`][Self::lang_sys_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn lang_sys<'a>(&self, data: FontData<'a>) -> Result<LangSys<'a>, ReadError> {
         self.lang_sys_offset().resolve(data)
     }
@@ -483,6 +491,10 @@ impl FeatureRecord {
     }
 
     /// Attempt to resolve [`feature_offset`][Self::feature_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     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)
@@ -3911,6 +3923,10 @@ impl FeatureVariationRecord {
     }
 
     /// Attempt to resolve [`condition_set_offset`][Self::condition_set_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn condition_set<'a>(
         &self,
         data: FontData<'a>,
@@ -3925,6 +3941,10 @@ impl FeatureVariationRecord {
     }
 
     /// Attempt to resolve [`feature_table_substitution_offset`][Self::feature_table_substitution_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn feature_table_substitution<'a>(
         &self,
         data: FontData<'a>,

read-fonts/generated/generated_test_records.rs

@@ -259,6 +259,10 @@ impl ContainsOffests {
     }
 
     /// Attempt to resolve [`array_offset`][Self::array_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     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)
@@ -269,6 +273,10 @@ impl ContainsOffests {
     }
 
     /// Attempt to resolve [`other_offset`][Self::other_offset].
+    ///
+    /// The `data` argument should generally be retrieved via the `offset_data`
+    /// method of the parent table, but you should consult the docs of the
+    /// referenced method for more information.
     pub fn other<'a>(&self, data: FontData<'a>) -> Result<BasicTable<'a>, ReadError> {
         self.other_offset().resolve(data)
     }