Fix up the tutorials a bit

4 files changed, 64 insertions, 25 deletions

diff --git a/docs/mixins/accessors.md b/docs/mixins/accessors.md
index f9ad7b8..60a174d 100644
--- a/docs/mixins/accessors.md
+++ b/docs/mixins/accessors.md
@@ -24,13 +24,13 @@ public interface AccessorMinecraft {
 }
 ```
 
-First, notice that we need to use an `interface`. Most mixins are `class`es. Accessors are the exception, since we don't want to actually put any code into the `Minecraft` class. Accessor mixins can also not be mixed with other mixin styles, but since you should have multiple mixins even for the same class for different things anyway, this shouldn't be an issue.
+First, notice that we need to use an `:::java interface`. Most mixins are `:::java class`es. Accessors are the exception, since we don't want to actually put any code into the `:::java Minecraft` class. Accessor mixins can also not be mixed with other mixin styles, but since you should have multiple mixins even for the same class for different things anyway, this shouldn't be an issue.
 
-Next we put the `@Mixin` annotation on our Accessor to let it known which class we want to inject into.
+Next we put the `:::java @Mixin` annotation on our Accessor to let it known which class we want to inject into.
 
-Then for a field we use the `@Accessor` annotation, with the name of the field we want to access. Please give all your mixin methods a `_mymodid` indicator, to avoid name collissions with other mods.
+Then for a field we use the `:::java @Accessor` annotation, with the name of the field we want to access. Please give all your mixin methods a `_mymodid` indicator, to avoid name collissions with other mods.
 
-For a setter, the method returns void and takes one argument of the type of the field you are targetting. For a getter, the method returns the type of the field you are targeting and takes no arguments.
+For a setter, the method returns `:::java void` and takes one argument of the type of the field you are targetting. For a getter, the method returns the type of the field you are targeting and takes no arguments.
 
 For an method invoker, you copy the method signature you want to call, but rename it to something unique with a `_mymodid` postfix.
 
diff --git a/docs/mixins/adding-fields.md b/docs/mixins/adding-fields.md
index c3533e9..ba54299 100644
--- a/docs/mixins/adding-fields.md
+++ b/docs/mixins/adding-fields.md
@@ -5,7 +5,7 @@ The next step up is injecting fields and methods into a class. This allows you t
 ```java
 @Mixin(EntityArmorStand.class)
 public class InjectCustomField {
-    Color colorOverride_mymodid;
+    Color colorOverride_mymodid = Color.RED;
 
     public void setColorOverride_mymodid(Color color) {
         colorOverride_mymodid = color;
@@ -17,13 +17,13 @@ public class InjectCustomField {
 }
 ```
 
-This mixin is a `class`, like all mixin (except for accessors) are. You can make the class abstract if you want. 
+This mixin is a `:::java class`, like all mixin (except for accessors) are. You can make the class abstract if you want. 
 
 First we add a new field (of course with modid postfix) into every armor stand.
 
 Then we also add a getter and a setter method for that field.
 
-Right now we run into a problem. We can't access mixin classes directly, so we cannot simply cast the `EntityArmorStand` into a `InjectCustomField`. Instead we create an interface (inside of our regular code, not inside of the mixin package) and implement that interface in our mixin class. You can also implement other interfaces this way, not just your own.
+Right now we run into a problem. We can't access mixin `:::java class`es directly, so we cannot simply cast the `EntityArmorStand` into a `InjectCustomField`. Instead we create an interface (inside of our regular code, not inside of the mixin package) and implement that interface in our mixin class. You can also implement other interfaces this way, not just your own.
 
 ```java
 // Inside our regular code. Not in the mixin package
@@ -48,3 +48,17 @@ public class InjectCustomField implement ColorFieldAccessor {
     }
 }
 ```
+
+Now we can just cast any instance of `EntityArmorStand` to `ColorFieldAccessor`:
+
+```java
+public static Color getColorOverrideForArmorStand(EntityArmorStand armorStand) {
+    return ((ColorFieldAccessor) armorStand).getColorOverride_mymodid();
+}
+```
+
+
+
+
+
+
diff --git a/docs/mixins/index.md b/docs/mixins/index.md
index bf4aa67..400d0a8 100644
--- a/docs/mixins/index.md
+++ b/docs/mixins/index.md
@@ -1,10 +1,11 @@
 # Mixins
 
-Mixins allow you to change Minecraft code. This is massively powerful, but you need to be very careful when using them, especially when considering to work together with other mods.
+Mixins allow you to change Minecraft code. This is massively powerful, but you need to be very careful when using them, especially when considering if you want to integrate well with other mods.
 
 !!! info
     The [MinecraftDev](https://mcdev.io/) plugin is pretty much non negotiable when coding Mixins. It enables auto completion, shows errors when your mixins are wrong in your IDE and allows you to directly navigate to the code you are changing.
-    It also has some other functions that allow for easier Minecraft development, but most of the functionality is aimed at higher versions.
+
+    It also has some other functions that allow for easier Minecraft development, but most of that functionality is aimed at higher Minecraft versions.
 
 > Please forgive the the nonsensical examples. I try to make the examples as simple as possible. [Check](https://github.com/NotEnoughUpdates/NotEnoughUpdates/tree/master/src/main/java/io/github/moulberry/notenoughupdates/mixins) [out](https://github.com/hannibal002/SkyHanni/tree/beta/src/main/java/at/hannibal2/skyhanni/mixins/transformers) [some](https://github.com/Skytils/SkytilsMod/tree/1.x/src/main/java/gg/skytils/skytilsmod/mixins/transformers) [open](https://github.com/inglettronald/DulkirMod/tree/master/src/main/java/dulkirmod/mixins) source mods to check out some real world mixins.
 
@@ -47,7 +48,7 @@ public void someMixinMethod_mymodid() {}
 public void someMixinMethod$mymodid() {}
 ```
 
-There are some exceptions for `@Inject`s, but in general it doesn't hurt to just add the postfix.
+There are some exceptions for `:::java @Inject`s, but in general it doesn't hurt to just add the postfix.
 
 ### Non destructive mixins
 
@@ -57,11 +58,11 @@ I.e. if you want a mixin to color mobs, and your mod decides not to color a mob,
 
 There are some general ground rules for achieving this behaviour: 
 
- - Only use `cir.setReturnValue()` or `ci.cancel()` if your mod decides to act on something. The default action should be to pass through to the next mixin or vanilla by doing nothing.
- - Don't use `@Redirect`. Only one mixin can ever use a `@Redirect` on the same call. Only one redirect will ever work, even if your mod does nothing different with a given method call.
- - Don't use `@Overwrite` (and don't overwrite without the annotation either, lol). Only one overwrite will ever work, even if your mod does nothing different with a given method call.
+ - Only use `:::java cir.setReturnValue()` or `:::java ci.cancel()` if your mod decides to act on something. The default action should be to pass through to the next mixin or vanilla by doing nothing.
+ - Don't use `:::java @Redirect`. Only one mixin can ever use a `:::java @Redirect` on the same call. Only one redirect will ever work, even if your mod does nothing different with a given method call.
+ - Don't use `:::java @Overwrite` (and don't overwrite without the annotation either, lol). Only one overwrite will ever work, even if your mod does nothing different with a given method call.
 
