Add documentation for Callable + misc improvements (#715)

CedNaru · web-flow · commit 41ff7ad45337 · 2024-10-07T10:53:54.000+02:00
* Improve doc + add Callable
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -32,7 +32,8 @@ theme:
     - navigation.tabs
     - navigation.expand
     - navigation.top
-
+    - content.code.copy
+    - toc.integrate
 
 extra:
   social:
@@ -43,9 +44,9 @@ markdown_extensions:
   - pymdownx.highlight:
       linenums: true
   - pymdownx.inlinehilite
-  - pymdownx.highlight
   - pymdownx.superfences
-  - pymdownx.tabbed
+  - pymdownx.blocks.tab:
+      alternate_style: true
   - pymdownx.details
   - admonition
   - meta
@@ -62,19 +63,17 @@ nav:
       - Requirements: getting-started/requirements.md
       - Setting-up: getting-started/setting-up.md
       - Your first Kotlin class: getting-started/your-first-class.md
+      - Compiling your project: getting-started/compiling-your-project.md
   - User guide:
     - API differences: user-guide/api-differences.md
     - Classes: user-guide/classes.md
-    - Compiling your project: user-guide/compiling-your-project.md
     - Properties: user-guide/properties.md
-    - Signals: user-guide/signals.md
+    - Signals and Callables: user-guide/signals_and_callables.md
     - Functions: user-guide/functions.md
-    - Exporting: user-guide/exporting.md
     - Coroutines: user-guide/coroutines.md
+    - Exporting: user-guide/exporting.md
     - Debugging: user-guide/debugging.md
     - Consuming libraries: user-guide/consuming-libraries.md
-    - Versioning: user-guide/versioning.md
-    - Supported platforms: user-guide/supported-platforms.md
     - Advanced:
       - Abstract classes: user-guide/advanced/abstract-classes.md
       - Cleanup operations: user-guide/advanced/cleanup-operations.md
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,2 +1,2 @@
 mkdocs-material==9.1.18
-mkdocs==1.4.3
+mkdocs==1.6.1
diff --git a/docs/src/doc/assets/img/build_ide.png b/docs/src/doc/assets/img/build_ide.png
diff --git a/docs/src/doc/getting-started/compiling-your-project.md b/docs/src/doc/getting-started/compiling-your-project.md
@@ -1,10 +1,27 @@
 To compile your project, run a classic *Gradle build*. By default this creates a `debug` version of your code.
 
-Example:
+Using the Godot editor:
+
+![Build button](../assets/img/editor-plugin/build_button.png)
+
+Using your IDE:
+
+![Gradle task](../assets/img/build_ide.png)
 
+Using command-line:
+
+/// tab | Windows
+```shell
+gradlew build
+```
+///
+
+/// tab | Unix
 ```bash
 ./gradlew build
 ```
+///
+
 
 ## Targets
 
@@ -13,22 +30,18 @@ In order to build in release, you should add `release` parameter to your Gradle
 
 Example:
 
+/// tab | Windows
+```shell
+gradlew build -Prelease
+```
+///
+
+/// tab | Unix
 ```bash
 ./gradlew build -Prelease
 ```
+///
 
 Using debug builds is recommended when developing. It adds some sanity checks that are cut off in `release`.  
 
-Release builds are recommended when distributing to retail.
-
-## Write debug code
-
-You can add code only for debug version of your project, by using `GodotJvmDefinitions`.
-
-Example:
-
-```kotlin
-if (GodotJvmDefinitions.DEBUG) {
-    // ...
-}
-```
+Release builds are recommended when distributing to retail.
diff --git a/docs/src/doc/getting-started/setting-up.md b/docs/src/doc/getting-started/setting-up.md
@@ -8,13 +8,14 @@ or [manually](#setting-up-manually).
 
 You can simply create a regular new Godot project. 
 Once done, you can go to `Project/Tools/Kotlin/JVM/Generate JVM Project`.
+
 ![Godot menu](../assets/img/editor-plugin/generation_menu.png)
 
 The following choice will appear:
 ![Project dialog](../assets/img/editor-plugin/generation_choice.png)
 
-After this action, all required files should be generated, and you can safely build the project using the `Build` button at the top-right of the editor window.
-![Build button](../assets/img/editor-plugin/build_button.png)
+After this action, all required files should be generated, and you can safely import your project in your IDE.
+
 ## Setting-up using IntelliJ IDEA project wizard
 
 This is the recommended solution as it creates the entire project in one action and import it in your IDE.
@@ -88,17 +89,19 @@ If the user does not want to use our IntelliJ IDEA plugin, then they can follow
 Firstly, you need to setup a Gradle [wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html).
 The wrapper will ensure that anyone who wants to build your project from source will use the same Gradle version.
 
-=== "Windows" 
-    ```shell
-    fsutil file createnew build.gradle.kts 0
-    fsutil file createnew gradle.properties 0
-    fsutil file createnew settings.gradle.kts 0
-    ```
+/// tab | Windows
+```shell
+fsutil file createnew build.gradle.kts 0
+fsutil file createnew gradle.properties 0
+fsutil file createnew settings.gradle.kts 0
+```
+///
 
-=== "Unix"
-    ```shell
-    touch build.gradle.kts gradle.properties settings.gradle.kts
-    ```
+/// tab | Unix
+```shell
+touch build.gradle.kts gradle.properties settings.gradle.kts
+```
+///
 
 The above command(s) will create three empty files. As next step, type the following
 command on the terminal:
@@ -111,17 +114,18 @@ After running the above command, the user should have the wrapper setup ready to
 Up next is setting-up the Gradle build. Now, open the `build.gradle.kts` file
 and paste the following content:
 
-=== "`build.gradle.kts`"
-    ```kotlin
-    plugins {
-        kotlin("jvm") version "$kotlinVersion"
-        id("com.utopia-rise.godot-kotlin-jvm") version "$godotKotlinVersion"
-    }
-
-    repositories {
-        mavenCentral()
-    }
-    ```
+/// tab | `build.gradle.kts`
+```kotlin
+plugins {
+    kotlin("jvm") version "$kotlinVersion"
+    id("com.utopia-rise.godot-kotlin-jvm") version "$godotKotlinVersion"
+}
+
+repositories {
+    mavenCentral()
+}
+```
+///
 
 !!! note 
     Please replace `$kotlinVersion` and `$godotkotlinVersion` to the appropriate version you want to use.
diff --git a/docs/src/doc/index.md b/docs/src/doc/index.md
@@ -39,7 +39,25 @@ If you don't have Discord or you don't want to use it, please file an issue on G
 
 The main language supported is Kotlin. We do however support Java experimentally. It should be possible to support other JVM-based languages as well but this is not the focus of this project. If you want to have support for other languages, have a look at [support for other JVM-based languages](contribution/support-for-other-jvm-based-languages.md).
 
-## Supported Kotlin version
+## Supported platforms
+
+While Kotlin and Godot supports a wide range of platforms, this module for the moment only supports the following:
+
+- Windows X64
+- Linux X64
+- MacOS X64 / arm64
+- Android (arm64v8)
+- iOS (arm64v8)
+
+## Versioning
+
+The module uses semantic versioning for its own versions but adds a suffix for the supported Godot version:
+
+Full version: `0.10.0-4.3.0`
+
+Module Version: `0.10.0`
+
+Supported Godot Version: `4.3.0`
 
 This module relies on a Kotlin *compiler plugin* for registering your classes and members to Godot. As the compiler API from Kotlin is not stable yet, at the moment we can only support specific Kotlin version per release.
 
diff --git a/docs/src/doc/user-guide/advanced/cleanup-operations.md b/docs/src/doc/user-guide/advanced/cleanup-operations.md
@@ -18,9 +18,9 @@ fun foo() {
 
 
 Sometimes you need to store some Godot objects or references in a Kotlin singleton.
-This can cause some leaks when the program ends because you have to manually free objects and have the references collected.
-This issue is fixed by using the delegate `godotStatic` on singleton properties. Those properties will be freed once the running JVM ends.
-They automatically handle `Object` and `Reference`. You can also freely set a new value and the previous one will be immediatly freed.
+This can cause some memory leak warnings when the program ends because they are kept alive by the singleton.
+This issue is fixed by using the method `asStatic()` on singleton properties. Those properties will be freed once the running JVM ends.
+They automatically handle `Object` and `Reference`.
 
 !!! warning
     Only use it on a singleton, otherwise all the properties of all instances are going to be kept alive until the end of the JVM.
diff --git a/docs/src/doc/user-guide/advanced/custom-src-dirs.md b/docs/src/doc/user-guide/advanced/custom-src-dirs.md
@@ -1,8 +1,9 @@
 To be able to use custom source directories, you modify your Gradle build file as it follows:
 
-=== "build.gradle.kts"
-    ```kt
-    kotlin.sourceSets.main {
-        kotlin.srcDirs("scripts")
-    }
-    ```
+/// tab | build.gradle.kts
+```kt
+kotlin.sourceSets.main {
+    kotlin.srcDirs("scripts")
+}
+```
+///
diff --git a/docs/src/doc/user-guide/advanced/gradle-plugin-configuration.md b/docs/src/doc/user-guide/advanced/gradle-plugin-configuration.md
@@ -6,10 +6,11 @@ This is due to the fact that the Kotlin compiler plugin API is not stable yet. T
 But if you are familiar with the quirks of compiler plugins and their compatibility and you need to use another Kotlin version than we officially support,
 you can disable the version checks we have in place in our Gradle plugin. To do this you have to set `godot.jvm.suppressKotlinIncompatibility` to `true` in the `gradle.properties` file:
 
-=== "gradle.properties"
-    ```
-    godot.jvm.suppressKotlinIncompatibility=true
-    ```
+/// tab | gradle.properties
+```kotlin
+godot.jvm.suppressKotlinIncompatibility=true
+```
+///
 
 !!! warning
     This is an advanced feature! Only use it if you know what you're doing. We cannot guarantee that our compiler plugin is compatible with other kotlin versions than the one we build it for. Setting this property to true can lead to build and/or runtime errors.
diff --git a/docs/src/doc/user-guide/api-differences.md b/docs/src/doc/user-guide/api-differences.md
@@ -125,13 +125,6 @@ dictionary.get("foo") {
 
 Godot enums are mapped to Kotlin enums, the generated enum exposes a `value` property that represents the value in Godot. Constants in Godot classes that represent an enum value (such as `Node.PAUSE_MODE_INHERIT`) are not present in this module, please use the generated enum instead (`Node.PauseMode.INHERIT`).
 
-## Signals and exposed methods
-
-In GDScript, signals can have any number of arguments, this is not possible in Kotlin as it is a statically typed language.
-At the moment, you can create signals and expose them to Godot with at most 10 parameters.
-
-If you need more than 10 parameters, you can either use the not typesafe function `connect(signalAsString, targetObject, targetMethodAsString)` and the corresponding emit function or you can write your own typesafe extension functions like we did, to further increase the supported arg count. Keep in mind that you pass in the converted function and signal names (snake_case) to the above mentioned functions.  
-
 ## Renamed symbols
 
 To avoid confusion and conflict with Kotlin types, the following Godot symbol is renamed.
@@ -166,33 +159,45 @@ override fun _notification() = godotNotification {
 ```  
 Currently this feature except abstract classes.  
 
-## Caching
+## StringName and NodePath
 
 Several Godot functions take `StringName` or `NodePath` as a parameter. 
-It's often more convenient to directly use a String that need to be converted.
+It's often more convenient to directly use a String and convert it.
 
-This operation can be costly so we provide extension functions which cache the result of the conversion for later calls:
-
-- `String.asCachedStringName()`
-- `String.asCachedNodePath()` 
-- `StringName.asCachedNodePath()`
+This kind of operation can be costly so we provide extension functions which cache the result of the conversion for later calls:
 
+/// tab | Kotlin
 ```kotlin
-// This first call to the extension function creates the cache entry.
-val firstCall = "Test".asCachedStringName()
-
-// This second call for the same String value, will return the previously cached instance.
-val secondCall = "Test".asCachedStringName()
+    val stringName = "myString".asCachedStringName() // Cache the string for faster future calls.
+    val nodePath = "myNode/myChildNode".asCachedNodePath() // Cache the string for faster future calls.
+    val snakeCaseStringName = "myString".toGodotName() // Convert the string to snake_case and cache it for faster future calls.
+```
+///
 
-// This third call will create a second entry in the cache due to the different key value.
-val thirdCall = "OtherTest".asCachedStringName()
+/// tab | Java
+```java
+    StringName stringName = StringNames.asCachedStringName("myString");
+    NodePath nodePath = NodePaths.asCachedNodePath("myNode/myChildNode");
+    StringName snakeCaseStringName = StringNames.toGodotName("myString");
 ```
+///
 
 You can also use the non-cached version of them if you simply want ease of conversion:
 
-- `String.asStringName()`
-- `String.asNodePath()`
-- `StringName.asNodePath()`
+/// tab | Kotlin
+```kotlin
+    val stringName = "myString".asStringName()
+    val nodePath = "myNode/myChildNode".asNodePath()
+```
+///
+
+/// tab | Java
+```java
+    StringName stringName = StringNames.asStringName("myString");
+    NodePath nodePath = NodePaths.asNodePath("myNode/myChildNode");
+```
+///
+
 
 ## Logging
 
diff --git a/docs/src/doc/user-guide/classes.md b/docs/src/doc/user-guide/classes.md
@@ -161,7 +161,7 @@ var instance := load("res://gdj/YourClass.gdj").new(oneArg, anotherArg)
 ```
 
 !!! info
-    The limitation of max 8 arguments for constructors is arbitrary. We decided to introduce this limitation to prevent performance bottlenecks for creating objects as each argument passed to a constructor needs to be unpacked by the binding. The more arguments, the more unpacking is needed which means more overhead.
+    The limitation of max 16 arguments for constructors is arbitrary. We decided to introduce this limitation to prevent performance bottlenecks for creating objects as each argument passed to a constructor needs to be unpacked by the binding. The more arguments, the more unpacking is needed which means more overhead.
 
 
 ## Customization
diff --git a/docs/src/doc/user-guide/debugging.md b/docs/src/doc/user-guide/debugging.md
@@ -19,3 +19,17 @@ Run your game with the command-line option `--jvm-debug-port=<port (normally 500
 
 Example:  
 ![remote debug configuration](../assets/img/remote_debug_configuration.png)
+
+
+## Write debug code
+
+You can add code only for debug version of your project, by using `GodotJvmDefinitions`.
+When building your project with the release flag, those ifs are going to be automatically removed from your code, not even the condition check is left.
+
+Example:
+
+```kotlin
+if (GodotJvmDefinitions.DEBUG) {
+    // ...
+}
+```
diff --git a/docs/src/doc/user-guide/exporting.md b/docs/src/doc/user-guide/exporting.md
@@ -63,12 +63,13 @@ Don't forget to remove them when writing an uninstaller for your game.
 
 In order to build for Android, set the `isAndroidExportEnabled` flag to `true` in your build file.
 
-=== "build.gradke.kts"
-    ```kt
-    godot {
-        isAndroidExportEnabled.set(true)
-    }
-    ```
+/// tab | build.gradke.kts
+```kt
+godot {
+    isAndroidExportEnabled.set(true)
+}
+```
+///
 
 On Android, we do not embed a JVM, we use the existing VM provided by the OS. In order for your game to load the necessary JAR files,
 they need to be converted into `.dex` format. Our Gradle plugin will handle this for you but it requires that you have the android build tools installed (you can easily install and update them with the SDK manager in Android Studio or by installing the Android plugin in Intellij and using the SDK manager there).
diff --git a/docs/src/doc/user-guide/functions.md b/docs/src/doc/user-guide/functions.md
@@ -26,8 +26,8 @@ register it as well with `@RegisterFunction`.
 
 ## Arguments count
 
-Godot limits the allowed argument count of functions to `8`. Thus, this binding also has this limitation.
-If you want to pass more than 8 parameters in a function, you need to wrap them in a container
+Godot limits the allowed argument count of functions to `16`. Thus, this binding also has this limitation.
+If you want to pass more than 16 parameters in a function, you need to wrap them in a container
 (like a custom container class or a `VariantArray` or `Dictionary`).
 
 ## Customization
diff --git a/docs/src/doc/user-guide/signals.md b/docs/src/doc/user-guide/signals.md
diff --git a/docs/src/doc/user-guide/signals_and_callables.md b/docs/src/doc/user-guide/signals_and_callables.md
diff --git a/docs/src/doc/user-guide/supported-platforms.md b/docs/src/doc/user-guide/supported-platforms.md
diff --git a/docs/src/doc/user-guide/versioning.md b/docs/src/doc/user-guide/versioning.md
diff --git a/versionBumpGuide.txt b/versionBumpGuide.txt

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`	`1`	`mkdocs-material==9.1.18`
`2`		`-mkdocs==1.4.3`
	`2`	`+mkdocs==1.6.1`