From dfad9d25f2a5eeb6bb2f0e3ddea0ee8388385a3b Mon Sep 17 00:00:00 2001
From: Rongmario <rongmario@protonmail.com>
Date: Thu, 21 Sep 2023 22:24:21 +0100
Subject: [PATCH] Shadow annotation arguments and usages

Added `def_list` markdown extension
---
 .../mixin/annotation/shadow.md                | 101 ++++++++++++++++++
 mkdocs.yml                                    |   3 +
 2 files changed, 104 insertions(+)
 create mode 100644 docs/mod-development/mixin/annotation/shadow.md

diff --git a/docs/mod-development/mixin/annotation/shadow.md b/docs/mod-development/mixin/annotation/shadow.md
new file mode 100644
index 0000000..6acb654
--- /dev/null
+++ b/docs/mod-development/mixin/annotation/shadow.md
@@ -0,0 +1,101 @@
+`@Shadow` is used as placeholders for in a Mixin class. Where you would want to access fields and methods like how you would if you were working in the class you are Mixin'ing.
+
+### ^^Arguments^^
+`remap`
+
+:   `[Optional Boolean, default value: true`
+
+    The annotation processor will skip this if this is false. With the refmap skipping over this member. This is useful for members originating from mods and not Vanilla Minecraft.
+
+`aliases`
+
+:   `[Optional String Array, default value: {}`
+
+    This can be populated with other aliases, particularly useful when shadowing synthetic members, or if the member is known to have name-changes at runtime from other sources of transformation
+
+`prefix`
+
+:   `[Optional String, default value: "shadow$"]`
+
+    For compilers it is illegal to allow methods to have the same name, same arguments, regardless of the return types. This may be an issue when using `@Shadow`. Hence the `prefix` takes care of that for you, at runtime when the mixin is being applied, the name will be restored with the prefix removed.
+
+    ```java
+    public class Illegal {
+
+        protected String method(String argument) {
+            return "";
+        }
+
+        protected int method(String argument) {
+            return 0;
+        }
+
+    }
+
+    public class Legal {
+
+        @Shadow(prefix = "alt$")
+        protected String alt$method(String argument) {
+            return "";
+        }
+
+        protected int method(String argument) {
+            return 0;
+        }
+
+    }
+    ```
+
+### ^^Usages^^
+
+??? abstract "Shadowing a Field"
+    ```java title="Target.java"
+    public class Target {
+
+        private String privateValue = "Hello World";
+        protected int protectedValue = 42;
+
+    }
+    ```
+
+    ```java title="Example.java"
+    @Mixin(Target.class)
+    public class Example {
+
+        @Shadow private String privateValue = null; // Will not affect original field
+
+        @Shadow protected int protectedValue = 0; // Will not affect original field
+
+    }
+    ```
+
+??? abstract "Shadowing a Method"
+    ```java title="Target.java"
+    public class Target {
+
+        public void method() {
+            // ...
+        }
+
+        public int fruitfulMethod() {
+            // ...
+        }
+
+    }
+    ```
+
+    ```java title="Example.java"
+    @Mixin(Target.class)
+    public class Example {
+
+        @Shadow public void method() { }
+
+        // If the method needs to return something
+        // You can return primitive defaults or null
+        // But throwing an exception here helps if something goes extremely wrong
+        @Shadow public int fruitfulMethod() {
+            throw new AssertionError(); 
+        }
+
+    }
+    ```
diff --git a/mkdocs.yml b/mkdocs.yml
index 412e27c..9404f3d 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -19,6 +19,8 @@ nav:
     - Mixin:
       - Preface: mod-development/mixin/preface.md
       - MixinBooter: mod-development/mixin/mixinbooter.md
+      - Annotation:
+        - "@Shadow": mod-development/mixin/annotation/shadow.md
       - Environment:
         - Registration: mod-development/mixin/environment/registration.md
         - Configuration: mod-development/mixin/environment/configuration.md
@@ -63,6 +65,7 @@ plugins:
 
 markdown_extensions:
   - admonition
+  - def_list
   - attr_list
   - md_in_html
   - footnotes