Docs: recommend releasing bind/base guards when no longer needed

Author: Bromeon

godot-core/src/obj/gd.rs

@@ -71,12 +71,15 @@ use crate::{classes, out};
 /// * [`Gd::from_instance_id(id)`][Gd::from_instance_id] and [`Gd::try_from_instance_id(id)`][Gd::try_from_instance_id]
 ///   to obtain a pointer to an object which is already alive in the engine.
 ///
-/// # Binds
+/// # Bind guards
 ///
 /// The [`bind()`][Self::bind] and [`bind_mut()`][Self::bind_mut] methods allow you to obtain a shared or exclusive guard to the user instance.
 /// These provide interior mutability similar to [`RefCell`][std::cell::RefCell], with the addition that `Gd` simultaneously handles reference
 /// counting (for some types `T`).
 ///
+/// Holding a bind guard will prevent other code paths from obtaining their own shared/mutable bind. As such, you should drop the guard
+/// as soon as you don't need it anymore, by closing a `{ }` block or calling `std::mem::drop()`.
+///
 /// When you declare a `#[func]` method on your own class, and it accepts `&self` or `&mut self`, an implicit `bind()` or `bind_mut()` call
 /// on the owning `Gd<T>` is performed. This is important to keep in mind, as you can get into situations that violate dynamic borrow rules; for
 /// example if you are inside a `&mut self` method, make a call to GDScript and indirectly call another method on the same object (re-entrancy).
@@ -151,6 +154,8 @@ where
     /// `GodotClass` instance, independently of how many `Gd` smart pointers point to it. There are runtime
     /// checks to ensure that Rust safety rules (e.g. no `&` and `&mut` coexistence) are upheld.
     ///
+    /// Drop the guard as soon as you don't need it anymore. See also [Bind guards](#bind-guards).
+    ///
     /// # Panics
     /// * If another `Gd` smart pointer pointing to the same Rust instance has a live `GdMut` guard bound.
     /// * If there is an ongoing function call from GDScript to Rust, which currently holds a `&mut T`
@@ -167,6 +172,8 @@ where
     /// `GodotClass` instance, independently of how many `Gd` smart pointers point to it. There are runtime
     /// checks to ensure that Rust safety rules (e.g. no `&mut` aliasing) are upheld.
     ///
+    /// Drop the guard as soon as you don't need it anymore. See also [Bind guards](#bind-guards).
+    ///
     /// # Panics
     /// * If another `Gd` smart pointer pointing to the same Rust instance has a live `GdRef` or `GdMut` guard bound.
     /// * If there is an ongoing function call from GDScript to Rust, which currently holds a `&T` or `&mut T`

godot-core/src/obj/script.rs

@@ -342,6 +342,9 @@ impl<'a, T: ScriptInstance> SiMut<'a, T> {
 
     /// Returns a shared reference suitable for calling engine methods on this object.
     ///
+    /// Holding a shared guard prevents other code paths from obtaining a _mutable_ reference to `self`, as such it is recommended to drop the
+    /// guard as soon as you no longer need it.
+    ///
     /// ```no_run
     /// # use godot::prelude::*;
     /// # use godot::classes::{ScriptLanguage, Script};
@@ -388,7 +391,10 @@ impl<'a, T: ScriptInstance> SiMut<'a, T> {
 
     /// Returns a mutable reference suitable for calling engine methods on this object.
     ///
-    /// This method will allow you to call back into the same object from Godot.
+    /// This method will allow you to call back into the same object from Godot (re-entrancy).
+    ///
+    /// Holding a mutable guard prevents other code paths from obtaining _any_ reference to `self`, as such it is recommended to drop the
+    /// guard as soon as you no longer need it.
     ///
     /// ```no_run
     /// # use godot::prelude::*;

godot-core/src/obj/traits.rs

@@ -248,6 +248,9 @@ pub trait WithBaseField: GodotClass + Bounds<Declarer = bounds::DeclUser> {
 
     /// Returns a shared reference suitable for calling engine methods on this object.
     ///
+    /// Holding a shared guard prevents other code paths from obtaining a _mutable_ reference to `self`, as such it is recommended to drop the
+    /// guard as soon as you no longer need it.
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -312,6 +315,9 @@ pub trait WithBaseField: GodotClass + Bounds<Declarer = bounds::DeclUser> {
     /// This method will allow you to call back into the same object from Godot, unlike what would happen
     /// if you used [`to_gd()`](WithBaseField::to_gd).
     ///
+    /// Holding a mutable guard prevents other code paths from obtaining _any_ reference to `self`, as such it is recommended to drop the
+    /// guard as soon as you no longer need it.
+    ///
     /// # Examples
     ///
     /// ```no_run