-Of course you will have to break those rules from time to time. But before you do, think twice if you need to. And if you do, maybe consider exposing some sort of API for other mods to hook into your code?
+Of course you will have to break those rules from time to time. But before you do, think twice if you *really* need to. And if you do, maybe consider exposing some sort of API for other mods to hook into your code?
 
 ## Troubleshooting
 
diff --git a/docs/mixins/simple-injects.md b/docs/mixins/simple-injects.md
index eeea65e..b635973 100644
--- a/docs/mixins/simple-injects.md
+++ b/docs/mixins/simple-injects.md
@@ -9,26 +9,41 @@ Now we will modify an existing method in Minecrafts code. This will allow us to
 
 ## The easiest of the easiest
 
-Let's start with probably the easiest `@Inject` out there. The HEAD inject. This mixin will inject whatever code you have inside your method at the start of the method you target.
+Let's start with probably the easiest `@Inject` out there. The `HEAD` inject. This mixin will inject whatever code you have inside your method at the start of the method you target.
 
 ```java
-@Mixin(PlayerControllerMP.class)
+@Mixin(PlayerControllerMP.class) // (1)!
 public class RightClickWithItemEvent {
 
-    @Inject(method = "sendUseItem", at = @At("HEAD"))
-    private void onSendUseItem_mymod(EntityPlayer playerIn, World worldIn, ItemStack itemStackIn, CallbackInfoReturnable<Boolean> cir) {
+    @Inject( // (2)!
+        method = "sendUseItem", // (3)!
+        at = @At("HEAD")) // (4)!
+    private void onSendUseItem_mymod( // (5)!
+        EntityPlayer playerIn, World worldIn, ItemStack itemStackIn, // (6)!
+        CallbackInfoReturnable<Boolean> cir // (7)!
+        ) {
         MinecraftForge.EVENT_BUS.post(new SendUseItemEvent(playerIn, worldIn, itemStackIn));
     }
 }
 ```
 
+1. First we declare which class we want to change 
+2. `:::java @Inject` allows us to add code into an already existing method
+3. This sets the method into which we want to inject something. Be careful of overloaded methods here. Check out the [advanced tutorial](./advanced-injects.md) for more info.
+4. The `:::java @At` specifies where our code will be injected. `HEAD` just means the top of the method.
+5. The injected code method should be `:::java private` and `:::java void` no matter what your target method is. You might also need to make your method `:::java static`
+6. You need to copy over all the parameters from your original method into which you are injecting.
+7. You need one extra parameter for the callback info.
+
+
+
 First we want to inject into the `PlayerControllerMP` class.
 
 We create an `@Inject`. This tells us in which method we want to inject (`sendUseItem`) and where in that method (`HEAD`, meaning the very top of the method).
 
 The actual method signature for an inject is always to return a `void`. You can make them `private` or `public`. The arguments are the same arguments as the method you want to inject into, as well as a `CallbackInfo`.
 
