update docs for GroovyScript 1.2.4 (#38)

* update docs for GroovyScript 1.2.4

* remove duplicate method invalid documentation

* add equality difference from java

* update runconfig for classes removal

* fix custom reloading instructions

* update class information

* include metaclass information

* update main page description info

* warn about file name and method size

Author: WaitingIdly

docs/groovy-script/getting_started/classes.md

@@ -2,37 +2,114 @@
 # Classes
 
 
-While all Groovy files are technically class files,
-this refers specifically to files interacting with the [`runConfig.json`](./run_config.md#classes) classes section.
+All groovy files are classes.
+However, if no specific class declaration is used, the file will be parsed as a script file.
 
 
-## Class Declaration
+## Groovy File Extensions
 
 
-::: info Bug {id="bug"}
+A Groovy file is a file with the extension `groovy`, `gy`, `gvy`, or `gsh`.
 
-Starting from version `1.0.0` and getting fixed in version `1.1.0`
-there was a bug which caused class files require a package declaration
-in the form of `package classes` at the top of the script to be functional.
+In almost all places on the wiki, only `groovy` will be used.
 
+Groovy file names must follow the [Java class naming specification](https://docs.oracle.com/javase/specs/jls/se7/html/jls-3.html#jls-3.8),
+meaning valid names match the regex pattern of `[a-zA-Z$_][a-zA-Z0-9$_]*`.
+To spell it out: a file name must begin with a letter, dollar sign, or underscore,
+and every character afterwards is must be either a letter, number, dollar sign, or underscore.
+
+::: warning Invalid Name {id="danger"}
+
+If the file does not have a valid name it will not be loaded!
+
+:::
+
+::: warning Global Object Confusion {id="warning"}
+
+As the file name will create a class with the same name, naming your file with the
+same name as a global object such as `item`, `mods`, `eventManager`, or otherwise
+may cause unexpected issues due to accessing the class instead of the desired global object!
+
+:::
+
+
+## Script Files
+
+
+Script files must be placed in a specific [loader](./run_config.md#loaders) to be run,
+and will be executed in that stage.
+
+::: code-group
+
+```groovy [postInit/Example.groovy]
+log.info('A normal script file')
+```
+
+```json [runConfig.json]
+{
+  "loaders": {
+    "postInit": [
+      "postInit/Example.groovy"
+    ]
+  },
+}
+```
 :::
 
-Classes must be declared in the locations specified in the [`runConfig.json`](./run_config.md#classes) by the classes element.
+Behind the scenes, a script file will be converted like so:
+
+::: code-group
+
+```groovy [postInit/Example.groovy]
+import groovy.transform.Field
+
+@Field // this annotation makes what would otherwise be a local to become a field
+int baseValue = 2
 
+def hello = 'hello, world!' // creates a local variable
 
-## Importing
+log.info(hello)
+int power(int n) { baseValue**n }
+log.info(power(3))
+```
+
+```groovy [Script File]
+package postInit
+
+import groovy.transform.Field
+// imports still occur before the code
 
+class Example extends groovy.lang.Script {
 
-You can import these classes the same way you would any package from Java.
-The default package classes are located in is `classes`, so you would run `import classes.DemoClass`
+    @Field
+    int baseValue = 2
 
+    int power(int n) { baseValue**n } // if baseValue was not annotated with @Field, an exception will be thrown!
 
-## Example
+    def run() {
+        def hello = 'hello, world!'
+        log.info(hello)
+        log.info(power(3))
+    }
+}
+```
+
+:::
+
+::: warning Maximum method size {id="danger"}
+
+Java cannot load methods larger than [64kb](https://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.11).
+Particularly large GroovyScript scripts may pass this - in this situation,
+you will need to refactor your scripts in some fashion to avoid this issue.
+
+:::
+
+
+## Custom Classes
 
 :::: info Basic Example {id="example"}
 
-With a named `DemoClass.groovy` that is registered by the `runConfig.json` to the `classes` element,
-you can access that class from any script file or another class.
+With a named `DemoClass.groovy` from any other groovy class.
 
 ::: code-group
 
@@ -44,9 +121,11 @@ class DemoClass {
 ```
 
 ```json [runConfig.json]
-"classes": [
-  "classes/" // targets either the file or a folder that the file is nested within
-]
+"loaders": {
+  "preInit": [
+    "classes/" // targets either the file or a folder that the file is nested within
+  ]
+}
 ```
 
 ```groovy [postInit/CheckIron.groovy]

docs/groovy-script/getting_started/groovy_modifications.md

@@ -74,3 +74,32 @@ A number of packages, classes, and methods are banned, and not able to be used b
 
 In particular, when interacting with a File object through Groovy,
 the File can only refer to a file path that targets inside the minecraft directory.
+
+
+## MetaClass
+
+
+Groovy adds a new property to every object, `MetaClass`, which can be accessed via `object.metaClass`.
+This can be used for meta-programming, but in GroovyScript we have custom additions to it
+to allow modifying the visibility and mutability of fields and methods.
+
+To strip `final` from a field, allowing it to be set, do
+
+::: info Example {id="example"}
+
+```groovy:no-line-numbers
+obj.metaClass.makeMutable('fieldName')
+```
+
+:::
+
+To make a method or field public, allowing it to be accessed, do
+
+::: info Example {id="example"}
+
+```groovy:no-line-numbers
+obj.metaClass.makePublic('fieldName')
+obj.metaClass.makePublic('methodName')
+```
+
+:::

docs/groovy-script/getting_started/reloading.md

@@ -78,12 +78,13 @@ class DemoRegistry {
 :::
 ::::
 
-Then, add an event listener that is listening for `GroovyReloadEvent`.
-Inside of this event listener, call the `onReload` method.
+Then, you can accomplish reloading via one of two ways:
+1. Create an event listener that is listening for `GroovyReloadEvent` *in the `init` stage*.
+2. Check `isReloading()` *in the `postInit` stage*.
 
 ::: code-group
 
-```groovy [postInit/ReloadHelper.groovy]
+```groovy [init/ReloadHelper.groovy]
 import classes.DemoRegistry
 import com.cleanroommc.groovyscript.event.GroovyReloadEvent
 
@@ -92,6 +93,15 @@ eventManager.listen(GroovyReloadEvent) {
 }
 ```
 
+```groovy [postInit/ReloadHelper.groovy]
+import classes.DemoRegistry
+
+if (!isReloading()) return
+
+DemoRegistry.instance.onReload()
+```
+
+
 :::
 
 Finally, any time you would add a recipe to or remove a recipe from `DemoHolder.DemoRecipeList`,

docs/groovy-script/getting_started/run_config.md

@@ -21,9 +21,6 @@ Let's see what the file can look like.
   "packId": "",
   "version": "1.0.0",
   "debug": false,
-  "classes": [
-    "classes/"
-  ],
   "loaders": {
     "preInit": [
       "preInit/"
@@ -86,6 +83,21 @@ and logs the line numbers in errors.
 
 ## `classes`
 
+This *was* an element used to control what files were loaded as class files
+prior to [GroovyScript 1.2.3](https://github.com/CleanroomMC/GroovyScript/tree/v1.2.3).
+
+::: info Failure {id="failure"}
+
+If `classes` is an element in your `runConfig.json` file, a fatal message will be logged
+and you **must** remove it in order to be able to launch.
+
+Instead, load your classes via one of the loaders - typically [`preInit`](#preinit).
+To migrate in this fashion, simply add `"classes/"` to the `preInit` loader.
+
+:::
+
+:::: details Prior to GroovyScript 1.2.3 {id="warning"}
+
 Files that contain a single class should be specified here.
 It makes sure classes are loaded when scripts try to access them.
 You can specify classes to only load in certain loaders.
@@ -113,6 +125,8 @@ This works exactly like the `loaders` property.
 ```
 :::
 
+::::
+
 ## `loaders`
 
 This defines at what stage what files should be loaded.

docs/groovy-script/groovy/differences_from_java.md

@@ -140,6 +140,30 @@ def map2 = [(1): "example", (3): "demo"] // if the key is an expression, wrappin
 
 :::
 
+## Equality
+
+In Java, you can compare two objects by reference equality using two equal signs.
+Objects can override `equals` to provide a custom equal check.
+
+In Groovy, comparing two objects by reference equality requires *three* equal signs,
+and using two defers to `equals` via [operator overloading](./operators.md#operator-overloading).
+
+::: code-group
+
+```java
+a == b // reference equality
+a.equals(b) // requires that a is non-null
+a == null ? b == null : a.equals(b) // null-safe check
+```
+
+```groovy
+a === b // reference equality
+a == b // shorthand for a.equals(b)
+a.equals(b) // null-safe check
+```
+
+:::
+
 ## Visibility
 
 In Java, fields, classes, and methods that do not have an access specifier stated are `package-private` by default, meaning they are only visible to other classes inside the package.

docs/groovy-script/index.md

@@ -3,6 +3,7 @@
 next:
   text: 'Getting Started'
   link: '/groovy-script/getting_started/'
+description: "GroovyScript is a comprehensive scripting sandbox for Minecraft 1.12.2 via the Groovy language."
 ---
 
 # GroovyScript

docs/groovy-script/minecraft/helpers/crafting.md

@@ -166,7 +166,18 @@ Just like other recipe types, the Crafting Table also uses a recipe builder.
 
 Don't know what a builder is? Check [the builder info page](../../getting_started/builder.md) out.
 
-:::::::::: details crafting.shapedBuilder() {open id="abstract"}
+:::::::::: details Recipe Builder {open id="abstract"}
+
+---
+
+- Create the Recipe Builder.
+
+    ```groovy:no-line-numbers
+    crafting.shapedBuilder()
+    ```
+
+---
+
 - `ResourceLocation`. Sets the Resource Location of the recipe.
 
     ```groovy:no-line-numbers
@@ -229,12 +240,16 @@ Don't know what a builder is? Check [the builder info page](../../getting_starte
     recipeAction(Closure<Void>)
     ```
 
+---
+
 - First validates the builder, returning `null` and outputting errors to the log file if the validation failed, then registers the builder and returns the registered object. (returns `null` or `net.minecraft.item.crafting.IRecipe`).
 
     ```groovy:no-line-numbers
     register()
     ```
 
+---
+
 ::::::::: details Example {open id="example"}
 ```groovy:no-line-numbers
 crafting.shapedBuilder()
@@ -331,7 +346,18 @@ crafting.shapedBuilder()
 
 ::::::::::
 
-:::::::::: details crafting.shapelessBuilder() {open id="abstract"}
+:::::::::: details Recipe Builder {open id="abstract"}
+
+---
+
+- Create the Recipe Builder.
+
+    ```groovy:no-line-numbers
+    crafting.shapelessBuilder()
+    ```
+
+---
+
 - `ResourceLocation`. Sets the Resource Location of the recipe.
 
     ```groovy:no-line-numbers
@@ -372,12 +398,16 @@ crafting.shapedBuilder()
     recipeAction(Closure<Void>)
     ```
 
+---
+
 - First validates the builder, returning `null` and outputting errors to the log file if the validation failed, then registers the builder and returns the registered object. (returns `null` or `net.minecraft.item.crafting.IRecipe`).
 
     ```groovy:no-line-numbers
     register()
     ```
 
+---
+
 ::::::::: details Example {open id="example"}
 ```groovy:no-line-numbers
 crafting.shapelessBuilder()
@@ -462,9 +492,9 @@ crafting.shapelessBuilder()
 
 :::::::::: details Example {open id="example"}
 ```groovy:no-line-numbers
-crafting.removeByOutput(item('minecraft:gold_ingot'))
-crafting.remove('minecraft:mossy_stonebrick')
 crafting.remove(resource('minecraft:stonebrick'))
+crafting.remove('minecraft:mossy_stonebrick')
+crafting.removeByOutput(item('minecraft:gold_ingot'))
 crafting.removeAll()
 ```