Improve ClassBuilder doc and enable doc-tests

Author: Bromeon

gdnative-core/Cargo.toml

@@ -18,16 +18,17 @@ type_tag_fallback = []
 
 [dependencies]
 gdnative-sys = { path = "../gdnative-sys", version = "0.9.3" }
-libc = "0.2.98"
+gdnative-impl-proc-macros = { path = "../impl/proc_macros", version = "=0.9.3" }
+ahash = "0.7.4"
 approx = "0.5.0"
+atomic-take = "1.0.0"
+bitflags = { version = "1.2.1", optional = true }
 glam = "0.18.0"
 indexmap = "1.7.0"
-ahash = "0.7.4"
+libc = "0.2.98"
 once_cell = "1.8.0"
+parking_lot = { version = "0.11.1", optional = true }
 serde = { version = "1", features = ["derive"], optional = true }
 
-gdnative-impl-proc-macros = { path = "../impl/proc_macros", version = "=0.9.3" }
-
-bitflags = { version = "1.2.1", optional = true }
-parking_lot = { version = "0.11.1", optional = true }
-atomic-take = "1.0.0"
+[dev-dependencies]
+gdnative = { path = "../gdnative", version = "0.9.3" } # for doc-tests

gdnative-core/src/nativescript/init.rs

@@ -1,31 +1,30 @@
-//! Types and functionalities to declare and initialize gdnative classes.
+//! Low-level API to register and export GDNative classes, methods and properties.
 //!
-//! ## API endpoints
+//! ## Init and exit hooks
 //!
 //! Three endpoints are automatically invoked by the engine during startup and shutdown:
 //!
-//! - [`godot_gdnative_init`](macro.godot_gdnative_init.html),
-//! - [`godot_nativescript_init`](macro.godot_nativescript_init.html),
-//! - [`godot_gdnative_terminate`](macro.godot_gdnative_terminate.html),
+//! - [`godot_gdnative_init`],
+//! - [`godot_nativescript_init`],
+//! - [`godot_gdnative_terminate`],
 //!
 //! All three must be present. To quickly define all three endpoints using the default names,
-//! use [`godot_init`](macro.godot_init.html).
+//! use [`godot_init`].
 //!
 //! ## Registering script classes
 //!
-//! To register script classes, call `InitHandle::add_class` or `InitHandle::add_tool_class`
-//! in your `godot_nativescript_init` or `godot_init` callback:
+//! [`InitHandle`] is the registry of all your exported symbols.
+//! To register script classes, call [`InitHandle::add_class`] or [`InitHandle::add_tool_class`]
+//! in your [`godot_nativescript_init`] or [`godot_init`] callback:
 //!
 //! ```ignore
-//! // - snip -
+//! use gdnative::prelude::*;
 //!
-//! fn init(handle: gdnative::init::InitHandle) {
+//! fn init(handle: InitHandle) {
 //!     handle.add_class::<HelloWorld>();
 //! }
 //!
 //! godot_init!(init);
-//!
-//! // - snip -
 //! ```
 //!
 //! For full examples, see [`examples`](https://github.com/godot-rust/godot-rust/tree/master/examples)
@@ -291,15 +290,39 @@ impl<C: NativeClass> ClassBuilder<C> {
     /// # Examples
     ///
     /// Basic usage:
+    /// ```
+    /// use gdnative::prelude::*;
+    /// use gdnative::nativescript::init::{RpcMode, Varargs};
+    ///
+    /// #[derive(NativeClass)]
+    /// #[register_with(Self::my_register)]
+    /// #[no_constructor]
+    /// struct MyType {}
     ///
-    /// ```ignore
-    /// // `Bar` is a stateful method implementing `Method<C>`
+    /// // Note: no #[methods] required
+    /// impl MyType {
+    ///     fn my_method(&self) -> i64 { 42 }
     ///
-    /// builder
-    ///     .build_method("foo", Bar { baz: 42 })
-    ///     .with_rpc_mode(RpcMode::RemoteSync)
-    ///     .done();
+    ///     fn my_register(builder: &ClassBuilder<MyType>) {
+    ///         builder
+    ///             .build_method("my_method", MyMethod)
+    ///             .with_rpc_mode(RpcMode::RemoteSync)
+    ///             .done();
+    ///     }
+    /// }
+    ///
+    /// // Now, wrap the method (this can do anything and does not need to actually call a method)
+    /// struct MyMethod;
+    /// impl Method<MyType> for MyMethod {
+    ///     fn call(&self, this: RefInstance<'_, MyType, Shared>, _args: Varargs<'_>) -> Variant {
+    ///         this.map(|obj: &MyType, _| {
+    ///             let result = obj.my_method();
+    ///             Variant::from_i64(result)
+    ///         }).expect("method call succeeds")
+    ///     }
+    /// }
     /// ```
+    ///
     #[inline]
     pub fn build_method<'a, F: Method<C>>(
         &'a self,
@@ -316,14 +339,32 @@ impl<C: NativeClass> ClassBuilder<C> {
     ///
     /// Basic usage:
     ///
-    /// ```ignore
-    /// builder
-    ///     .add_property("foo")
-    ///     .with_default(0.0)
-    ///     .with_hint((-10.0..=30.0).into())
-    ///     .with_getter(MyType::get_foo)
-    ///     .with_setter(MyType::set_foo)
-    ///     .done();
+    /// ```
+    /// use gdnative::prelude::*;
+    ///
+    /// #[derive(NativeClass)]
+    /// #[inherit(Node)]
+    /// #[register_with(Self::my_register)]
+    /// #[no_constructor]
+    /// struct MyType {
+    ///     foo: i32,
+    /// }
+    ///
+    /// // Note: no #[methods] required
+    /// impl MyType {
+    ///     pub fn get_foo(&self, _owner: TRef<Node>) -> i32 { self.foo }
+    ///     pub fn set_foo(&mut self, _owner: TRef<Node>, val: i32) { self.foo = val; }
+    ///
+    ///     fn my_register(builder: &ClassBuilder<MyType>) {
+    ///         builder
+    ///             .add_property("foo")
+    ///             .with_default(5)
+    ///             .with_hint((-10..=30).into())
+    ///             .with_getter(MyType::get_foo)
+    ///             .with_setter(MyType::set_foo)
+    ///             .done();
+    ///     }
+    /// }
     /// ```
     #[inline]
     pub fn add_property<'a, T>(&'a self, name: &'a str) -> PropertyBuilder<'a, C, T>

gdnative-derive/src/lib.rs

@@ -163,7 +163,7 @@ pub fn profiled(meta: TokenStream, input: TokenStream) -> TokenStream {
 ///
 /// ```
 /// use gdnative::prelude::*;
-/// use gdnative::nativescript::property::{RangeHint, FloatHint};
+/// use gdnative::nativescript::init::property::{RangeHint, FloatHint};
 ///
 /// #[derive(NativeClass)]
 /// #[inherit(Reference)]