From 631fd3c7f50c21e911b24daa4a749d685aad93c9 Mon Sep 17 00:00:00 2001
From: NotMyFault <mc.cache@web.de>
Date: Tue, 4 Jan 2022 20:57:23 +0100
Subject: [PATCH] docs: Document annotations

---
 FAWE-ANNOTATIONS-EXPLAINED.adoc | 46 +++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 FAWE-ANNOTATIONS-EXPLAINED.adoc

diff --git a/FAWE-ANNOTATIONS-EXPLAINED.adoc b/FAWE-ANNOTATIONS-EXPLAINED.adoc
new file mode 100644
index 000000000..d398a80a6
--- /dev/null
+++ b/FAWE-ANNOTATIONS-EXPLAINED.adoc
@@ -0,0 +1,46 @@
+:toc:
+:toclevels: 2
+
+= Fawe annotations explained
+
+If we have modified parts of the WorldEdit codebase, we considered annotating it with different styles of comments, which
+are explained in this document.
+
+== In-line annotations
+
+[source,java]
+-----------------
+public static Player adapt(com.sk89q.worldedit.entity.Player player) {
+        //FAWE start - Get player from PlayerProxy instead of BukkitPlayer if null
+        player = PlayerProxy.unwrap(player);
+        return player == null ? null : ((BukkitPlayer) player).getPlayer();
+        //FAWE end
+}
+-----------------
+The `-sources` jar retains comments, if you add the FAWE API to your maven or gradle project, you can view differences between the projects with ease.
+Behind the `//FAWE start - ` you can find a comment what has been changed and why it has been changed.
+
+== Block annotations
+
+[source,java]
+-----------------
+//FAWE start
+    @Override
+    public void setPermission(String permission, boolean value) {
+    }
+//FAWE end
+-----------------
+Annotations can cover whole methods or go beyond the method and wrap around several added methods.
+
+== Package annotations
+Class additions are added under the `com.fastasyncworldedit` namespace, but sometimes classes need to be added in package private.
+If that is done, you can find a `package-info.java` file within the package affected that outlines FAWE added classes:
+[source,java]
+-----------------
+/**
+* The following classes are FAWE additions:
+*
+* @see com.sk89q.worldedit.world.block.BlockTypesCache
+*/
+package com.sk89q.worldedit.world.block;
+-----------------