Merge pull request #1182 from godot-rust/feature/final-classes-no-interface

Final classes no longer have a `I*` interface trait

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;
@@ -45,6 +45,7 @@ pub fn generate_class_files(
             own_notification_enum_name: generated_class.notification_enum.try_to_own_name(),
             inherits_macro_ident: generated_class.inherits_macro_ident,
             is_pub_sidecar: generated_class.has_sidecar_module,
+            has_interface_trait: generated_class.has_interface_trait,
         });
     }
 
@@ -63,6 +64,7 @@ struct GeneratedClass {
     inherits_macro_ident: Option<Ident>,
     /// Sidecars are the associated modules with related enum/flag types, such as `node_3d` for `Node3D` class.
     has_sidecar_module: bool,
+    has_interface_trait: bool,
 }
 
 struct GeneratedClassModule {
@@ -71,6 +73,7 @@ struct GeneratedClassModule {
     own_notification_enum_name: Option<Ident>,
     inherits_macro_ident: Option<Ident>,
     is_pub_sidecar: bool,
+    has_interface_trait: bool,
 }
 
 struct Construction {
@@ -86,13 +89,11 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
     // Strings
     let godot_class_str = &class_name.godot_ty;
     let class_name_cstr = util::c_str(godot_class_str);
-    let virtual_trait_str = class_name.virtual_trait_name();
 
     // 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),
     };
@@ -157,25 +158,32 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
     // This checks if token streams (i.e. code) is empty.
     let has_sidecar_module = !enums.is_empty() || !builders.is_empty() || has_own_signals;
 
+    let module_doc = docs::make_module_doc(class_name);
+
+    // 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 {
+        virtual_traits::make_virtual_methods_trait(
+            class,
+            &all_bases,
+            &notification_enum_name,
+            &cfg_attributes,
+            view,
+            ctx,
+        )
+    } else {
+        TokenStream::new()
+    };
+
     let class_doc = docs::make_class_doc(
         class_name,
         base_ident_opt,
         notification_enum.is_some(),
         has_sidecar_module,
+        has_interface_trait,
         has_own_signals,
     );
 
-    let module_doc = docs::make_module_doc(class_name);
-
-    let virtual_trait = virtual_traits::make_virtual_methods_trait(
-        class,
-        &all_bases,
-        &virtual_trait_str,
-        &notification_enum_name,
-        &cfg_attributes,
-        view,
-    );
-
     // notify() and notify_reversed() are added after other methods, to list others first in docs.
     let notify_methods = notifications::make_notify_methods(class_name, ctx);
 
@@ -220,7 +228,7 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
                 // The RawGd<T>'s identity field can be None because of generality (it can represent null pointers, as opposed to Gd<T>).
                 rtti: Option<crate::private::ObjectRtti>,
             }
-            #virtual_trait
+            #interface_trait
             #notification_enum
             impl #class_name {
                 #constructor
@@ -274,6 +282,7 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
         },
         inherits_macro_ident,
         has_sidecar_module,
+        has_interface_trait,
     }
 }
 
@@ -294,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
         );
 
@@ -351,10 +360,14 @@ fn make_class_module_file(classes_and_modules: Vec<GeneratedClassModule>) -> Tok
 
         let vis = is_pub.then_some(quote! { pub });
 
+        let interface_reexport = m.has_interface_trait.then(|| {
+            quote! { pub use #module_name::re_export::#virtual_trait_name; }
+        });
+
         let class_decl = quote! {
             #vis mod #module_name;
             pub use #module_name::re_export::#class_name;
-            pub use #module_name::re_export::#virtual_trait_name;
+            #interface_reexport
         };
         class_decls.push(class_decl);
 
@@ -452,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.",
+            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

@@ -19,6 +19,7 @@ pub fn make_class_doc(
     base_ident_opt: Option<Ident>,
     has_notification_enum: bool,
     has_sidecar_module: bool,
+    has_interface_trait: bool,
     has_signal_collection: bool,
 ) -> String {
     let TyName { rust_ty, godot_ty } = class_name;
@@ -62,7 +63,12 @@ pub fn make_class_doc(
         godot_ty.to_ascii_lowercase()
     );
 
-    let trait_name = class_name.virtual_trait_name();
+    let interface_trait_line = if has_interface_trait {
+        let trait_name = class_name.virtual_trait_name();
+        format!("* [`{trait_name}`][crate::classes::{trait_name}]: virtual methods\n")
+    } else {
+        String::new()
+    };
 
     let notes = special_cases::get_class_extra_docs(class_name)
         .map(|notes| format!("# Specific notes for this class\n\n{}", notes))
@@ -75,15 +81,19 @@ pub fn make_class_doc(
         \
         Related symbols:\n\n\
         {sidecar_signal_lines}\
-        * [`{trait_name}`][crate::classes::{trait_name}]: virtual methods\n\
+        {interface_trait_line}\
         {signal_line}\
         {notify_line}\
         \n\n\
         See also [Godot docs for `{godot_ty}`]({online_link}).\n\n{notes}",
     )
 }
 
-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!(
@@ -95,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)
     }