-For a method returning void, you just use a `CallbackInfo`, and if the method returns something, you use `CallbackInfoReturnable<ReturnTypeOfTheInjectedIntoMethod>`.
+For a method returning void, you just use a `:::java CallbackInfo`, and if the method returns something, you use `:::java CallbackInfoReturnable<ReturnTypeOfTheInjectedIntoMethod>`.
 
 Your method will now be called every time the `sendUseItem` is called with the arguments to that method and the `CallbackInfo`.
 
@@ -50,7 +65,8 @@ Let's take this example method:
 
 ```java
 public void methodA() {
-    // ...
+    // Let's pretend lots of code calls methodA, so we don't want to inject
+    // ourselves into methodA
 }
 
 public void methodB() {
@@ -64,18 +80,26 @@ public void methodB() {
 We can inject ourselves into `methodB` as well. It is *just* a bit more complicated than the `HEAD` inject.
 
 ```java
-@Inject(method = "methodB", at = @At(target = "Lnet/some/Class;methodA()V", value = "INVOKE"))
+@Inject(
+    method = "methodB", // (3)!
+    at = @At(
+        target = "Lnet/some/Class;methodA()V", // (1)!
+        value = "INVOKE")) // (2)!
 private void onMethodBJustCalledMethodA(CallbackInfo ci) {
 }
 ```
 
+1. This is the method call for which we are searching. This is not the method into which our code will be injected.
+2. This tells mixin that we want `target` to point to a method call (not a field or anything else).
+3. This is the method into which we want our code to be injected.
+
 > **HUUUUH, where does that come from???**
 
-Don't worry! I won't explain you how to understand these `target`s in this tutorial, but you also don't need to understand that `target`. Instead you can simply use the Minecraft Development IntelliJ Plugin to help you. Simply type `@At(value = "INVOKE", target = "")`, place your cursor inside of the target and use auto completion (<kbd>Ctrl + Space</kbd>) and the plugin will recommend you a bunch of method calls. Find whichever seems right to you and press enter. You can now (also thanks to the plugin) <kbd>Ctrl</kbd> click on the `target` string, which will take you to the decompiled code exactly to where that target will inject.
+Don't worry! I won't explain you how to understand these `target`s in this tutorial, but you also don't need to understand that `target`. Instead you can simply use the Minecraft Development IntelliJ Plugin to help you. Simply type `:::java @At(value = "INVOKE", target = "")`, place your cursor inside of the target and use auto completion (++ctrl+space++) and the plugin will recommend you a bunch of method calls. Find whichever seems right to you and press enter. You can now (also thanks to the plugin) ++ctrl++ click on the `target` string, which will take you to the decompiled code exactly to where that target will inject.
 
 ## Ordinals
 
-Let's take the method injection example from before and change it a bit:
+Let's take the `INVOKE` injection example from before and change it a bit:
 
 ```java
 public void methodA() {
@@ -93,7 +117,7 @@ public void methodB() {
 }
 ```
 
-We can't simply use the same `@Inject` from before, since by default a `INVOKE` inject will inject just after *every* method call. Here, we can use the `ordinal` classifier to specify which method call we want to use. Keep in mind this is about where to place our injection, so many method calls in a loop will not increment the ordinal, only unique code locations that call the function will increase the ordinal. Keep in mind: we are programmers, we start counting with `0`.
+We can't simply use the same `:::java @Inject` from before, since by default a `INVOKE` inject will inject just after *every* method call. Here, we can use the `ordinal` classifier to specify which method call we want to use. Keep in mind this is about where to place our injection, so many method calls in a loop will not increment the ordinal, only unique code locations that call the function will increase the ordinal. Remember: we are programmers, we start counting with `0`.
 
 ```java
 @Inject(method = "methodB", at = @At(target = "Lnet/some/Class;methodA()V", value = "INVOKE", ordinal = 1))
@@ -121,7 +145,7 @@ private void onIsHittingPosition_mymod(BlockPos pos, CallbackInfoReturnable<Bool
 }
 ```
 
-For `void` methods you need to use `callbackInfo.cancel()`. For all other methods you need to use `callbackInfoReturnable.setReturnValue(returnValue)`.
+For `void` methods you need to use `:::java callbackInfo.cancel()` which acts the same as a normal `:::java return;` would in the method you are injecting into. For all other methods you need to use `:::java callbackInfoReturnable.setReturnValue(returnValue)` which corresponds to `:::java return returnValue;`.
 
 
 !!! important