Update AsArg and ParamType documentation to reflect changes

Author: TitanNano

godot-core/src/meta/args/as_arg.rs

@@ -16,15 +16,15 @@ use std::ffi::CStr;
 /// this trait is implemented more conservatively.
 ///
 /// As a result, `AsArg<T>` is currently only implemented for certain argument types:
-/// - `T` for by-value builtins (typically `Copy`): `i32`, `bool`, `Vector3`, `Transform2D`, ...
-/// - `&T` for by-ref builtins: `GString`, `Array`, `Dictionary`, `Packed*Array`, `Variant`...
+/// - `T` for by-value built-ins (typically `Copy`): `i32`, `bool`, `Vector3`, `Transform2D`, ...
+/// - `&T` for by-ref built-ins: `GString`, `Array`, `Dictionary`, `Packed*Array`, `Variant`...
 /// - `&str`, `&String` additionally for string types `GString`, `StringName`, `NodePath`.
 ///
 /// See also the [`AsObjectArg`][crate::meta::AsObjectArg] trait which is specialized for object arguments. It may be merged with `AsArg`
 /// in the future.
 ///
 /// # Pass by value
-/// Implicitly converting from `T` for by-ref builtins is explicitly not supported. This emphasizes that there is no need to consume the object,
+/// Implicitly converting from `T` for by-ref built-ins is explicitly not supported. This emphasizes that there is no need to consume the object,
 /// thus discourages unnecessary cloning.
 ///
 /// # Performance for strings
@@ -44,8 +44,7 @@ use std::ffi::CStr;
 /// `AsArg` is meant to be used from the function call site, not the declaration site. If you declare a parameter as `impl AsArg<...>` yourself,
 /// you can only forward it as-is to a Godot API -- there are no stable APIs to access the inner object yet.
 ///
-/// Furthermore, there is currently no benefit in implementing `AsArg` for your own types, as it's only used by Godot APIs which don't accept
-/// custom types. Classes are already supported through upcasting and [`AsObjectArg`][crate::meta::AsObjectArg].
+/// If you want to pass your own types to a Godot API i.e. to emit a signal, you should implement the [`ParamType`] trait.
 #[diagnostic::on_unimplemented(
     message = "Argument of type `{Self}` cannot be passed to an `impl AsArg<{T}>` parameter",
     note = "if you pass by value, consider borrowing instead.",
@@ -259,6 +258,10 @@ impl AsArg<NodePath> for &String {
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
 /// Implemented for all parameter types `T` that are allowed to receive [impl `AsArg<T>`][AsArg].
+///
+/// **Deprecated**: This trait is considered deprecated and will be removed in 0.4. It is still required to be implemented by types that should
+/// be passed `AsArg` in the current version, though.
+//
 // ParamType used to be a subtrait of GodotType, but this can be too restrictive. For example, DynGd is not a "Godot canonical type"
 // (GodotType), however it's still useful to store it in arrays -- which requires AsArg and subsequently ParamType.
 //

godot-core/src/meta/traits.rs

@@ -36,10 +36,10 @@ pub trait GodotFfiVariant: Sized + GodotFfi {
 //
 // Unlike `GodotFfi`, types implementing this trait don't need to fully represent its corresponding Godot
 // type. For instance [`i32`] does not implement `GodotFfi` because it cannot represent all values of
-// Godot's `int` type, however it does implement `GodotType` because we can set the metadata of values with
+// Godot's `int` type, however it does implement `GodotType` because we can set the meta-data of values with
 // this type to indicate that they are 32 bits large.
 pub trait GodotType: GodotConvert<Via = Self> + sealed::Sealed + Sized + 'static
-// 'static is not technically required, but it simplifies a few things (limits e.g. ObjectArg).
+// 'static is not technically required, but it simplifies a few things (limits e.g. `ObjectArg`).
 {
     // Value type for this type's FFI representation.
     #[doc(hidden)]
@@ -122,7 +122,7 @@ pub trait GodotType: GodotConvert<Via = Self> + sealed::Sealed + Sized + 'static
     ///
     /// Examples:
     /// - `MyClass` for objects
-    /// - `StringName`, `AABB` or `int` for builtins
+    /// - `StringName`, `AABB` or `int` for built-ins
     /// - `Array` for arrays
     #[doc(hidden)]
     fn godot_type_name() -> String;
@@ -131,7 +131,7 @@ pub trait GodotType: GodotConvert<Via = Self> + sealed::Sealed + Sized + 'static
     ///
     /// Returning false only means that this is not a special case, not that it cannot be `None`. Regular checks are expected to run afterward.
     ///
-    /// This exists only for varcalls and serves a similar purpose as `GodotNullableFfi::is_null()` (although that handles general cases).
+    /// This exists only for var-calls and serves a similar purpose as `GodotNullableFfi::is_null()` (although that handles general cases).
     #[doc(hidden)]
     fn qualifies_as_special_none(_from_variant: &Variant) -> bool {
         false
@@ -164,14 +164,14 @@ pub trait GodotType: GodotConvert<Via = Self> + sealed::Sealed + Sized + 'static
 /// Also, keep in mind that Godot uses `Variant` for each element. If performance matters and you have small element types such as `u8`,
 /// consider using packed arrays (e.g. `PackedByteArray`) instead.
 //
-// TODO: The ParamType super trait is no longer needed and can be removed in 0.4. We are only keeping it for backwards compatebility.
+// TODO: The `ParamType` super trait is no longer needed and can be removed in 0.4. We are only keeping it for backwards compatibility.
 #[diagnostic::on_unimplemented(
     message = "`Array<T>` can only store element types supported in Godot arrays (no nesting).",
     label = "has invalid element type"
 )]
 pub trait ArrayElement: ToGodot + FromGodot + sealed::Sealed + ParamType + 'static {
-    // Note: several indirections in ArrayElement and the global `element_*` functions go through `GodotConvert::Via`,
-    // to not require Self: GodotType. What matters is how array elements map to Godot on the FFI level (GodotType trait).
+    // Note: several indirections in `ArrayElement` and the global `element_*` functions go through `GodotConvert::Via`,
+    // to not require Self: `GodotType`. What matters is how array elements map to Godot on the FFI level (`GodotType` trait).
 
     /// Returns the representation of this type as a type string, e.g. `"4:"` for string, or `"24:34/MyClass"` for objects.
     ///