Determine interface trait presence by abstract/final status

Collect information about all "abstract" classes in Godot.

Disable `I*` traits whenever they are final, meaning either:
* a singleton
* abstract (in Godot terms), i.e. non-inheritable outside engine itself

Document the trait relation, and explicitly exclude intermediate interfaces
associated with final classes.

Author: Bromeon

godot-codegen/src/context.rs

@@ -23,6 +23,8 @@ pub struct Context<'a> {
     native_structures_types: HashSet<&'a str>,
     singletons: HashSet<&'a str>,
     inheritance_tree: InheritanceTree,
+    /// Which interface traits are generated (`false` for "Godot-abstract"/final classes).
+    classes_final: HashMap<TyName, bool>,
     cached_rust_types: HashMap<GodotTy, RustTy>,
     notifications_by_class: HashMap<TyName, Vec<(Ident, i32)>>,
     classes_with_signals: HashSet<TyName>,
@@ -64,13 +66,16 @@ impl<'a> Context<'a> {
                 continue;
             }
 
-            // Populate class lookup by name
+            // Populate class lookup by name.
             engine_classes.insert(class_name.clone(), class);
 
             if !option_as_slice(&class.signals).is_empty() {
                 ctx.classes_with_signals.insert(class_name.clone());
             }
 
+            ctx.classes_final
+                .insert(class_name.clone(), ctx.is_class_final(&class_name));
+
             // Populate derived-to-base relations
             if let Some(base) = class.inherits.as_ref() {
                 let base_name = TyName::from_godot(base);
@@ -245,6 +250,21 @@ impl<'a> Context<'a> {
             .unwrap_or_else(|| panic!("did not register table index for key {:?}", key))
     }
 
+    /// Whether an interface trait is generated for a class.
+    ///
+    /// False if the class is "Godot-abstract"/final, thus there are no virtual functions to inherit.
+    fn is_class_final(&self, class_name: &TyName) -> bool {
+        debug_assert!(
+            !self.singletons.is_empty(),
+            "initialize singletons before final-check"
+        );
+
+        self.singletons.contains(class_name.godot_ty.as_str())
+            || special_cases::is_class_abstract(class_name)
+    }
+
+    // ------------------------------------------------------------------------------------------------------------------------------------------
+
     /// Checks if this is a builtin type (not `Object`).
     ///
     /// Note that builtins != variant types.
@@ -275,6 +295,15 @@ impl<'a> Context<'a> {
         self.singletons.contains(class_name.godot_ty.as_str())
     }
 
+    pub fn is_final(&self, class_name: &TyName) -> bool {
+        *self.classes_final.get(class_name).unwrap_or_else(|| {
+            panic!(
+                "queried final status for class {}, but it is not registered",
+                class_name.godot_ty
+            )
+        })
+    }
+
     pub fn inheritance_tree(&self) -> &InheritanceTree {
         &self.inheritance_tree
     }
@@ -317,7 +346,6 @@ impl<'a> Context<'a> {
         assert!(prev.is_none(), "no overwrites of RustTy");
     }
 }
-
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
 #[derive(Clone)]
@@ -379,7 +407,7 @@ impl InheritanceTree {
         self.derived_to_base.get(derived_name).cloned()
     }
 
