Clarify Export semantics for objects

Author: Bromeon

godot-core/src/obj/dyn_gd.rs

@@ -46,7 +46,7 @@ use std::{fmt, ops};
 /// #[derive(GodotClass)]
 /// #[class(init)]
 /// struct Monster {
-///    #[init(val = 100)]
+///     #[init(val = 100)]
 ///     hitpoints: u16,
 /// }
 ///
@@ -137,24 +137,39 @@ use std::{fmt, ops};
 /// and it can query the dynamic type of the object. Based on that type, it can find the `impl Health` implementation matching the correct class.
 /// Behind the scenes, everything is wired up correctly so that you can restore the original `DynGd` even after it has passed through Godot.
 ///
-/// # `#[export]` for `DynGd<T, D>`
+/// # Exporting
 ///
-/// Exporting `DynGd<T, D>` is possible only via [`OnEditor`] or [`Option`].
+/// [Like `Gd<T>`](struct.Gd.html#exporting), using `#[export]` with `DynGd<T, D>` is possible only via [`OnEditor`] or [`Option`].
 /// `DynGd<T, D>` can also be exported directly as an element of an array such as `Array<DynGd<T, D>>`.
 ///
-/// Since `DynGd<T, D>` represents shared functionality `D` across classes inheriting from `T`,
-/// consider using `#[export] Gd<T>` instead of `#[export] DynGd<T, D>`
-/// in cases when `T` is a concrete Rust `GodotClass`.
+/// When talking about "exporting", the following paragraphs assume that you wrap `DynGd` in one of those types.
 ///
-/// ## Node based classes
+/// In cases where `T: AsDyn<D>` (the trait is directly implemented on the user class, i.e. no upcasting), exporting `DynGd<T, D>` is
+/// equivalent to exporting `Gd<T>` regarding Inspector UI.
 ///
-/// `#[export]` for a `DynGd<T, D>` works identically to `#[export]` `Gd<T>` for `T` inheriting Node classes.
-/// Godot will report an error if the conversion fails, but it will only do so when accessing the given value.
+/// ## Node-based classes
 ///
-/// ## Resource based classes
+/// If `T` inherits `Node`, exporting `DynGd<T, D>` works identically to `Gd<T>`.
 ///
-/// `#[export]` for a `DynGd<T, D>` allows you to limit the available choices to implementors of a given trait `D` whose base inherits the specified `T`
-/// (for example, `#[export] Option<DynGd<Resource, dyn MyTrait>>` won't include Rust classes with an Object base, even if they implement `MyTrait`).
+/// If you try to assign a class from the editor that does not implement trait `D`, Godot will report a conversion-failed error,
+/// but it will only do so when accessing the given value.
+///
+/// ## Resource-based classes
+///
+/// If `T` inherits `Resource`, exporting `DynGd<T, D>>` will limit the available choices to known implementors of the trait `D`.
+///
+/// For example, let's say you have four Rust classes:
+///
+/// | Class        | Inherits   | Implements trait |
+/// |--------------|------------|------------------|
+/// | `Bullet`     | `Resource` | `Projectile`     |
+/// | `Rocket`     | `Resource` | `Projectile`     |
+/// | `BulletNode` | `Node`     | `Projectile`     |
+/// | `Tower`      | `Resource` | (none)           |
+///
+/// Then, an exported `DynGd<Resource, dyn Projectile>` would be visible in Godot's Inspector UI with a drop-down field, i.e. users can assign
+/// only objects of certain classes. **The available options for the drop-down are `Bullet` and `Rocket`.** The class `BulletNode` is not
+/// available because it's not a `Resource`, and `Tower` is not because it doesn't implement the `Projectile` trait.
 ///
 /// # Type inference
 ///
@@ -581,9 +596,7 @@ where
     }
 }
 
-/// `#[export]` for `Option<DynGd<T, D>>` is available only for `T` being Engine class (such as Node or Resource).
-///
-/// Consider exporting `Option<Gd<T>>` instead of `Option<DynGd<T, D>>` for user-declared GDExtension classes.
+/// See [`DynGd` Exporting](struct.DynGd.html#exporting) section.
 impl<T, D> Export for Option<DynGd<T, D>>
 where
     T: GodotClass + Bounds<Exportable = bounds::Yes>,
@@ -632,9 +645,7 @@ where
     }
 }
 
-/// `#[export]` for `OnEditor<DynGd<T, D>>` is available only for `T` being Engine class (such as Node or Resource).
-///
-/// Consider exporting `OnEditor<Gd<T>>` instead of `OnEditor<DynGd<T, D>>` for user-declared GDExtension classes.
+/// See [`DynGd` Exporting](struct.DynGd.html#exporting) section.
 impl<T, D> Export for OnEditor<DynGd<T, D>>
 where
     Self: Var,

godot-core/src/obj/gd.rs

@@ -90,6 +90,16 @@ use crate::{classes, out};
 ///
 /// For type conversions, please read the [`godot::meta` module docs][crate::meta].
 ///
+/// # Exporting
+///
+/// The [`Export`][crate::registry::property::Export] trait is not directly implemented for `Gd<T>`, because the editor expects object-based
+/// properties to be nullable, while `Gd<T>` can't be null. Instead, `Export` is implemented for [`OnEditor<Gd<T>>`][crate::obj::OnEditor],
+/// which validates that objects have been set by the editor. For the most flexible but least ergonomic option, you can also export
+/// `Option<Gd<T>>` fields.
+///
+/// Objects can only be exported if `T: Inherits<Node>` or `T: Inherits<Resource>`, just like GDScript.
+/// This means you cannot use `#[export]` with `OnEditor<Gd<RefCounted>>`, for example.
+///
 /// [book]: https://godot-rust.github.io/book/godot-api/objects.html
 /// [`Object`]: classes::Object
 /// [`RefCounted`]: classes::RefCounted
@@ -949,6 +959,7 @@ impl<T: GodotClass> Var for Gd<T> {
     }
 }
 
+/// See [`Gd` Exporting](struct.Gd.html#exporting) section.
 impl<T> Export for Option<Gd<T>>
 where
     T: GodotClass + Bounds<Exportable = bounds::Yes>,
@@ -991,6 +1002,7 @@ where
     }
 }
 
+/// See [`Gd` Exporting](struct.Gd.html#exporting) section.
 impl<T> Export for OnEditor<Gd<T>>
 where
     Self: Var,

godot-core/src/registry/property.rs

@@ -54,8 +54,7 @@ pub trait Var: GodotConvert {
 // Note: HTML link for #[export] works if this symbol is inside prelude, but not in register::property.
 /// Trait implemented for types that can be used as [`#[export]`](../register/derive.GodotClass.html#properties-and-exports) fields.
 ///
-/// `Export` is only implemented for objects `Gd<T>` if either `T: Inherits<Node>` or `T: Inherits<Resource>`, just like GDScript.
-/// This means you cannot use `#[export]` with `Gd<RefCounted>`, for example.
+/// To export objects, see the [_Exporting_ section of `Gd<T>`](../obj/struct.Gd.html#exporting).
 ///
 /// For enums, this trait can be derived using the [`#[derive(Export)]`](../derive.Export.html) macro.
 #[doc(alias = "property")]