Improving Documentation: Fixing Name Convetions and Formatting

README.md

@@ -1,33 +1,53 @@
-# Godot Kotlin JVM
-
-# Kotlin/JVM binding for the Godot Game Engine
+# Godot Kotlin/JVM
+## Kotlin/JVM binding for the Godot Game Engine
 
 <p align="center">
 <img src=".README/logo.png" width="30%" height="30%">
 </p>
 
 ## Overview
 
-This is a **Kotlin** language binding for the [**Godot**](https://godotengine.org/) game engine. It is built as a module (like the C# binding) to interact with **Godot**'s core internally. The binding provides you Godot API's as Kotlin classes, so you can write your game logic completely in Kotlin. Your code will be compiled into a .jar which is then executed by an embedded JVM, so you don't have to worry that your users have Java installed. It's already embedded in your game executable.
-You also don't have to worry about any binding logic. Just write your game scripts like you would for [GDScript](https://docs.godotengine.org/en/3.1/getting_started/scripting/gdscript/gdscript_basics.html) or [C#](https://docs.godotengine.org/en/3.1/getting_started/scripting/c_sharp/) but with all the syntactic sugar of Kotlin.
+This is a [**Kotlin**](https://kotlinlang.org) language binding for the [**Godot**](https://godotengine.org/) game engine.
+It is built as a module (like the C# binding) to interact with **Godot**'s core internally.
+
+The binding provides you Godot API's as [Kotlin classes](https://godot-kotl.in/en/stable/getting-started/your-first-class/),
+so you can write your game logic completely in Kotlin.
+
+### Code Distribution
+
+There are two methods for distributing JVM bytecode produced by the Kotlin compiler:
+
+1.  A classic JAR file: your code will be packed into a `.jar` file, which is then executed by an embedded JVM.
+    So the developer does not have to worry about their user installing a JRE. The JVM is already embedded in your game executable.
+2.  Dynamic Library using GraalVM Native Image: please read more about this in our [documentation page](https://godot-kotl.in/en/stable/user-guide/advanced/graal-vm-native-image/).
+
+Just write your game scripts like you would for [GDScript](https://docs.godotengine.org/en/4.2/getting_started/scripting/gdscript/gdscript_basics.html)
+or for [C#](https://docs.godotengine.org/en/3.1/getting_started/scripting/c_sharp/) but with all the syntactic sugar of Kotlin.
 
 [![GitHub](https://img.shields.io/github/license/utopia-rise/godot-kotlin-jvm?style=flat-square)](LICENSE)
 
-## Important notes
+## Important Notes
 
-This version of the binding is currently **Alpha**!  
+This version of the binding is currently **Alpha**! This means that the bindings are not
+production-ready. However, if you are curious in using Kotlin in Godot, this is a good opportunity
+to help us in improving the project!
 
 ## Documentation
-The documentation can be found [here](https://godot-kotl.in)
 
-## Developer discussion
+The documentation can be found [here](https://godot-kotl.in). It's a work in progress, and we would love your input to
+make it even better!
+
+## Developer Discussion & Contribution
 
-Ask questions and collaborate on [Discord](https://discord.gg/zpb5Ru7v9x)
+Join us on our [Discord](https://discord.gg/zpb5Ru7v9x) server to ask questions and work together
+with a friendly community.
 
-## Contribution
-If you want to contribute to the project, please read through the contribution guidlines and getting started sections [here](https://godot-kotl.in/en/stable/contribution/guidelines/)
+If you want to contribute to the project, please read through the [contribution guidelines](https://godot-kotl.in/en/stable/contribution/guidelines/)
+and the [setup](https://godot-kotl.in/en/stable/contribution/setup/) sections.
 
 ## Partners
-Jetbrains is helping us to develop this project by providing development tools to maintainers.  
-Intellij IDEA is our IDE of choice for Kotlin development and we strongly recommend using it.  
+
+JetBrains is helping us to develop this project by providing development tools to maintainers.
+Intellij IDEA is our IDE of choice for Kotlin development and we strongly recommend using it.
+
 [![jblogo](.README/jetbrains.svg)](https://www.jetbrains.com/)

docs/mkdocs.yml

@@ -8,15 +8,26 @@ theme:
   name: material
   favicon: assets/img/favicon.ico
   palette:
-    - scheme: default
+    - media: "(prefers-color-scheme)"
+      primary: deep purple
       toggle:
-        icon: material/toggle-switch-off-outline
+        icon: material/brightness-auto
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: deep purple
+      toggle:
+        icon: material/brightness-7
         name: Switch to dark mode
-    - scheme: slate
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: deep purple
       toggle:
-        icon: material/toggle-switch
-        name: Switch to light mode
+        icon: material/brightness-4
+        name: Switch to system preference
   logo: assets/img/logo.png
+  font:
+    code: JetBrains Mono
   features:
     - navigation.tabs
     - navigation.expand
@@ -35,6 +46,7 @@ markdown_extensions:
   - pymdownx.highlight
   - pymdownx.superfences
   - pymdownx.tabbed
+  - pymdownx.details
   - admonition
   - meta
 
@@ -46,10 +58,10 @@ extra_css:
 
 nav:
   - Home: index.md
-  - Getting started:
+  - Getting Started:
       - Requirements: getting-started/requirements.md
-      - Setting up: getting-started/setting-up.md
-      - Your first class: getting-started/your-first-class.md
+      - Setting-up: getting-started/setting-up.md
+      - Your first Kotlin class: getting-started/your-first-class.md
   - User guide:
     - API differences: user-guide/api-differences.md
     - Classes: user-guide/classes.md
@@ -63,13 +75,13 @@ nav:
     - Versioning: user-guide/versioning.md
     - Supported platforms: user-guide/supported-platforms.md
     - Advanced:
-      - Abstract Classes: user-guide/advanced/abstract_classes.md
-      - Custom src dirs: user-guide/advanced/custom-src-dirs.md
-      - Custom gradle wrapper path: user-guide/advanced/custom_gradle_wrapper_path.md
+      - Abstract classes: user-guide/advanced/abstract-classes.md
+      - Custom source directories: user-guide/advanced/custom-src-dirs.md
+      - Custom gradle wrapper path: user-guide/advanced/custom-gradle-wrapper-path.md
       - Gradle plugin configuration: user-guide/advanced/gradle-plugin-configuration.md
-      - Commandline args: user-guide/advanced/commandline-args.md
+      - Command-line arguments: user-guide/advanced/commandline-args.md
       - Kotlin singletons: user-guide/advanced/kotlin-singleton.md
-      - GraalVM native-image: user-guide/advanced/graal-vm-native-image.md
+      - GraalVM Native Image: user-guide/advanced/graal-vm-native-image.md
   - Develop libraries:
       - Introduction: develop-libraries/introduction.md
       - Setup: develop-libraries/setup.md
@@ -79,9 +91,9 @@ nav:
     - Guidelines: contribution/guidelines.md
     - Setup: contribution/setup.md
     - Build with C# support: contribution/build-with-csharp-support.md
-    - Support for other jvm based languages: contribution/support_for_other_jvm_based_languages.md
+    - Support for other JVM-based languages: contribution/support-for-other-jvm-based-languages.md
     - Knowledge base:
         - Artefact differentiation: contribution/knowledge-base/artefact-differentiation.md
         - Entry generation: contribution/knowledge-base/entry-generation.md
         - Shared buffer: contribution/knowledge-base/shared-buffer.md
-        - Memory Management: contribution/knowledge-base/memory-management.md
+        - Memory management: contribution/knowledge-base/memory-management.md

docs/src/doc/contribution/build-with-csharp-support.md

@@ -1,9 +1,10 @@
 ## Build engine for C# and Kotlin/JVM
-1. Fulfill requirements mentioned [here](https://docs.godotengine.org/en/stable/development/compiling/compiling_with_mono.html)
-2. `scons p=<platform> tools=yes module_mono_enabled=yes mono_glue=no`
+
+1. Fulfill requirements mentioned [here](https://docs.godotengine.org/en/stable/development/compiling/compiling_with_mono.html).
+2. `scons p=<platform> tools=yes module_mono_enabled=yes mono_glue=no`.
 3. `<godot_binary> --generate-mono-glue modules/mono/glue`
-    - For this step to work you need a jre in the `godot-root` folder
-    - And a `godot-bootstrap.jar` in `<godot-root>/bin`
-4. `export LD_PRELOAD=<path_to_sample_project>/jre-{amd64|arm64}/lib/libjsig.so`
-5. `scons -j$(nproc) platform=<platform> module_mono_enabled=yes`
-6. run with `../../../../bin/godot.linuxbsd.editor.x86_64.mono`
+    - For this step to work you need a JRE in the `godot-root` folder.
+    - And a `godot-bootstrap.jar` in `<godot-root>/bin`.
+4. `export LD_PRELOAD=<path_to_sample_project>/jre-{amd64|arm64}/lib/libjsig.so`.
+5. `scons -j$(nproc) platform=<platform> module_mono_enabled=yes`.
+6. Run with `../../../../bin/godot.linuxbsd.editor.x86_64.mono`.

docs/src/doc/contribution/general.md

@@ -1,12 +1,20 @@
-We encourage you to contribute to the project if you want. Even if you don't have any idea how the module works or if it seems overwhelming at first, we're here to help you getting started.
+We encourage you to contribute to the project if you want. Even if you don't have any idea how
+the module works or if it seems overwhelming at first, we're here to help you getting started.
 
 ## Keywords
+
 The following keywords are used throughout the contribution documentation:
 
 - `godot-root`: root dir in which the godot engine is cloned into
 - `module-dir`: root dir of our module
 
 ## Discussions
-Most of our discussions are happening on Discord. So if you have Discord or don't mind starting using it, feel free to [join](https://discord.gg/zpb5Ru7v9x) our server. But don't worry if you don't have or want to use Discord. Then the discussions are just in the corresponding issue. If you discuss on Discord though: don't forget to document all relevant outcome in the corresponding issue.  
 
-If you have critique or an opinion on a discussed topic, please be kind and give valuable feedback. If you are on the receiving end of the critique: don't take it personally. Many people are no native english speaker and it can happen that something which is not rude at all in the language of the writer, might sound rude in english.
+Most of our discussions are happening on Discord. So, if you have Discord or don't mind starting using it,
+feel free to [join](https://discord.gg/zpb5Ru7v9x) our server. But don't worry if you don't have or want to use Discord.
+Then the discussions are just in the corresponding issue. If you discuss on Discord though: don't forget to document all
+relevant outcome in the corresponding issue.
+
+If you have critique or an opinion on a discussed topic, please be kind and give valuable feedback. If you are on the
+receiving end of the critique: don't take it personally. Many people are no native english speaker and it can happen that
+something which is not rude at all in the language of the writer, might sound rude in english.

docs/src/doc/contribution/guidelines.md

@@ -1,17 +1,27 @@
 ## General
-We are working with the Code Owners feature of GitHub. This means each piece of code in our module has a maintainer who is the "Owner" of said code. This maintainer is usually the one who implemented it or has the most knowledge about that particular part of the module. General code may not have a specific "Owner". In this case the fallback is: all Maintainers.
 
-## Before Contributing
-Before you start to invest your precious time in writing code that you want to contribute, consider following these guidelines. They are here to make the lives of all people involved easier.
+We are working with the Code Owners feature of GitHub. This means each piece of code in our module has a maintainer who
+is the "Owner" of said code.
+This maintainer is usually the one who implemented it or has the most knowledge about that particular part of the module.
+General code may not have a specific "Owner". In this case the fallback is: all Maintainers.
+
+## Before contributing
+
+Before you start to invest your precious time in writing code that you want to contribute, consider following these guidelines.
+They are here to make the lives of all people involved easier.
 
 - If you have an idea or a bug you want to fix, first look if an issue already exists that describes this Feature/Bug.
 - If such a issue exists, and a person is already assigned, it means the assigned person is working on it. But don't go away yet! Maybe this person could need your help, or you have some valuable input for the topic.
 - If the issue exists, but no one is assigned. You are free to state your interest in implementing/fixing the issue. But don't just start working. To prevent multiple people working on the same issue, we need to know you're working on it. Write in the issue, so we can assign it to you.
 - If the issue does not yet exist, open one and describe as best as you can, what your idea/what the bug is you want to tackle. The provided templates are a good starting point.
 
 ## Code
+
 ### Code style
-We enforce the code style to match the official Kotlin [coding conventions](https://kotlinlang.org/docs/reference/coding-conventions.html). Read there on how to set those up for your IDE. We will enforce this later on through CI and linting.  
+
+We enforce the code style to match the official Kotlin [coding conventions](https://kotlinlang.org/docs/reference/coding-conventions.html).
+Read there on how to set those up for your IDE. We will enforce this later on through CI and linting.
 
 ### Branching
+
 We do branching like described in `git-flow`.

docs/src/doc/contribution/knowledge-base/artefact-differentiation.md

@@ -1,29 +1,52 @@
 This document describes what the individual artefacts are for and how they are used.
 
 ## godot-library
+
 ### Overview
-The `godot-library` contains the godot api as kotlin classes as well as registration code. It is automatically added as a dependency to the users code by the `godot-gradle-plugin`. Hence, it is deployed to mavenCentral. It is also used as a dependency by `godot-bootstrap` and thus present in the `godot-bootstrap.jar` which gets shipped alongside the engine.
+
+The `godot-library` contains the godot api as Kotlin classes as well as registration code.
+It is automatically added as a dependency to the users code by the `godot-gradle-plugin`.
+Hence, it is deployed to `mavenCentral`. It is also used as a dependency by `godot-bootstrap` and
+thus present in the `godot-bootstrap.jar` which gets shipped alongside the engine.
 
 ### Usage
-The `godot-library` is mainly used by the end user implicitly. Implicitly because he does not add it by himself. The `godot-gradle-plugin` does that. But it is also used by the `godot-bootstrap.jar` for initial loading and usage in the editor. Important is, that during runtime, only the version that was added as a dependency to the users code through the `godot-gradle-plugin` is used. The version inside `godot-bootstrap` is only used for the editor.
+
+The `godot-library` is mainly used by the end user implicitly. Implicitly because he/she does not add it by himself.
+The `godot-gradle-plugin` does that. But, it is also used by the `godot-bootstrap.jar` for initial loading and usage in the editor.
+Important is, that during runtime, only the version that was added as a dependency to the users code through the `godot-gradle-plugin` is used.
+The version inside `godot-bootstrap` is only used for the editor.
 
 ## godot-bootstrap
+
 ### Overview
-The `godot-bootstrap` is a shadowJar (also known as fat jar) which contains the `godot-library` and runtime code to reload usercode in the editor after rebuilds.
+
+The `godot-bootstrap` is a "shadow JAR" (also known as [fat JAR](https://jenkov.com/tutorials/maven/maven-build-fat-jar.html)) which contains the `godot-library`
+and runtime code to reload usercode in the editor after rebuilds.
 
 ### Usage
-The `godot-bootstrap` is shipped alongside the engine for editor use and is bundled together with the game executable during export. It is never used by the user directly nor added as a dependency anywhere.
+
+The `godot-bootstrap` is shipped alongside the engine for editor use and is bundled together with the game executable during export.
+It is never used by the user directly nor added as a dependency anywhere.
 
 ## main
+
 ### Overview
-The `main.jar` is built when the user builds his code. It is a shadowJar containing only the users code as well as all the dependencies the user has defined recursively. This is needed so they and all dependencies and the dependencies of the dependencies are present at runtime.
+
+The `main.jar` is built when the user builds his code. It is a shadow JAR containing only the users code as well as all the dependencies
+the user has defined recursively. This is needed so they and all dependencies and the dependencies of the dependencies are present at runtime.
 
 ### Usage
-This jar is bundled together with the game executable during export and executed through the `godot-bootstrap` during runtime. It is nowhere else used.
+
+This JAR is bundled together with the game executable during export and executed through the `godot-bootstrap` during runtime. It is nowhere else used.
 
 ## usercode
+
 ### Overview
+
 The `usercode` artifact is a shared library which is only used on GraalVM native image builds. It contains all code from the `main.jar` and the `godot-bootstrap.jar`.
 
 ### Usage
-It replaces the `godot-bootstrap.jar` and the `main.jar` when the game is exported. It is only used when configured either as a commandline arg or through the configuration file (see [GraalVM documentation](../../user-guide/advanced/graal-vm-native-image.md) for more information). While it is used (either in game or editor) no usercode can be reloaded.
+
+It replaces the `godot-bootstrap.jar` and the `main.jar` when the game is exported. It is only used when configured either as a
+command line argument or through the configuration file (see [GraalVM documentation](../../user-guide/advanced/graal-vm-native-image.md) for more information).
+While it is used (either in game or editor) no usercode can be reloaded.