Merge pull request #723 from godot-rust/qol/document-experimental-apis

Annotate `#[doc(cfg)]` for all generated experimental classes

Author: Bromeon

godot-bindings/Cargo.toml

@@ -7,7 +7,7 @@ license = "MPL-2.0"
 keywords = ["gamedev", "godot", "engine", "ffi", "sys"]
 categories = ["game-engines", "graphics"]
 
-# Since features are additive and we want the user to user prebuilt by default, we need to have `prebuilt-godot` as the
+# Since features are additive, and we want the user to user prebuilt by default, we need to have `prebuilt-godot` as the
 # default feature. However, it's not possible to _disable_ the prebuilt dependency when specifying `api-custom` (without
 # requiring no-default-features), so we unfortunately still need to depend on prebuilt and just ignore it.
 # The artifact generator explicitly excludes that though (to avoid a quasi-circular dependency back to its repo).
@@ -34,3 +34,8 @@ which = { optional = true, version = "6" }
 [dev-dependencies]
 # For tests, we need regex unconditionally. Keep this in sync with above dependency.
 regex = { version = "1.5.5", default-features = false, features = ["std", "unicode-gencat"] }
+
+# https://docs.rs/about/metadata
+[package.metadata.docs.rs]
+features = ["experimental-godot-api"]
+rustdoc-args = ["--cfg", "published_docs"]

godot-cell/Cargo.toml

@@ -12,3 +12,8 @@ proptest = ["dep:proptest"]
 
 [dependencies]
 proptest = { version = "1.4.0", optional = true }
+
+# https://docs.rs/about/metadata
+[package.metadata.docs.rs]
+features = ["experimental-godot-api"]
+rustdoc-args = ["--cfg", "published_docs"]

godot-codegen/Cargo.toml

@@ -33,3 +33,8 @@ regex = { version = "1.5.5", default-features = false, features = ["std", "unico
 
 [build-dependencies]
 godot-bindings = { path = "../godot-bindings" } # emit_godot_version_cfg
+
+# https://docs.rs/about/metadata
+[package.metadata.docs.rs]
+features = ["experimental-godot-api"]
+rustdoc-args = ["--cfg", "published_docs"]

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,42 @@ 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();
 
+    // These attributes are for our nightly docs pipeline, which enables "only available in ..." labels in the HTML output. The website CI sets
+    // RUSTFLAGS="--cfg published_docs" during the `cargo +nightly doc` invocation. They are applied to classes, interface traits, sidecar modules,
+    // the notification enum, other enums and default-parameter extender structs.
+    //
+    // In other parts of the codebase, #[cfg] statements are replaced with #[doc(cfg)] using sed/sd. However, that doesn't work here, because
+    // generated files are output in ./target/build/debug. Upon doing sed/sd replacements on these files, cargo doc will either treat them as
+    // unchanged (doing nothing), or rebuild the generated files into a _different_ folder. Therefore, the generator itself must already provide
+    // the correct attributes from the start.
+    let (cfg_attributes, cfg_inner_attributes);
+    if class.is_experimental {
+        cfg_attributes = quote! {
+            // #[cfg(feature = "experimental-godot-api")]
+            #[cfg_attr(published_docs, doc(cfg(feature = "experimental-godot-api")))]
+        };
+        cfg_inner_attributes = quote! {
+            // #![cfg(feature = "experimental-godot-api")]
+            #![cfg_attr(published_docs, doc(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 +143,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 +181,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 +192,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 +433,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 +452,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 +522,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.