Merge pull request #960 from godot-rust/qol/helpful-aliases

Helpful doc aliases: `func`, `var`, `init`, ...

Author: Bromeon

godot-core/src/builtin/math/float.rs

@@ -16,6 +16,7 @@ mod private {
     impl Sealed for f64 {}
 }
 
+/// Trait that provides Godot math functions as extensions on `f32` and `f64`.
 pub trait FloatExt: private::Sealed + Copy {
     const CMP_EPSILON: Self;
 

godot-core/src/init/mod.rs

@@ -226,6 +226,7 @@ fn gdext_on_level_deinit(level: InitLevel) {
 /// [gdextension]: attr.gdextension.html
 /// [safety]: https://godot-rust.github.io/book/gdext/advanced/safety.html
 // FIXME intra-doc link
+#[doc(alias = "entry_symbol", alias = "entry_point")]
 pub unsafe trait ExtensionLibrary {
     /// Determines if and how an extension's code is run in the editor.
     fn editor_run_behavior() -> EditorRunBehavior {

godot-core/src/meta/godot_convert/mod.rs

@@ -21,6 +21,7 @@ use crate::meta::GodotType;
 /// in Godot (without intermediate "via"). Every `GodotType` also implements `GodotConvert` with `Via = Self`.
 ///
 /// Please read the [`godot::meta` module docs][crate::meta] for further information about conversions.
+#[doc(alias = "via", alias = "transparent")]
 #[diagnostic::on_unimplemented(
     message = "`GodotConvert` is needed for `#[func]` parameters/returns, as well as `#[var]` and `#[export]` properties",
     note = "check following errors for more information"
@@ -39,6 +40,8 @@ pub trait GodotConvert {
 /// Violating these assumptions is safe but will give unexpected results.
 ///
 /// Please read the [`godot::meta` module docs][crate::meta] for further information about conversions.
+///
+/// This trait can be derived using the [`#[derive(GodotConvert)]`](../register/derive.GodotConvert.html) macro.
 pub trait ToGodot: Sized + GodotConvert {
     /// Target type of [`to_godot()`](ToGodot::to_godot), which can differ from [`Via`][GodotConvert::Via] for pass-by-reference types.
     ///
@@ -71,6 +74,8 @@ pub trait ToGodot: Sized + GodotConvert {
 /// Violating these assumptions is safe but will give unexpected results.
 ///
 /// Please read the [`godot::meta` module docs][crate::meta] for further information about conversions.
+///
+/// This trait can be derived using the [`#[derive(GodotConvert)]`](../register/derive.GodotConvert.html) macro.
 pub trait FromGodot: Sized + GodotConvert {
     /// Converts the Godot representation to this type, returning `Err` on failure.
     fn try_from_godot(via: Self::Via) -> Result<Self, ConvertError>;

godot-core/src/registry/property.rs

@@ -14,13 +14,20 @@ use crate::meta::{ClassName, FromGodot, GodotConvert, GodotType, PropertyHintInf
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 // Trait definitions
 
-/// Trait implemented for types that can be used as `#[var]` fields.
+// Note: HTML link for #[var] works if this symbol is inside prelude, but not in register::property.
+/// Trait implemented for types that can be used as [`#[var]`](../register/derive.GodotClass.html#properties-and-exports) fields.
 ///
 /// This creates a copy of the value, according to copy semantics provided by `Clone`. For example, `Array`, `Dictionary` and `Gd` are
 /// returned by shared reference instead of copying the actual data.
 ///
 /// This does not require [`FromGodot`] or [`ToGodot`], so that something can be used as a property even if it can't be used in function
 /// arguments/return types.
+///
+/// See also [`Export`], a specialization of this trait for properties exported to the editor UI.
+///
+/// For enums, this trait can be derived using the [`#[derive(Var)]`](../derive.Var.html) macro.
+#[doc(alias = "property")]
+//
 // on_unimplemented: we also mention #[export] here, because we can't control the order of error messages.
 // Missing Export often also means missing Var trait, and so the Var error message appears first.
 #[diagnostic::on_unimplemented(
@@ -39,10 +46,15 @@ pub trait Var: GodotConvert {
     }
 }
 
-/// Trait implemented for types that can be used as `#[export]` fields.
+// 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.
+///
+/// For enums, this trait can be derived using the [`#[derive(Export)]`](../derive.Export.html) macro.
+#[doc(alias = "property")]
+//
 // on_unimplemented: mentioning both Var + Export; see above.
 #[diagnostic::on_unimplemented(
     message = "`#[var]` properties require `Var` trait; #[export] ones require `Export` trait",

godot-macros/src/derive/derive_godot_convert.rs

@@ -4,6 +4,7 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
+
 use crate::derive::data_models::GodotConvert;
 use crate::derive::{make_fromgodot, make_togodot};
 use crate::ParseResult;

godot-macros/src/lib.rs

@@ -148,7 +148,8 @@ use crate::util::{bail, ident, KvParser};
 /// [properties](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_basics.html#properties-setters-and-getters)
 /// (fields with a `get` or `set` declaration) and
 /// [exports](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_exports.html)
-/// (fields annotated with `@export`). In the gdext API, these two concepts are represented with `#[var]` and `#[export]` attributes respectively.
+/// (fields annotated with `@export`). In the gdext API, these two concepts are represented with `#[var]` and `#[export]` attributes respectively,
+/// which in turn are backed by the [`Var`](../register/property/trait.Var.html) and [`Export`](../register/property/trait.Export.html) traits.
 ///
 /// ## Property registration
 ///
@@ -474,7 +475,17 @@ use crate::util::{bail, ident, KvParser};
 ///     }
 /// }
 /// ```
-#[proc_macro_derive(GodotClass, attributes(class, base, hint, var, export, init, signal))]
+#[doc(
+    alias = "class",
+    alias = "base",
+    alias = "init",
+    alias = "no_init",
+    alias = "var",
+    alias = "export",
+    alias = "tool",
+    alias = "rename"
+)]
+#[proc_macro_derive(GodotClass, attributes(class, base, hint, var, export, init))]
 pub fn derive_godot_class(input: TokenStream) -> TokenStream {
     translate(input, class::derive_godot_class)
 }
@@ -773,6 +784,15 @@ pub fn derive_godot_class(input: TokenStream) -> TokenStream {
 ///     pub fn two(&self) { }
 /// }
 /// ```
+#[doc(
+    alias = "func",
+    alias = "rpc",
+    alias = "virtual",
+    alias = "signal",
+    alias = "constant",
+    alias = "rename",
+    alias = "secondary"
+)]
 #[proc_macro_attribute]
 pub fn godot_api(meta: TokenStream, input: TokenStream) -> TokenStream {
     translate(input, |body| {
@@ -827,9 +847,9 @@ pub fn godot_dyn(_meta: TokenStream, input: TokenStream) -> TokenStream {
     translate(input, class::attribute_godot_dyn)
 }
 
-/// Derive macro for [`GodotConvert`](../builtin/meta/trait.GodotConvert.html) on structs.
+/// Derive macro for [`GodotConvert`](../meta/trait.GodotConvert.html) on structs.
 ///
-/// This derive macro also derives [`ToGodot`](../builtin/meta/trait.ToGodot.html) and [`FromGodot`](../builtin/meta/trait.FromGodot.html).
+/// This derive macro also derives [`ToGodot`](../meta/trait.ToGodot.html) and [`FromGodot`](../meta/trait.FromGodot.html).
 ///
 /// # Choosing a Via type
 ///
@@ -960,7 +980,7 @@ pub fn derive_godot_convert(input: TokenStream) -> TokenStream {
 
 /// Derive macro for [`Var`](../register/property/trait.Var.html) on enums.
 ///
-/// This expects a derived [`GodotConvert`](../builtin/meta/trait.GodotConvert.html) implementation, using a manual
+/// This expects a derived [`GodotConvert`](../meta/trait.GodotConvert.html) implementation, using a manual
 /// implementation of `GodotConvert` may lead to incorrect values being displayed in Godot.
 #[proc_macro_derive(Var, attributes(godot))]
 pub fn derive_var(input: TokenStream) -> TokenStream {

godot/src/lib.rs

@@ -107,7 +107,7 @@
 //! * **`codegen-rustfmt`**
 //!
 //!   Use rustfmt to format generated binding code. Because rustfmt is so slow, this is detrimental to initial compile time.
-//!   Without it, we use a lightweight and fast custom formatter to enable basic human readability.
+//!   Without it, we use a lightweight and fast custom formatter to enable basic human readability.<br><br>
 //!
 //! * **`register-docs`**
 //!