Document public API guarantees; hide some symbols

godot-core/src/obj/traits.rs

@@ -213,13 +213,16 @@ pub mod dom {
     use crate::obj::{Gd, GodotClass};
     use std::ops::DerefMut;
 
+    /// Trait that specifies who declares a given `GodotClass`.
     pub trait Domain: Sealed {
+        #[doc(hidden)]
         fn scoped_mut<T, F, R>(obj: &mut Gd<T>, closure: F) -> R
         where
             T: GodotClass<Declarer = Self>,
             F: FnOnce(&mut T) -> R;
     }
 
+    /// Expresses that a class is declared by the Godot engine.
     pub enum EngineDomain {}
     impl Sealed for EngineDomain {}
     impl Domain for EngineDomain {
@@ -232,6 +235,7 @@ pub mod dom {
         }
     }
 
+    /// Expresses that a class is declared by the user.
     pub enum UserDomain {}
     impl Sealed for UserDomain {}
     impl Domain for UserDomain {
@@ -255,23 +259,29 @@ pub mod mem {
     use crate::obj::{Gd, GodotClass};
     use crate::out;
 
+    /// Specifies the memory
     pub trait Memory: Sealed {
         /// Initialize reference counter
+        #[doc(hidden)]
         fn maybe_init_ref<T: GodotClass>(obj: &Gd<T>);
 
         /// If ref-counted, then increment count
+        #[doc(hidden)]
         fn maybe_inc_ref<T: GodotClass>(obj: &Gd<T>);
 
         /// If ref-counted, then decrement count
+        #[doc(hidden)]
         fn maybe_dec_ref<T: GodotClass>(obj: &Gd<T>) -> bool;
 
         /// Check if ref-counted, return `None` if information is not available (dynamic and obj dead)
+        #[doc(hidden)]
         fn is_ref_counted<T: GodotClass>(obj: &Gd<T>) -> Option<bool>;
 
         /// Returns `true` if argument and return pointers are passed as `Ref<T>` pointers given this
         /// [`PtrcallType`].
         ///
         /// See [`PtrcallType::Virtual`] for information about `Ref<T>` objects.
+        #[doc(hidden)]
         fn pass_as_ref(_call_type: PtrcallType) -> bool {
             false
         }

godot/src/lib.rs

@@ -136,9 +136,28 @@
 //!   Experimental threading support. This enables `Send`/`Sync` traits for `Gd<T>` and makes the guard types `Gd`/`GdMut` aware of
 //!   multi-threaded references. The safety aspects of this are not ironed out yet; use at your own risk. The API may also change
 //!   at any time.
+//!
+//! # Public API
+//!
+//! Some symbols in the API are not intended for users, however Rust's visibility feature is not strong enough to express that in all cases
+//! (for example, proc-macros and separated crates may need access to internals).
+//!
+//! The following API symbols are considered private:
+//!
+//! * Symbols annotated with `#[doc(hidden)]`.
+//! * Any of the dependency crates (crate `godot` is the only public interface).
+//! * Modules named `private` and all their contents.
+//!
+//! Being private means a workflow is not supported. As such, there are **no guarantees** regarding API stability, robustness or correctness.
+//! Problems arising from using such APIs are not considered bugs, and anything relying on them may stop working without announcement.
+//! Please refrain from using undocumented and private features; if you are missing certain functionality, bring it up for discussion instead.
+//! This allows us to decide whether it fits the scope of the library and to design proper APIs for it.
 
 #[doc(inline)]
-pub use godot_core::{builtin, engine, log, obj, sys};
+pub use godot_core::{builtin, engine, log, obj};
+
+#[doc(hidden)]
+pub use godot_core::sys;
 
 pub mod init {
     pub use godot_core::init::*;