From 4802dd8d4ef283607cf945779a63b15d0e4da8f4 Mon Sep 17 00:00:00 2001 From: Jan Haller <bromeon@gmail.com> Date: Mon, 17 Jul 2023 20:43:05 +0200 Subject: [PATCH] Document public API guarantees; hide some symbols --- godot-core/src/obj/traits.rs | 10 ++++++++++ godot/src/lib.rs | 21 ++++++++++++++++++++- 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/godot-core/src/obj/traits.rs b/godot-core/src/obj/traits.rs index a2039f8f5..01e9b1b2b 100644 --- a/godot-core/src/obj/traits.rs +++ b/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 } diff --git a/godot/src/lib.rs b/godot/src/lib.rs index aed084435..53929484d 100644 --- a/godot/src/lib.rs +++ b/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::*;