Documentation

Author: TitanNano

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
+/// ```no_compile
+/// # 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,7 @@ macro_rules! setup_library {
 
 pub trait GodotScriptEnum: GodotConvert + FromGodot + ToGodot {}
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! init {
     ($scripts_module:tt) => {
@@ -222,6 +243,7 @@ macro_rules! init {
     };
 }
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! deinit {
     () => {

rust-script/src/lib.rs

@@ -3,6 +3,7 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  */
+#![doc = include_str!("../../README.md")]
 
 mod apply;
 
@@ -11,7 +12,63 @@ 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::{godot_script_impl, GodotScriptEnum};
+
+/// 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.
+pub use godot_rust_script_derive::GodotScript;
 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) => {