Annotate #[cfg(feature = "experimental-godot-api")] for all generated experimental classes

This is not strictly necessary, because those classes are already excluded by codegen when
the feature is disabled. However, explicitly adding the #[cfg(...)] helps our doc pipeline
to recognize and annotate such classes.

This commit is a bit involved, because it first adds an is_experimental property to the
domain model, and then generates #[cfg] for all the public symbols -- not just the class
itself, but its module, interface trait, related enums and ex-builder structs.

Author: Bromeon

godot-codegen/src/generator/builtins.rs

@@ -101,7 +101,7 @@ fn make_builtin_class(class: &BuiltinClass, ctx: &mut Context) -> GeneratedBuilt
     } = make_builtin_methods(class, &class.methods, ctx);
 
     let imports = util::make_imports();
-    let enums = enums::make_enums(&class.enums);
+    let enums = enums::make_enums(&class.enums, &TokenStream::new());
     let special_constructors = make_special_builtin_methods(class.name(), ctx);
 
     // mod re_export needed, because class should not appear inside the file module, and we can't re-export private struct as pub
@@ -245,5 +245,6 @@ fn make_builtin_method_definition(
             ptrcall_invocation,
         },
         safety_doc,
+        &TokenStream::new(),
     )
 }

godot-codegen/src/generator/classes.rs

@@ -94,19 +94,31 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
     let api_level = class.api_level;
     let init_level = api_level.to_init_level();
 
+    // This is not strictly needed because the classes are included/excluded by codegen depending on that feature, however it helps the
+    // docs pipeline which converts #[ cfg(...) ] to #[ doc(cfg(...)) ], resulting in "only available in ..." labels in the HTML output.
+    // (The above has spaces because there's a primitive sed expression at work :) )
+    let (cfg_attributes, cfg_inner_attributes);
+    if class.is_experimental {
+        cfg_attributes = quote! { #[cfg(feature = "experimental-godot-api")] };
+        cfg_inner_attributes = quote! { #![cfg(feature = "experimental-godot-api")] };
+    } else {
+        cfg_attributes = TokenStream::new();
+        cfg_inner_attributes = TokenStream::new();
+    };
+
     let FnDefinitions {
         functions: methods,
         builders,
-    } = make_class_methods(class, &class.methods, ctx);
+    } = make_class_methods(class, &class.methods, &cfg_attributes, ctx);
 
-    let enums = enums::make_enums(&class.enums);
+    let enums = enums::make_enums(&class.enums, &cfg_attributes);
     let constants = constants::make_constants(&class.constants);
     let inherits_macro = format_ident!("unsafe_inherits_transitive_{}", class_name.rust_ty);
     let deref_impl = make_deref_impl(class_name, &base_ty);
 
     let all_bases = ctx.inheritance_tree().collect_all_bases(class_name);
     let (notification_enum, notification_enum_name) =
-        notifications::make_notification_enum(class_name, &all_bases, ctx);
+        notifications::make_notification_enum(class_name, &all_bases, &cfg_attributes, ctx);
 
     // Associated "sidecar" module is made public if there are other symbols related to the class, which are not
     // in top-level godot::engine module (notification enums are not in the sidecar, but in godot::engine::notify).
@@ -120,11 +132,13 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
         has_sidecar_module,
     );
     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,
     );
 
