Merge branches 'qol/untyped-signal-connect', 'qol/cli-setup' and 'bugfix/gdscript-enums'

Author: Bromeon

src/intro/setup.md

@@ -29,19 +29,21 @@ For beta and older versions, you can also check the [download archive][godot-dow
 
 ```bash
 # --- Linux ---
-# For Ubuntu or Debian-based distros.
-apt install godot
-
-# For Fedora/RHEL.
+# Fedora/RHEL.
 dnf install godot
 
-# Distro-independent through Flatpak.
+# Arch Linux.
+pacman -Syu godot
+paru -Syu godot
+
+# Flatpak (e.g. Ubuntu, Debian, or distro-independent).
 flatpak install flathub org.godotengine.Godot
 
 
 # --- Windows ---
-# Windows installations can be made through WinGet.
-winget install --id=GodotEngine.GodotEngine -e
+winget install -e --id GodotEngine.GodotEngine
+choco install godot
+scoop bucket add extras && scoop install godot
 
 
 # --- macOS ---
@@ -67,7 +69,7 @@ install it via command-line.
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 
 # Windows
-winget install --id=Rustlang.Rustup -e
+winget install -e --id Rustlang.Rustup
 
 # macOS
 brew install rustup

src/register/properties.md

@@ -162,18 +162,21 @@ enum Planet {
 ~~~
 is roughly the same as:
 ~~~java
-const EARTH = 0
-const VENUS = 1
-const MARS = 2
+const Planet: Dictionary = {
+    EARTH = 0,
+    VENUS = 1,
+    MARS = 2,
+}
 
 @export_enum("EARTH", "VENUS", "MARS") var favorite_planet = Planet.EARTH
 ~~~
 However, the enum is not type-safe, you can just do this:
 ~~~java
 var p: Planet = 5
 ~~~
-Furthermore, unless you initialize the constants with string values, you cannot retrieve their names, making debugging harder. There is no
-reflection either, such as "get number of enum values" or "iterate over all of them". If you have the choice, consider keeping enums in Rust.
+Furthermore, you can also not easily retrieve the name `"EARTH"` from the expression `Planet.EARTH`.[^enum-name]
+
+See [GDScript enums][godot-gdscript-enums] for more details.
 ```
 
 
@@ -212,3 +215,13 @@ As a general rule, try to stay close to Godot's own types, e.g. `Array`, `Dictio
 [api-var-export]: https://godot-rust.github.io/docs/gdext/master/godot/register/derive.GodotClass.html#properties-and-exports
 [godot-gdscript-properties]: https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_basics.html#properties
 [gh-godot-packedarray]: https://github.com/godotengine/godot/issues/76150
+[godot-gdscript-enums]: https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_basics.html#enums
+
+<br>
+
+---
+
+**Footnotes**
+
+[^enum-name]: You _can_ obtain `"EARTH"` if you iterate the `Planet` dictionary and compare each value (assuming there are no duplicates).
+   That however requires that you know the type (`Planet`); the value itself does not hold this information.

src/register/signals.md

@@ -443,16 +443,25 @@ The builder methods need to be called in the correct order ("stages"). See [API
 
 Godot's low-level APIs for dealing with untyped signals are still available:
 
-- [`Object::connect()`][api-object-connect], `Object::connect_ex()`
+- [`Object::connect()`][api-object-connect]
+- [`Object::connect_ex()`][api-object-connect-ex]
 - [`Object::emit_signal()`][api-object-emitsignal]
 - [`Signal::connect()`][api-signal-connect]
 - [`Signal::emit()`][api-signal-emit]
 
 The new typed-signal API should cover the full functionality, but there are situations where information is only available at runtime, making
 the untyped reflection APIs a good fit. We might also combine the two in the future.
 
-To emit an untyped signal, you can call the `Object::emit_signal` method by accessing the base class (mutably):
-Considering the `Monster` struct from the previous examples, you can emit its signal with:
+One way to connect signals the old-school is passing in the signal name and the `Callable`:
+
+```rust
+let monster: Gd<Monster> = ...;
+let damage_taken: Callable = monster.callable("damage_taken");
+monster.connect("damage_taken", &damage_taken);
+```
+
+To emit an untyped signal, call the `Object::emit_signal()` method by (mutably) accessing the base class.
+Staying with the `Monster` struct from the previous examples, you can emit its signal with:
 
 ```rust
 self.base_mut().emit_signal(
@@ -461,10 +470,11 @@ self.base_mut().emit_signal(
 );
 ```
 
-See [vslice!][api-vslice] docs for passing multiple variants in a slice.
+See [`vslice!`][api-vslice] docs for passing multiple variants in a slice.
 
-Certain typed-signal features are still planned and will make working with signals even more streamlined. Other features are likely not going
-to be ported to godot-rust, e.g. a `Callable::bind()` equivalent for typed Rust methods. Just use closures instead.
+Certain untyped-signal functionality may still be ported typed signals, while others such as `Callable::bind()` will likely not be available.
+Just use closures instead. Generally speaking, the [`TypedSignal`][api-typedsignal] and [`ConnectBuilder`][api-connectbuilder] APIs are designed
+to be extensible for your own workflows.
 
 
 ## Conclusion
@@ -483,6 +493,7 @@ Rust function references or closures can be directly connected to signals, and e
 [api-typedsignal-builder]: https://godot-rust.github.io/docs/gdext/master/godot/register/struct.TypedSignal.html#method.builder
 [api-connectbuilder]: https://godot-rust.github.io/docs/gdext/master/godot/register/struct.ConnectBuilder.html
 [api-object-connect]: https://godot-rust.github.io/docs/gdext/master/godot/classes/struct.Object.html#method.connect
+[api-object-connect-ex]: https://godot-rust.github.io/docs/gdext/master/godot/classes/struct.Object.html#method.connect_ex
 [api-object-emitsignal]: https://godot-rust.github.io/docs/gdext/master/godot/classes/struct.Object.html#method.emit_signal
 [api-signal-connect]: https://godot-rust.github.io/docs/gdext/master/godot/builtin/struct.Signal.html#method.connect
 [api-signal-emit]: https://godot-rust.github.io/docs/gdext/master/godot/builtin/struct.Signal.html#method.emit