-    /// Returns all base classes, without the class itself, in order from nearest to furthest (object).
+    /// Returns all base classes, without the class itself, in order from nearest to furthest (`Object`).
     pub fn collect_all_bases(&self, derived_name: &TyName) -> Vec<TyName> {
         let mut upgoer = derived_name;
         let mut result = vec![];

godot-codegen/src/generator/classes.rs

@@ -15,7 +15,7 @@ use crate::models::domain::{
     ModName, TyName,
 };
 use crate::util::{ident, make_string_name};
-use crate::{conv, util, SubmitFn};
+use crate::{util, SubmitFn};
 use proc_macro2::{Ident, TokenStream};
 use quote::{format_ident, quote};
 use std::path::Path;
@@ -91,10 +91,9 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
     let class_name_cstr = util::c_str(godot_class_str);
 
     // Idents and tokens
-    let (base_ty, base_ident_opt) = match class.inherits.as_ref() {
-        Some(base) => {
-            let base = ident(&conv::to_pascal_case(base));
-            (quote! { crate::classes::#base }, Some(base))
+    let (base_ty, base_ident_opt) = match class.base_class.as_ref() {
+        Some(TyName { rust_ty, .. }) => {
+            (quote! { crate::classes::#rust_ty }, Some(rust_ty.clone()))
         }
         None => (quote! { crate::obj::NoBase }, None),
     };
@@ -164,14 +163,13 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
     // Classes that can't be inherited from don't need to provide an interface with overridable virtual methods.
     let has_interface_trait = !class.is_final;
     let interface_trait = if has_interface_trait {
-        let virtual_trait_str = class_name.virtual_trait_name();
         virtual_traits::make_virtual_methods_trait(
             class,
             &all_bases,
-            &virtual_trait_str,
             &notification_enum_name,
             &cfg_attributes,
             view,
+            ctx,
         )
     } else {
         TokenStream::new()
@@ -305,7 +303,7 @@ fn make_inherits_macro(class: &Class, all_bases: &[TyName]) -> (Option<Ident>, T
     // For final classes, we can directly create a meaningful compile error.
     if class.is_final {
         let error_msg = format!(
-            "Class `{}` is final and cannot be inherited from.",
+            "Class `{}` is final, meaning it cannot be inherited in GDExtension or GDScript.",
             class_name.rust_ty
         );
 
@@ -467,7 +465,8 @@ fn make_constructor_and_default(class: &Class, ctx: &Context) -> Construction {
     let final_doc = if class.is_final {
         Some(
             "\n\n# Final class\n\n\
-            This class is _final_, meaning you cannot inherit from it, and it comes without `I*` interface trait.",
+            This class is _final_, meaning you cannot inherit from it, and it comes without `I*` interface trait. \
+            It is still possible that other Godot classes inherit from it, but that is limited to the engine itself.",
         )
     } else {
         None

godot-codegen/src/generator/docs.rs

@@ -89,7 +89,11 @@ pub fn make_class_doc(
     )
 }
 
-pub fn make_virtual_trait_doc(trait_name_str: &str, class_name: &TyName) -> String {
+pub fn make_virtual_trait_doc(
+    trait_name_str: &str,
+    base_traits: &[(String, bool)],
+    class_name: &TyName,
+) -> String {
     let TyName { rust_ty, godot_ty } = class_name;
 
     let online_link = format!(
@@ -101,12 +105,40 @@ pub fn make_virtual_trait_doc(trait_name_str: &str, class_name: &TyName) -> Stri
         .map(|notes| format!("# Specific notes for this interface\n\n{}", notes))
         .unwrap_or_default();
 
+    // Detect if a base interface exists. This is not the case if intermediate Godot classes are marked "abstract" (aka final for GDExtension).
+    // In such cases, still show interfaces as strikethrough.
+    let inherits_line = if base_traits.is_empty() {
+        String::new()
+    } else {
+        let mut parts = vec![];
+        let mut strikethrough_explanation = "";
+        for (trait_name, is_generated) in base_traits {
+            let part = if *is_generated {
+                format!("[`{trait_name}`][crate::classes::{trait_name}]")
+            } else {
+                strikethrough_explanation =
+                    "  \n(Strike-through means some intermediate Godot classes are marked final, \
+                    and can thus not be inherited by GDExtension.)\n\n";
+                format!("~~`{trait_name}`~~")
+            };
+            parts.push(part);
+        }
+
+        format!(
+            "\n\nBase interfaces: {}.{}",
+            parts.join(" > "),
+            strikethrough_explanation
+        )
+    };
+
     format!(
-        "Virtual methods for class [`{rust_ty}`][crate::classes::{rust_ty}].\
-        \n\n\
-        These methods represent constructors (`init`) or callbacks invoked by the engine.\
+        "# Interface trait for class [`{rust_ty}`][crate::classes::{rust_ty}].\
         \n\n\
-        See also [Godot docs for `{godot_ty}` methods]({online_link}).\n\n{notes}"
+        Functions in this trait represent constructors (`init`) or virtual method callbacks invoked by the engine.\
+        \n\n{notes}\
+        \n\n# Related symbols\
+        {inherits_line}\
+        \n\nSee also [Godot docs for `{godot_ty}` methods]({online_link})."
     )
 }
 

godot-codegen/src/generator/virtual_traits.rs

@@ -5,6 +5,7 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+use crate::context::Context;
 use crate::generator::functions_common::FnCode;
 use crate::generator::{docs, functions_common};
 use crate::models::domain::{
@@ -19,18 +20,20 @@ use std::fmt::Write;
 pub fn make_virtual_methods_trait(
     class: &Class,
     all_base_names: &[TyName],
-    trait_name_str: &str,
     notification_enum_name: &Ident,
     cfg_attributes: &TokenStream,
     view: &ApiView,
+    ctx: &Context,
 ) -> TokenStream {
-    let trait_name = ident(trait_name_str);
     let class_name = &class.name().rust_ty;
+    let trait_name_str = class.name().virtual_trait_name();
+    let trait_name = ident(&trait_name_str);
 
     let (virtual_method_fns, extra_docs) = make_all_virtual_methods(class, all_base_names, view);
     let special_virtual_methods = make_special_virtual_methods(notification_enum_name);
 
-    let trait_doc = docs::make_virtual_trait_doc(trait_name_str, class.name());
+    let base_traits = collect_base_traits(all_base_names, ctx);
+    let trait_doc = docs::make_virtual_trait_doc(&trait_name_str, &base_traits, class.name());
 
     quote! {
         #[doc = #trait_doc]
@@ -45,6 +48,22 @@ pub fn make_virtual_methods_trait(
     }
 }
 
+/// Collects base traits (without current) in order towards root.
+///
+/// Results contain the name of the trait `I*` and whether code for it is generated (e.g. `false` for final classes).
+fn collect_base_traits(all_base_classes: &[TyName], ctx: &Context) -> Vec<(String, bool)> {
+    let mut base_traits = vec![];
+
+    for class_name in all_base_classes {
+        let trait_name = class_name.virtual_trait_name();
+        let has_interface_trait = !ctx.is_final(class_name);
+
+        base_traits.push((trait_name, has_interface_trait))
+    }
+
+    base_traits
+}
+
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 // Implementation
 

godot-codegen/src/models/domain.rs

@@ -161,9 +161,8 @@ pub struct Class {
     pub is_refcounted: bool,
     pub is_instantiable: bool,
     pub is_experimental: bool,
-    /// `true` if inheriting the class is disallowed.
     pub is_final: bool,
-    pub inherits: Option<String>,
+    pub base_class: Option<TyName>,
     pub api_level: ClassCodegenLevel,
     pub constants: Vec<ClassConstant>,
     pub enums: Vec<Enum>,
@@ -762,6 +761,9 @@ impl TyName {
         }
     }
 
+    /// Get name of virtual interface trait.
+    ///
+    /// This is also valid if the outer class generates no traits (e.g. to explicitly mention absence in docs).
     pub fn virtual_trait_name(&self) -> String {
         format!("I{}", self.rust_ty)
     }

godot-codegen/src/models/domain_mapping.rs

@@ -91,9 +91,11 @@ impl Class {
 
         // Already checked in is_class_deleted(), but code remains more maintainable if those are separate, and it's cheap to validate.
         let is_experimental = special_cases::is_class_experimental(&ty_name.godot_ty);
-        let is_instantiable =
-            special_cases::is_class_instantiable(&ty_name).unwrap_or(json.is_instantiable);
-        let is_final = ctx.is_singleton(&ty_name) || special_cases::is_class_final(&ty_name);
+
+        let is_instantiable = special_cases::is_class_instantiable(&ty_name) //.
+            .unwrap_or(json.is_instantiable);
+
+        let is_final = ctx.is_final(&ty_name);
 
         let mod_name = ModName::from_godot(&ty_name.godot_ty);
 
@@ -126,6 +128,11 @@ impl Class {
             })
             .collect();
 
+        let base_class = json
+            .inherits
+            .as_ref()
+            .map(|godot_name| TyName::from_godot(godot_name));
+
         Some(Self {
             common: ClassCommons {
                 name: ty_name,
@@ -135,7 +142,7 @@ impl Class {
             is_instantiable,
             is_experimental,
             is_final,
-            inherits: json.inherits.clone(),
+            base_class,
             api_level: get_api_level(json),
             constants,
             enums,