@@ -156,6 +170,7 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
     let imports = util::make_imports();
     let tokens = quote! {
         #![doc = #module_doc]
+        #cfg_inner_attributes
 
         #imports
         use crate::engine::notify::*;
@@ -166,6 +181,7 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
 
             #[doc = #class_doc]
             #[doc = #construct_doc]
+            #cfg_attributes
             #[derive(Debug)]
             #[repr(C)]
             pub struct #class_name {
@@ -406,12 +422,17 @@ fn make_bounds(class: &Class) -> (Ident, Ident) {
     (assoc_memory, assoc_dyn_memory)
 }
 
-fn make_class_methods(class: &Class, methods: &[ClassMethod], ctx: &mut Context) -> FnDefinitions {
+fn make_class_methods(
+    class: &Class,
+    methods: &[ClassMethod],
+    cfg_attributes: &TokenStream,
+    ctx: &mut Context,
+) -> FnDefinitions {
     let get_method_table = class.api_level.table_global_getter();
 
-    let definitions = methods
-        .iter()
-        .map(|method| make_class_method_definition(class, method, &get_method_table, ctx));
+    let definitions = methods.iter().map(|method| {
+        make_class_method_definition(class, method, &get_method_table, cfg_attributes, ctx)
+    });
 
     FnDefinitions::expand(definitions)
 }
@@ -420,6 +441,7 @@ fn make_class_method_definition(
     class: &Class,
     method: &ClassMethod,
     get_method_table: &Ident,
+    cfg_attributes: &TokenStream,
     ctx: &mut Context,
 ) -> FnDefinition {
     let FnDirection::Outbound { hash } = method.direction() else {
@@ -489,5 +511,6 @@ fn make_class_method_definition(
             ptrcall_invocation,
         },
         None,
+        cfg_attributes,
     )
 }

godot-codegen/src/generator/default_parameters.rs

@@ -17,6 +17,7 @@ pub fn make_function_definition_with_defaults(
     sig: &dyn Function,
     code: &FnCode,
     full_fn_name: &Ident,
+    cfg_attributes: &TokenStream,
 ) -> (TokenStream, TokenStream) {
     let (default_fn_params, required_fn_params): (Vec<_>, Vec<_>) = sig
         .params()
@@ -62,6 +63,7 @@ pub fn make_function_definition_with_defaults(
     let builders = quote! {
         #[doc = #builder_doc]
         #[must_use]
+        #cfg_attributes
         pub struct #builder_ty #builder_lifetime {
             // #builder_surround_ref
             #( #builder_fields, )*

godot-codegen/src/generator/enums.rs

@@ -13,11 +13,11 @@ use crate::models::domain::{Enum, Enumerator};
 use proc_macro2::TokenStream;
 use quote::{quote, ToTokens};
 
-pub fn make_enums(enums: &[Enum]) -> TokenStream {
+pub fn make_enums(enums: &[Enum], cfg_attributes: &TokenStream) -> TokenStream {
     let definitions = enums.iter().map(make_enum_definition);
 
     quote! {
-        #( #definitions )*
+        #( #cfg_attributes #definitions )*
     }
 }
 

godot-codegen/src/generator/functions_common.rs

@@ -86,11 +86,12 @@ pub fn make_function_definition(
     sig: &dyn Function,
     code: &FnCode,
     safety_doc: Option<TokenStream>,
+    cfg_attributes: &TokenStream,
 ) -> FnDefinition {
     let has_default_params = default_parameters::function_uses_default_params(sig);
     let vis = if has_default_params {
         // Public API mapped by separate function.
-        // Needs to be crate-public because default-arg builder lives outside of the module.
+        // Needs to be crate-public because default-arg builder lives outside the module.
         quote! { pub(crate) }
     } else {
         make_vis(sig.is_private())
@@ -127,7 +128,12 @@ pub fn make_function_definition(
     };
 
     let (default_fn_code, default_structs_code) = if has_default_params {
-        default_parameters::make_function_definition_with_defaults(sig, code, &primary_fn_name)
+        default_parameters::make_function_definition_with_defaults(
+            sig,
+            code,
+            &primary_fn_name,
+            cfg_attributes,
+        )
     } else {
         (TokenStream::new(), TokenStream::new())
     };

godot-codegen/src/generator/notifications.rs

@@ -61,6 +61,7 @@ pub fn make_notify_methods(class_name: &TyName, ctx: &mut Context) -> TokenStrea
 pub fn make_notification_enum(
     class_name: &TyName,
     all_bases: &Vec<TyName>,
+    cfg_attributes: &TokenStream,
     ctx: &mut Context,
 ) -> (Option<TokenStream>, Ident) {
     let Some(all_constants) = ctx.notification_constants(class_name) else {
@@ -98,6 +99,7 @@ pub fn make_notification_enum(
         /// notifications defined in base classes.
         #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
         #[repr(i32)]
+        #cfg_attributes
         pub enum #enum_name {
             #(
                 #notification_enumerators_pascal = #notification_enumerators_ord,

godot-codegen/src/generator/utility_functions.rs

@@ -79,6 +79,7 @@ pub(crate) fn make_utility_function_definition(function: &UtilityFunction) -> To
             ptrcall_invocation,
         },
         None,
+        &TokenStream::new(),
     );
 
     // Utility functions have no builders.

godot-codegen/src/generator/virtual_traits.rs

@@ -19,19 +19,21 @@ pub fn make_virtual_methods_trait(
     all_base_names: &[TyName],
     trait_name_str: &str,
     notification_enum_name: &Ident,
+    cfg_attributes: &TokenStream,
     view: &ApiView,
 ) -> TokenStream {
     let trait_name = ident(trait_name_str);
 
     let virtual_method_fns = make_all_virtual_methods(class, all_base_names, view);
-    let special_virtual_methods = special_virtual_methods(notification_enum_name);
+    let special_virtual_methods = make_special_virtual_methods(notification_enum_name);
 
     let trait_doc = docs::make_virtual_trait_doc(trait_name_str, class.name());
 
     quote! {
         #[doc = #trait_doc]
         #[allow(unused_variables)]
         #[allow(clippy::unimplemented)]
+        #cfg_attributes
         pub trait #trait_name: crate::obj::GodotClass + crate::private::You_forgot_the_attribute__godot_api {
             #special_virtual_methods
             #( #virtual_method_fns )*
@@ -42,7 +44,7 @@ pub fn make_virtual_methods_trait(
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 // Implementation
 
-fn special_virtual_methods(notification_enum_name: &Ident) -> TokenStream {
+fn make_special_virtual_methods(notification_enum_name: &Ident) -> TokenStream {
     quote! {
         #[doc(hidden)]
         fn register_class(builder: &mut crate::builder::ClassBuilder<Self>) {
@@ -125,6 +127,7 @@ fn make_virtual_method(method: &ClassMethod) -> Option<TokenStream> {
             ptrcall_invocation: TokenStream::new(),
         },
         None,
+        &TokenStream::new(),
     );
 
     // Virtual methods have no builders.

godot-codegen/src/models/domain.rs

@@ -160,6 +160,7 @@ pub struct Class {
     pub common: ClassCommons,
     pub is_refcounted: bool,
     pub is_instantiable: bool,
+    pub is_experimental: bool,
     pub inherits: Option<String>,
     pub api_level: ClassCodegenLevel,
     pub constants: Vec<ClassConstant>,

godot-codegen/src/models/domain_mapping.rs

@@ -87,6 +87,9 @@ impl Class {
             return None;
         }
 
+        // 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 mod_name = ModName::from_godot(&ty_name.godot_ty);
 
         let constants = option_as_slice(&json.constants)
@@ -117,6 +120,7 @@ impl Class {
             },
             is_refcounted: json.is_refcounted,
             is_instantiable: json.is_instantiable,
+            is_experimental,
             inherits: json.inherits.clone(),
             api_level: get_api_level(json),
             constants,