Merge #223

223: Object notification API, `engine` intra-doc links r=Bromeon a=Bromeon

So far, there was no way to intercept the Godot `_notification` API, and also issuing notifications was very cumbersome, as the constants were spread across several classes.

This PR introduces multiple new APIs:

1. `{Class}Notification` enum, which contains all notifications relevant for a given class.
    * For example, `Node3DNotification` accumulates all `NOTIFICATION_*` constants across `Node3D`, `Node` and `Object` classes.
    * In GDScript, this is less of an issue because there is true inheritance, so one can type `Node3D.NOTIF...` and auto-complete will list all candidates. In Rust, constants are not inherited.
    * There is currently a workaround for bug [godot#75839](godotengine/godot#75839): in two cases, two enumerators cannot be distinguished as they share the same integer value. We address this by using a single enumerator to represent both (not ideal, but there's nothing else we can do).

2. Virtual method `{Class}Virtual::on_notification(what: {NearestClass}Notification)`.
    * This is the equivalent to GDScript's `_notification` (with underscore), but more meaningfully named. It can be used to intercept low-level notifications for the given class.
    *  The parameter type is either the notification enum for that class; or if the class itself does not have any notification constants, the nearest base class that _does_. This avoids proliferation of enum types with the exact same interface. It's possibly breaking when Godot adds such constants in new classes, but it helps reduce the API surface if not _every single class_ needs its own enum (since there are relatively few classes working with notifications).

3. The method `{Class}::issue_notification(what: {NearestClass}Notification)`.
    * This is the counterpart of `on_notification` to _send_ notifications. 
    * In GDScript, this is named `notification` (no underscore).

---

Apart from that, there are smaller changes:
* `Display` is now implemented on all `Gd<T>` types, by using the Godot string representation. `T`'s `Display` impl is ignored.
* Several generated symbols in `godot::engine` are now slighly documented and contain intra-doc links to navigate easily:
   * Class <-> virtual trait
   * Class <-> notification enum
   * Class <-> sidecar module
   * Class -> Godot online docs
   * Modules `global`, `utilities` and `notify`

Co-authored-by: Jan Haller <[email protected]>

Author: bors[bot]

godot-codegen/src/central_generator.rs

@@ -136,6 +136,8 @@ fn make_sys_code(central_items: &CentralItems) -> String {
             #(#opaque_types)*
         }
 
+        // ----------------------------------------------------------------------------------------------------------------------------------------------
+
         pub struct GlobalMethodTable {
             #(#variant_fn_decls)*
         }
@@ -148,6 +150,8 @@ fn make_sys_code(central_items: &CentralItems) -> String {
             }
         }
 
+        // ----------------------------------------------------------------------------------------------------------------------------------------------
+
         #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
         #[repr(i32)]
         pub enum VariantType {
@@ -182,6 +186,8 @@ fn make_sys_code(central_items: &CentralItems) -> String {
             ffi_methods! { type GDExtensionTypePtr = *mut Self; .. }
         }
 
+        // ----------------------------------------------------------------------------------------------------------------------------------------------
+
         #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
         #[repr(i32)]
         pub enum VariantOperator {
@@ -256,6 +262,12 @@ fn make_core_code(central_items: &CentralItems) -> String {
             }
         }
 
+        /// Global enums and constants.
+        ///
+        /// A list of global-scope enumerated constants.
+        /// For global built-in functions, check out the [`utilities` module][crate::engine::utilities].
+        ///
+        /// See also [Godot docs for `@GlobalScope`](https://docs.godotengine.org/en/stable/classes/[email protected]#enumerations).
         pub mod global {
             use crate::sys;
             #( #global_enum_defs )*
@@ -266,7 +278,7 @@ fn make_core_code(central_items: &CentralItems) -> String {
 }
 
 fn make_central_items(api: &ExtensionApi, build_config: &str, ctx: &mut Context) -> CentralItems {
-    let mut opaque_types = vec![];
+    let mut opaque_types = Vec::new();
     for class in &api.builtin_class_sizes {
         if class.build_configuration == build_config {
             for ClassSize { name, size } in &class.sizes {
@@ -331,7 +343,7 @@ fn make_central_items(api: &ExtensionApi, build_config: &str, ctx: &mut Context)
 
         result
             .variant_op_enumerators_pascal
-            .push(ident(&shout_to_pascal(name)));
+            .push(ident(&util::shout_to_pascal(name)));
         result
             .variant_op_enumerators_ord
             .push(Literal::i32_unsuffixed(op.value));
@@ -707,22 +719,3 @@ fn is_trivial(type_names: &TypeNames) -> bool {
 
     list.contains(&type_names.json_builtin_name.as_str())
 }
-
-fn shout_to_pascal(shout_case: &str) -> String {
-    let mut result = String::with_capacity(shout_case.len());
-    let mut next_upper = true;
-
-    for ch in shout_case.chars() {
-        if next_upper {
-            assert_ne!(ch, '_'); // no double underscore
-            result.push(ch); // unchanged
-            next_upper = false;
-        } else if ch == '_' {
-            next_upper = true;
-        } else {
-            result.push(ch.to_ascii_lowercase());
-        }
-    }
-
-    result
-}