docs changes

Author: makspll

crates/bevy_mod_scripting_bindings/src/function/namespace.rs

@@ -1,6 +1,7 @@
 //! A module for managing namespaces for functions
 
 use crate::{
+    DummyScriptFunctionRegistry, ScriptFunctionRegistryArc,
     docgen::info::GetFunctionInfo,
     function::script_function::{AppScriptFunctionRegistry, ScriptFunction},
 };
@@ -66,6 +67,8 @@ impl Namespace {
 
 /// A convenience builder for registering multiple functions in a namespace
 pub struct NamespaceBuilder<'a, N> {
+    /// If true will use the dummy function registry instead
+    registry: ScriptFunctionRegistryArc,
     /// phantom data to reference the namespace type
     namespace: PhantomData<N>,
     /// a cached reference to the world
@@ -86,6 +89,10 @@ impl<'a, S: IntoNamespace> NamespaceBuilder<'a, S> {
             registry.register::<S>();
         }
         Self {
+            registry: world
+                .get_resource_or_init::<AppScriptFunctionRegistry>()
+                .0
+                .clone(),
             namespace: Default::default(),
             world,
         }
@@ -94,11 +101,27 @@ impl<'a, S: IntoNamespace> NamespaceBuilder<'a, S> {
     /// Prefer using the `register` method on the `NamespaceBuilder` instead
     pub fn new_unregistered(world: &'a mut World) -> Self {
         Self {
+            registry: world
+                .get_resource_or_init::<AppScriptFunctionRegistry>()
+                .0
+                .clone(),
             namespace: Default::default(),
             world,
         }
     }
 
+    /// Register functions for this namespace on the dummy function registry instead.
+    ///
+    /// This will appear in documentation but not become callable.
+    pub fn with_dummy_registry(mut self) -> Self {
+        self.registry = self
+            .world
+            .get_resource_or_init::<DummyScriptFunctionRegistry>()
+            .0
+            .clone();
+        self
+    }
+
     /// Registers a function in the namespace
     pub fn register<'env, N, F, M>(&mut self, name: N, function: F) -> &mut Self
     where
@@ -136,10 +159,7 @@ impl<'a, S: IntoNamespace> NamespaceBuilder<'a, S> {
     {
         {
             {
-                let mut registry = self
-                    .world
-                    .get_resource_or_init::<AppScriptFunctionRegistry>();
-                let mut registry = registry.write();
+                let mut registry = self.registry.write();
                 registry.register_with_arg_names(
                     S::into_namespace(),
                     name,

crates/bevy_mod_scripting_bindings/src/function/script_function.rs

@@ -258,10 +258,16 @@ where
     }
 }
 
+/// Identical to the [`AppScriptFunctionRegistry`], but the functions only exist for docs purposes, use if you provide functions at a lower level,
+/// but still want to include the function in the docs
+#[derive(Clone, Default, Resource, DebugWithTypeInfo)]
+#[debug_with_type_info(bms_display_path = "bevy_mod_scripting_display")]
+pub struct DummyScriptFunctionRegistry(pub ScriptFunctionRegistryArc);
+
 /// Equivalent to [`AppFunctionRegistry`] but stores functions with a more convenient signature for scripting to avoid boxing every argument.
 #[derive(Clone, Default, Resource, DebugWithTypeInfo)]
 #[debug_with_type_info(bms_display_path = "bevy_mod_scripting_display")]
-pub struct AppScriptFunctionRegistry(ScriptFunctionRegistryArc);
+pub struct AppScriptFunctionRegistry(pub ScriptFunctionRegistryArc);
 
 impl Deref for AppScriptFunctionRegistry {
     type Target = ScriptFunctionRegistryArc;

crates/bevy_mod_scripting_core/src/lib.rs

@@ -22,8 +22,8 @@ use bevy_mod_scripting_asset::{Language, LanguageExtensions, ScriptAsset, Script
 
 use bevy_mod_scripting_bindings::{
     AppReflectAllocator, AppScheduleRegistry, AppScriptFunctionRegistry,
-    DynamicScriptComponentPlugin, MarkAsCore, ReflectReference, ScriptTypeRegistration,
-    ScriptValue, ThreadWorldContainer, garbage_collector,
+    DummyScriptFunctionRegistry, DynamicScriptComponentPlugin, MarkAsCore, ReflectReference,
+    ScriptTypeRegistration, ScriptValue, ThreadWorldContainer, garbage_collector,
 };
 use context::{Context, ContextInitializer, ContextPreHandlingInitializer};
 use event::{ScriptCallbackEvent, ScriptCallbackResponseEvent};
@@ -343,6 +343,7 @@ impl Plugin for BMSScriptingInfrastructurePlugin {
             .init_resource::<AppReflectAllocator>()
             .init_asset::<ScriptAsset>()
             .init_resource::<AppScriptFunctionRegistry>()
+            .init_resource::<DummyScriptFunctionRegistry>()
             .insert_resource(AppScheduleRegistry::new());
 
         app.register_type::<ScriptAsset>();

crates/bevy_mod_scripting_derive/src/derive/script_bindings.rs

@@ -82,9 +82,18 @@ pub fn script_bindings(
         Default::default()
     };
 
+    let use_dummy = if args.use_dummy_registry {
+        quote_spanned! {impl_span=>
+            .with_dummy_registry()
+        }
+    } else {
+        Default::default()
+    };
+
     let out = quote_spanned! {impl_span=>
         #visibility fn #function_name(world: &mut World) {
             #bms_bindings_path::function::namespace::NamespaceBuilder::<#type_ident_with_generics>::#builder_function_name(world)
+                #use_dummy
                 #(#function_registrations)*;
 
             #mark_as_generated
@@ -113,6 +122,9 @@ struct Args {
     pub core: bool,
     /// If true registers a marker type against the type registry to state that the type is significant (if unregistered is not set)
     pub significant: bool,
+    /// If true will register into the [`DummyScriptFunctionRegistry`] instead of the full one.
+    /// This is useful for documenting functions without actually making them available, if you're exposing them another way.
+    pub use_dummy_registry: bool,
 }
 
 impl syn::parse::Parse for Args {
@@ -127,6 +139,7 @@ impl syn::parse::Parse for Args {
         let mut generated = false;
         let mut core = false;
         let mut significant = false;
+        let mut use_dummy_registry = false;
         let mut bms_bindings_path =
             syn::Path::from(syn::Ident::new("bevy_mod_scripting", Span::call_site()));
         bms_bindings_path.segments.push(syn::PathSegment {
@@ -152,6 +165,9 @@ impl syn::parse::Parse for Args {
                     } else if path.is_ident("significant") {
                         significant = true;
                         continue;
+                    } else if path.is_ident("use_dummy_registry") {
+                        use_dummy_registry = true;
+                        continue;
                     }
                 }
                 syn::Meta::NameValue(name_value) => {
@@ -190,6 +206,7 @@ impl syn::parse::Parse for Args {
             generated,
             core,
             significant,
+            use_dummy_registry,
         })
     }
 }

crates/bevy_mod_scripting_derive/src/lib.rs

@@ -27,6 +27,7 @@ pub fn into_script(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
 /// - `unregistered`: If set, will use `new_unregistered` instead of `new` for the namespace builder
 /// - `core`: If set, marks the type as `core` using the `MarkAsCore` type data
 /// - `significant`: If set, marks the type as `significant` using the `MarkAsSignificant` type data
+/// - `use_dummy_registry`: If true will register into the [`DummyScriptFunctionRegistry`] instead of the full one. This is useful for documenting functions without actually making them available, if you're exposing them another way.
 ///
 /// It is encouraged to place `significant` markers on your own types, for the purposes of documentation generation.
 #[proc_macro_attribute]

crates/bevy_mod_scripting_functions/src/core.rs

@@ -9,9 +9,10 @@ use bevy_app::App;
 use bevy_asset::{AssetServer, Handle};
 use bevy_ecs::{entity::Entity, prelude::AppTypeRegistry, schedule::Schedules, world::World};
 use bevy_mod_scripting_bindings::{
-    DynamicScriptFunctionMut, FunctionInfo, GlobalNamespace, InteropError, PartialReflectExt,
-    ReflectReference, ScriptComponentRegistration, ScriptQueryBuilder, ScriptQueryResult,
-    ScriptResourceRegistration, ScriptTypeRegistration, ThreadWorldContainer, Union,
+    DynamicScriptFunction, DynamicScriptFunctionMut, FunctionInfo, GlobalNamespace, InteropError,
+    PartialReflectExt, ReflectReference, ScriptComponentRegistration, ScriptQueryBuilder,
+    ScriptQueryResult, ScriptResourceRegistration, ScriptTypeRegistration, ThreadWorldContainer,
+    Union,
     function::{
         from::{Ref, Val},
         from_ref::FromScriptRef,
@@ -1329,6 +1330,48 @@ impl Handle<ScriptAsset> {
     }
 }
 
+/// globals which are being registered at lower level within each language plugin.
+#[script_bindings(
+    remote,
+    bms_bindings_path = "bevy_mod_scripting_bindings",
+    name = "global_namespace_dummy_functions",
+    unregistered,
+    use_dummy_registry
+)]
+impl GlobalNamespace {
+    /// Registers a "frozen" callback handler,
+    ///
+    /// For example, this code:
+    ///
+    /// ```lua
+    /// register_callback("on_script_unloaded", my_unload_handler)
+    ///
+    /// function my_unload_handler()
+    ///     print("handling unload!")
+    /// end
+    /// ```
+    ///
+    /// would call the `my_unload_handler` function, whenever the `on_script_unloaded` callback is triggered, which is when your script is about to be unloaded.
+    ///
+    /// Registered callbacks take precedence over free-standing function callbacks, i.e. the below top level function:
+    /// ```lua
+    /// function on_script_unloaded()
+    ///     print("freestanding unload handler!")
+    /// end
+    /// ```
+    ///
+    /// would be a valid handler, but if a registered callback existed, it would be called instead.
+    ///
+    /// Arguments:
+    /// * `callback`: the callback label to register this function against.
+    /// * `function`: the callback function which will be stored as a handler for this callback label.
+    fn register_callback(callback: String, function: DynamicScriptFunction) {
+        // to avoid clippy unused errors.
+        println!("dummy called!: {callback:?}, {function:?}");
+    }
+}
+
+/// Globals registered by us
 #[script_bindings(
     remote,
     bms_bindings_path = "bevy_mod_scripting_bindings",
@@ -1421,5 +1464,6 @@ pub fn register_core_functions(app: &mut App) {
         register_script_handle_functions(world);
 
         register_global_namespace_functions(world);
+        register_global_namespace_dummy_functions(world);
     }
 }

crates/ladfile_builder/src/plugin.rs

@@ -8,7 +8,7 @@ use ::{
 };
 use bevy_log::{error, info};
 use bevy_mod_scripting_bindings::{
-    IntoNamespace,
+    DummyScriptFunctionRegistry, IntoNamespace,
     function::{namespace::Namespace, script_function::AppScriptFunctionRegistry},
     globals::AppScriptGlobalsRegistry,
 };
@@ -74,11 +74,13 @@ impl ScriptingDocgenPlugin {
 pub fn generate_lad_file(
     type_registry: &AppTypeRegistry,
     function_registry: &AppScriptFunctionRegistry,
+    dummy_function_registry: &DummyScriptFunctionRegistry,
     global_registry: &AppScriptGlobalsRegistry,
     settings: &LadFileSettings,
 ) {
     let type_registry = type_registry.read();
     let function_registry = function_registry.read();
+    let dummy_function_registry = dummy_function_registry.0.read();
     let global_registry = global_registry.read();
     let mut builder = LadFileBuilder::new(&type_registry);
     builder
@@ -92,7 +94,10 @@ pub fn generate_lad_file(
         r#"The ECS world containing all Components, Resources and Systems. Main point of interaction with a Bevy App."#.trim(),
     );
 
-    for (_, function) in function_registry.iter_namespace(World::into_namespace()) {
+    for (_, function) in function_registry
+        .iter_namespace(World::into_namespace())
+        .chain(dummy_function_registry.iter_namespace(World::into_namespace()))
+    {
         builder.add_function_info(&function.info);
     }
 
@@ -113,15 +118,19 @@ pub fn generate_lad_file(
         builder.add_type_info(type_info);
 
         // find functions on the namespace
-        for (_, function) in
-            function_registry.iter_namespace(Namespace::OnType(type_info.type_id()))
+        for (_, function) in function_registry
+            .iter_namespace(Namespace::OnType(type_info.type_id()))
+            .chain(dummy_function_registry.iter_namespace(Namespace::OnType(type_info.type_id())))
         {
             builder.add_function_info(&function.info);
         }
     }
 
     // find functions on the global namespace
-    for (_, function) in function_registry.iter_namespace(Namespace::Global) {
+    for (_, function) in function_registry
+        .iter_namespace(Namespace::Global)
+        .chain(dummy_function_registry.iter_namespace(Namespace::Global))
+    {
         builder.add_function_info(&function.info);
     }
 
@@ -171,12 +180,14 @@ pub fn generate_lad_file(
 fn generate_lad_file_system(
     type_registry: Res<AppTypeRegistry>,
     function_registry: Res<AppScriptFunctionRegistry>,
+    dummy_function_registry: Res<DummyScriptFunctionRegistry>,
     global_registry: Res<AppScriptGlobalsRegistry>,
     settings: Res<LadFileSettings>,
 ) {
     generate_lad_file(
         &type_registry,
         &function_registry,
+        &dummy_function_registry,
         &global_registry,
         &settings,
     );

examples/docgen.rs

@@ -1,6 +1,7 @@
 use bevy::{DefaultPlugins, app::App, ecs::reflect::AppTypeRegistry};
 use bevy_mod_scripting::ScriptFunctionsPlugin;
 use bevy_mod_scripting_bindings::{
+    DummyScriptFunctionRegistry,
     function::script_function::AppScriptFunctionRegistry,
     globals::{AppScriptGlobalsRegistry, core::CoreScriptGlobalsPlugin},
 };
@@ -44,6 +45,11 @@ fn main() -> std::io::Result<()> {
         .get_resource::<AppScriptFunctionRegistry>()
         .unwrap()
         .clone();
+    let dummy_function_registry = app
+        .world()
+        .get_resource::<DummyScriptFunctionRegistry>()
+        .unwrap()
+        .clone();
     let global_registry = app
         .world()
         .get_resource::<AppScriptGlobalsRegistry>()
@@ -58,6 +64,7 @@ fn main() -> std::io::Result<()> {
     generate_lad_file(
         &type_registry,
         &function_registry,
+        &dummy_function_registry,
         &global_registry,
         &settings,
     );