Documentation

Author: TitanNano

README.md

@@ -46,7 +46,7 @@ For this, a manual implementation of the `godot::init::ExtensionLibrary` trait i
 be achieved via two macro calls. The `init!(...)` macro requires the name / path to a module in your library, which represents the root module
 of all available scripts.
 
-```rs
+```rust
 struct Lib;
 
 #[gdextension]
@@ -75,7 +75,7 @@ unsafe impl ExtensionLibrary for Lib {
 
 Rust scripts require a root module. All rust modules under this module will be considered as potential scripts.
 
-```rs
+```rust
 mod example_script;
 
 godot_rust_script::define_script_root!();
@@ -92,7 +92,7 @@ Scripts are then composed of a `struct` definition and an `impl` block. Public f
 other scripting languages and the engine, so they must use Godot compatible types. The same applies to struct fields. 
 Struct fields can additionally be exported via the `#[export]` attribute, so they show up in the editor inspector.
 
-```rs
+```rust
 use godot_rust_script::{
 	godot::prelude::{godot_print, Gd, GodotString, Node3D, Object},
 	godot_script_impl, GodotScript,

derive/src/lib.rs

@@ -19,6 +19,60 @@ use type_paths::{godot_types, property_hints, string_name_ty, variant_ty};
 
 use crate::attribute_ops::{FieldExportOps, PropertyOpts};
 
+/// Use this derive macro to create new rust scripts for your projects.
+///
+/// The macro is desinged to closely align with both godot-rusts [`GodotClass`](https://docs.rs/godot/latest/godot/prelude/derive.GodotClass.html) macro and the GDScript
+/// annotations.
+///
+/// # Top Level Attribute
+/// On the struct level the `#[script]` attribute can be used to configure base details of the script.
+///
+/// ## `#[script(base)]`
+/// ```
+/// # use ::godot_rust_script::{GodotScript, godot_script_impl};
+/// # use ::godot::classes::Node3D;
+/// #
+/// #[derive(GodotScript, Debug)]
+/// #[script(base = Node3D)]
+/// struct MyScript {}
+///
+/// # #[godot_script_impl]
+/// # impl MyScript {}
+/// ```
+///
+/// Set the `base` field to specify a base class your script should inherit from. By default all scripts inherit from [`RefCounted`](https://docs.rs/godot/latest/godot/classes/struct.RefCounted.html).
+///
+/// # Field Level Attributes
+/// On the field level you can specify customizations for your script properties. Fields that are private will not be exposed to the engine.
+/// Public field on the other hand are exposed to the engine and can be annotated with attributes.
+///
+/// ## `#[prop]`
+/// Use the `#[prop]` attribute to set up getter and setter functions for your properties.
+///
+/// ```
+/// # use godot_rust_script::{GodotScript, godot_script_impl};
+/// # use godot::builtin::GString;
+/// #
+/// #[derive(GodotScript, Debug)]
+/// struct MyScript {
+///     #[prop(set = Self::set_my_prop, get = Self::get_my_prop)]
+///     my_prop: GString,
+/// }
+///
+/// #[godot_script_impl]
+/// impl MyScript {
+///     fn set_my_prop(&mut self, value: GString) {
+///         self.my_prop = value;
+///     }
+///
+///     fn get_my_prop(&self) -> GString {
+///         self.my_prop.clone()
+///     }
+/// }
+/// ```
+///
+/// This attribute optionally accepts a `get` and a `set` field. If these fields are defined they have to be set to a function pointer
+/// expression. The expression can contain the `Self` keyword.
 #[proc_macro_derive(GodotScript, attributes(export, script, prop, signal))]
 pub fn derive(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
     let input = parse_macro_input!(input as DeriveInput);

rust-script/src/interface.rs

@@ -20,6 +20,10 @@ pub use crate::runtime::Context;
 pub use export::GodotScriptExport;
 pub use signals::{ScriptSignal, Signal};
 
+/// The primary trait of this library. This trait must be implemented by a struct to create a new rust script.
+///
+/// While it is possible, it's not intended that this trait is implemented by hand. Use the [derive macro](derive@crate::GodotScript) to
+/// implement this trait.
 pub trait GodotScript: Debug + GodotScriptImpl<ImplBase = Self::Base> {
     type Base: Inherits<Object>;
 
@@ -171,6 +175,21 @@ impl<T: GodotScript, B: Inherits<T::Base> + Inherits<Object>> CastToScript<T> fo
     }
 }
 
+/// Defines the root module for rust scripts. All scripts must be in submodules of the root module.
+///
+/// There must be a script root module in your project for Godot Rust Script to work. Using multiple root modules is currently not supported.
+///
+/// # Example
+/// ```ignore
+/// # use godot_rust_script::define_script_root;
+/// // Example script root: src/scripts/mod.rs
+///
+/// // define your script modules that contain `RustScript` structs.
+/// mod player;
+/// mod mob;
+///
+/// define_script_root!();
+/// ```
 #[macro_export]
 macro_rules! define_script_root {
     () => {
@@ -202,6 +221,7 @@ macro_rules! define_script_root {
     };
 }
 
+/// DEPRECATED: This macro has been renamed to [define_script_root].
 #[deprecated = "Has been renamed to define_script_root!()"]
 #[macro_export]
 macro_rules! setup_library {
@@ -212,6 +232,43 @@ macro_rules! setup_library {
 
 pub trait GodotScriptEnum: GodotConvert + FromGodot + ToGodot {}
 
+/// Initialize the rust script runtime. This should be part of your `ExtensionLibrary::on_level_init` function.
+///
+/// # Example
+/// ```
+/// # use godot::init::{gdextension, InitLevel, ExtensionLibrary};
+/// #
+/// # mod scripts {
+/// #     pub const __GODOT_RUST_SCRIPT_SRC_ROOT: &str = "/dummy/root";
+/// #
+/// #     pub fn __godot_rust_script_init() -> Vec<godot_rust_script::private_export::RustScriptMetaData> {
+/// #         unimplemented!()
+/// #     }
+/// # }
+/// #
+/// struct Lib;
+///
+/// #[gdextension]
+/// unsafe impl ExtensionLibrary for Lib {
+///     fn on_level_init(level: InitLevel) {
+///         match level {
+///             InitLevel::Core => (),
+///             InitLevel::Servers => (),
+///             InitLevel::Scene => godot_rust_script::init!(scripts),
+///             InitLevel::Editor => (),
+///         }
+///     }
+///  
+///  #  fn on_level_deinit(level: InitLevel) {
+///  #      match level {
+///  #          InitLevel::Editor => (),
+///  #          InitLevel::Scene => godot_rust_script::deinit!(),
+///  #          InitLevel::Servers => (),
+///  #          InitLevel::Core => (),
+///  #      }
+///  #  }
+/// }
+/// ````
 #[macro_export]
 macro_rules! init {
     ($scripts_module:tt) => {
@@ -222,6 +279,43 @@ macro_rules! init {
     };
 }
 
+/// Deinitialize the rust script runtime. This should be part of your `ExtensionLibrary::on_level_deinit` function.
+///
+/// # Example
+/// ```
+/// # use godot::init::{gdextension, InitLevel, ExtensionLibrary};
+/// #
+/// # mod scripts {
+/// #     pub const __GODOT_RUST_SCRIPT_SRC_ROOT: &str = "/dummy/root";
+/// #
+/// #     pub fn __godot_rust_script_init() -> Vec<godot_rust_script::private_export::RustScriptMetaData> {
+/// #         unimplemented!()
+/// #     }
+/// # }
+/// #
+/// struct Lib;
+///
+/// #[gdextension]
+/// unsafe impl ExtensionLibrary for Lib {
+/// #   fn on_level_init(level: InitLevel) {
+/// #       match level {
+/// #           InitLevel::Core => (),
+/// #           InitLevel::Servers => (),
+/// #           InitLevel::Scene => godot_rust_script::init!(scripts),
+/// #           InitLevel::Editor => (),
+/// #       }
+/// #   }
+/// #
+///     fn on_level_deinit(level: InitLevel) {
+///         match level {
+///             InitLevel::Editor => (),
+///             InitLevel::Scene => godot_rust_script::deinit!(),
+///             InitLevel::Servers => (),
+///             InitLevel::Core => (),
+///         }
+///     }
+/// }
+/// ````
 #[macro_export]
 macro_rules! deinit {
     () => {

rust-script/src/lib.rs

@@ -4,14 +4,17 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  */
 
+#![doc = include_str!("../../README.md")]
+
 mod apply;
 
 mod editor_ui_hacks;
 mod interface;
 mod runtime;
 mod static_script_registry;
 
-pub use godot_rust_script_derive::{godot_script_impl, GodotScript, GodotScriptEnum};
+pub use godot_rust_script_derive::GodotScript;
+pub use godot_rust_script_derive::{godot_script_impl, GodotScriptEnum};
 pub use interface::*;
 pub use runtime::RustScriptExtensionLayer;
 

rust-script/src/static_script_registry.rs

@@ -21,6 +21,7 @@ use crate::runtime::GodotScriptObject;
 
 godot::sys::plugin_registry!(pub SCRIPT_REGISTRY: RegistryItem);
 
+#[doc(hidden)]
 #[macro_export]
 #[cfg(before_api = "4.4")]
 macro_rules! register_script_class {
@@ -44,6 +45,7 @@ macro_rules! register_script_class {
     };
 }
 
+#[doc(hidden)]
 #[macro_export]
 #[cfg(since_api = "4.4")]
 macro_rules! register_script_class {
@@ -66,6 +68,7 @@ macro_rules! register_script_class {
     };
 }
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! register_script_methods {
     ($class_name:ty, $methods:expr) => {