Pulling all pending Bukkit-JavaDoc changes

A special thanks goes to @aerouk for almost all of the changes found here.

By: Wesley Wolfe <weswolf@aol.com>

paper-api/src/test/java/org/bukkit/TestServer.java

@@ -1,100 +1,100 @@
-package org.bukkit;
-
-import java.lang.reflect.InvocationHandler;
-import java.lang.reflect.Method;
-import java.lang.reflect.Proxy;
-import java.util.Map;
-import java.util.logging.Logger;
-
-import org.bukkit.command.SimpleCommandMap;
-import org.bukkit.plugin.PluginManager;
-import org.bukkit.plugin.SimplePluginManager;
-
-import com.google.common.collect.ImmutableMap;
-
-public class TestServer implements InvocationHandler {
-    private static interface MethodHandler {
-        Object handle(TestServer server, Object[] args);
-    }
-
-    private static final Map<Method, MethodHandler> methods;
-
-    static {
-        try {
-            ImmutableMap.Builder<Method, MethodHandler> methodMap = ImmutableMap.builder();
-            methodMap.put(
-                    Server.class.getMethod("isPrimaryThread"),
-                    new MethodHandler() {
-                        public Object handle(TestServer server, Object[] args) {
-                            return Thread.currentThread().equals(server.creatingThread);
-                        }
-                    }
-                );
-            methodMap.put(
-                    Server.class.getMethod("getPluginManager"),
-                    new MethodHandler() {
-                        public Object handle(TestServer server, Object[] args) {
-                            return server.pluginManager;
-                        }
-                    }
-                );
-            methodMap.put(
-                    Server.class.getMethod("getLogger"),
-                    new MethodHandler() {
-                        final Logger logger = Logger.getLogger(TestServer.class.getCanonicalName());
-                        public Object handle(TestServer server, Object[] args) {
-                            return logger;
-                        }
-                    }
-                );
-            methodMap.put(
-                    Server.class.getMethod("getName"),
-                    new MethodHandler() {
-                        public Object handle(TestServer server, Object[] args) {
-                            return TestServer.class.getSimpleName();
-                        }
-                    }
-                );
-            methodMap.put(
-                    Server.class.getMethod("getVersion"),
-                    new MethodHandler() {
-                        public Object handle(TestServer server, Object[] args) {
-                            return "Version_" + TestServer.class.getPackage().getImplementationVersion();
-                        }
-                    }
-                );
-            methodMap.put(
-                    Server.class.getMethod("getBukkitVersion"),
-                    new MethodHandler() {
-                        public Object handle(TestServer server, Object[] args) {
-                            return "BukkitVersion_" + TestServer.class.getPackage().getImplementationVersion();
-                        }
-                    }
-                );
-            methods = methodMap.build();
-
-            TestServer server = new TestServer();
-            Server instance = Proxy.getProxyClass(Server.class.getClassLoader(), Server.class).asSubclass(Server.class).getConstructor(InvocationHandler.class).newInstance(server);
-            Bukkit.setServer(instance);
-            server.pluginManager = new SimplePluginManager(instance, new SimpleCommandMap(instance));
-        } catch (Throwable t) {
-            throw new Error(t);
-        }
-    }
-
-    private Thread creatingThread = Thread.currentThread();
-    private PluginManager pluginManager;
-    private TestServer() {};
-
-    public static Server getInstance() {
-        return Bukkit.getServer();
-    }
-
-    public Object invoke(Object proxy, Method method, Object[] args) {
-        MethodHandler handler = methods.get(method);
-        if (handler != null) {
-            return handler.handle(this, args);
-        }
-        throw new UnsupportedOperationException(String.valueOf(method));
-    }
-}
+package org.bukkit;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Method;
+import java.lang.reflect.Proxy;
+import java.util.Map;
+import java.util.logging.Logger;
+
+import org.bukkit.command.SimpleCommandMap;
+import org.bukkit.plugin.PluginManager;
+import org.bukkit.plugin.SimplePluginManager;
+
+import com.google.common.collect.ImmutableMap;
+
+public class TestServer implements InvocationHandler {
+    private static interface MethodHandler {
+        Object handle(TestServer server, Object[] args);
+    }
+
+    private static final Map<Method, MethodHandler> methods;
+
+    static {
+        try {
+            ImmutableMap.Builder<Method, MethodHandler> methodMap = ImmutableMap.builder();
+            methodMap.put(
+                    Server.class.getMethod("isPrimaryThread"),
+                    new MethodHandler() {
+                        public Object handle(TestServer server, Object[] args) {
+                            return Thread.currentThread().equals(server.creatingThread);
+                        }
+                    }
+                );
+            methodMap.put(
+                    Server.class.getMethod("getPluginManager"),
+                    new MethodHandler() {
+                        public Object handle(TestServer server, Object[] args) {
+                            return server.pluginManager;
+                        }
+                    }
+                );
+            methodMap.put(
+                    Server.class.getMethod("getLogger"),
+                    new MethodHandler() {
+                        final Logger logger = Logger.getLogger(TestServer.class.getCanonicalName());
+                        public Object handle(TestServer server, Object[] args) {
+                            return logger;
+                        }
+                    }
+                );
+            methodMap.put(
+                    Server.class.getMethod("getName"),
+                    new MethodHandler() {
+                        public Object handle(TestServer server, Object[] args) {
+                            return TestServer.class.getSimpleName();
+                        }
+                    }
+                );
+            methodMap.put(
+                    Server.class.getMethod("getVersion"),
+                    new MethodHandler() {
+                        public Object handle(TestServer server, Object[] args) {
+                            return "Version_" + TestServer.class.getPackage().getImplementationVersion();
+                        }
+                    }
+                );
+            methodMap.put(
+                    Server.class.getMethod("getBukkitVersion"),
+                    new MethodHandler() {
+                        public Object handle(TestServer server, Object[] args) {
+                            return "BukkitVersion_" + TestServer.class.getPackage().getImplementationVersion();
+                        }
+                    }
+                );
+            methods = methodMap.build();
+
+            TestServer server = new TestServer();
+            Server instance = Proxy.getProxyClass(Server.class.getClassLoader(), Server.class).asSubclass(Server.class).getConstructor(InvocationHandler.class).newInstance(server);
+            Bukkit.setServer(instance);
+            server.pluginManager = new SimplePluginManager(instance, new SimpleCommandMap(instance));
+        } catch (Throwable t) {
+            throw new Error(t);
+        }
+    }
+
+    private Thread creatingThread = Thread.currentThread();
+    private PluginManager pluginManager;
+    private TestServer() {};
+
+    public static Server getInstance() {
+        return Bukkit.getServer();
+    }
+
+    public Object invoke(Object proxy, Method method, Object[] args) {
+        MethodHandler handler = methods.get(method);
+        if (handler != null) {
+            return handler.handle(this, args);
+        }
+        throw new UnsupportedOperationException(String.valueOf(method));
+    }
+}

paper-api/src/test/java/org/bukkit/event/TestEvent.java

@@ -1,19 +1,19 @@
-package org.bukkit.event;
-
-
-public class TestEvent extends Event {
-    private static final HandlerList handlers = new HandlerList();
-
-    public TestEvent(boolean async) {
-        super(async);
-    }
-
-    @Override
-    public HandlerList getHandlers() {
-        return handlers;
-    }
-
-    public static HandlerList getHandlerList() {
-        return handlers;
-    }
-}
+package org.bukkit.event;
+
+
+public class TestEvent extends Event {
+    private static final HandlerList handlers = new HandlerList();
+
+    public TestEvent(boolean async) {
+        super(async);
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}

paper-api/src/test/java/org/bukkit/plugin/PluginManagerTest.java

@@ -1,170 +1,176 @@
-package org.bukkit.plugin;
-
-import static org.hamcrest.Matchers.*;
-import static org.junit.Assert.*;
-
-import org.bukkit.TestServer;
-import org.bukkit.event.Event;
-import org.bukkit.event.TestEvent;
-import org.bukkit.permissions.Permission;
-
-import org.junit.After;
-import org.junit.Test;
-
-public class PluginManagerTest {
-    private class MutableObject {
-        volatile Object value = null;
-    }
-
-    private static final PluginManager pm = TestServer.getInstance().getPluginManager();
-    
-    private final MutableObject store = new MutableObject();
-
-    @Test
-    public void testAsyncSameThread() {
-        final Event event = new TestEvent(true);
-        try {
-            pm.callEvent(event);
-        } catch (IllegalStateException ex) {
-            assertThat(event.getEventName() + " cannot be triggered asynchronously from primary server thread.", is(ex.getMessage()));
-            return;
-        }
-        throw new IllegalStateException("No exception thrown");
-    }
-
-    @Test
-    public void testSyncSameThread() {
-        final Event event = new TestEvent(false);
-        pm.callEvent(event);
-    }
-
-    @Test
-    public void testAsyncLocked() throws InterruptedException {
-        final Event event = new TestEvent(true);
-        Thread secondThread = new Thread(
-            new Runnable() {
-                public void run() {
-                    try {
-                        synchronized (pm) {
-                            pm.callEvent(event);
-                        }
-                    } catch (Throwable ex) {
-                        store.value = ex;
-                    }
-                }});
-        secondThread.start();
-        secondThread.join();
-        assertThat(store.value, is(instanceOf(IllegalStateException.class)));
-        assertThat(event.getEventName() + " cannot be triggered asynchronously from inside synchronized code.", is(((Throwable) store.value).getMessage()));
-    }
-
-    @Test
-    public void testAsyncUnlocked() throws InterruptedException {
-        final Event event = new TestEvent(true);
-        Thread secondThread = new Thread(
-            new Runnable() {
-                public void run() {
-                    try {
-                        pm.callEvent(event);
-                    } catch (Throwable ex) {
-                        store.value = ex;
-                    }
-                }});
-        secondThread.start();
-        secondThread.join();
-        if (store.value != null) {
-            throw new RuntimeException((Throwable) store.value);
-        }
-    }
-
-    @Test
-    public void testSyncUnlocked() throws InterruptedException {
-        final Event event = new TestEvent(false);
-        Thread secondThread = new Thread(
-            new Runnable() {
-                public void run() {
-                    try {
-                        pm.callEvent(event);
-                    } catch (Throwable ex) {
-                        store.value = ex;
-                    }
-                }});
-        secondThread.start();
-        secondThread.join();
-        if (store.value != null) {
-            throw new RuntimeException((Throwable) store.value);
-        }
-    }
-
-    @Test
-    public void testSyncLocked() throws InterruptedException {
-        final Event event = new TestEvent(false);
-        Thread secondThread = new Thread(
-            new Runnable() {
-                public void run() {
-                    try {
-                        synchronized (pm) {
-                            pm.callEvent(event);
-                        }
-                    } catch (Throwable ex) {
-                        store.value = ex;
-                    }
-                }});
-        secondThread.start();
-        secondThread.join();
-        if (store.value != null) {
-            throw new RuntimeException((Throwable) store.value);
-        }
-    }
-
-    @Test
-    public void testRemovePermissionByNameLower() {
-        this.testRemovePermissionByName("lower");
-    }
-
-    @Test
-    public void testRemovePermissionByNameUpper() {
-        this.testRemovePermissionByName("UPPER");
-    }
-
-    @Test
-    public void testRemovePermissionByNameCamel() {
-        this.testRemovePermissionByName("CaMeL");
-    }
-
-    public void testRemovePermissionByPermissionLower() {
-        this.testRemovePermissionByPermission("lower");
-    }
-
-    @Test
-    public void testRemovePermissionByPermissionUpper() {
-        this.testRemovePermissionByPermission("UPPER");
-    }
-
-    @Test
-    public void testRemovePermissionByPermissionCamel() {
-        this.testRemovePermissionByPermission("CaMeL");
-    }
-
-    private void testRemovePermissionByName(final String name) {
-        final Permission perm = new Permission(name);
-        pm.addPermission(perm);
-        assertThat("Permission \"" + name + "\" was not added", pm.getPermission(name), is(perm));
-        pm.removePermission(name);
-        assertThat("Permission \"" + name + "\" was not removed", pm.getPermission(name), is(nullValue()));
-    }
-
-    private void testRemovePermissionByPermission(final String name) {
-        final Permission perm = new Permission(name);
-        pm.addPermission(perm);
-        assertThat("Permission \"" + name + "\" was not added", pm.getPermission(name), is(perm));
-        pm.removePermission(perm);
-        assertThat("Permission \"" + name + "\" was not removed", pm.getPermission(name), is(nullValue()));
-    }
-    
-    @After
-    public void tearDown() {
-        pm.clearPlugins();
-        assertThat(pm.getPermissions(), is(empty()));
-    }
-}
+package org.bukkit.plugin;
+
+import static org.hamcrest.Matchers.*;
+import static org.junit.Assert.*;
+
+import org.bukkit.TestServer;
+import org.bukkit.event.Event;
+import org.bukkit.event.TestEvent;
+import org.bukkit.permissions.Permission;
+
+import org.junit.After;
+import org.junit.Test;
+
+public class PluginManagerTest {
+    private class MutableObject {
+        volatile Object value = null;
+    }
+
+    private static final PluginManager pm = TestServer.getInstance().getPluginManager();
+
+    private final MutableObject store = new MutableObject();
+
+    @Test
+    public void testAsyncSameThread() {
+        final Event event = new TestEvent(true);
+        try {
+            pm.callEvent(event);
+        } catch (IllegalStateException ex) {
+            assertThat(event.getEventName() + " cannot be triggered asynchronously from primary server thread.", is(ex.getMessage()));
+            return;
+        }
+        throw new IllegalStateException("No exception thrown");
+    }
+
+    @Test
+    public void testSyncSameThread() {
+        final Event event = new TestEvent(false);
+        pm.callEvent(event);
+    }
+
+    @Test
+    public void testAsyncLocked() throws InterruptedException {
+        final Event event = new TestEvent(true);
+        Thread secondThread = new Thread(
+            new Runnable() {
+                public void run() {
+                    try {
+                        synchronized (pm) {
+                            pm.callEvent(event);
+                        }
+                    } catch (Throwable ex) {
+                        store.value = ex;
+                    }
+                }
+            }
+        );
+        secondThread.start();
+        secondThread.join();
+        assertThat(store.value, is(instanceOf(IllegalStateException.class)));
+        assertThat(event.getEventName() + " cannot be triggered asynchronously from inside synchronized code.", is(((Throwable) store.value).getMessage()));
+    }
+
+    @Test
+    public void testAsyncUnlocked() throws InterruptedException {
+        final Event event = new TestEvent(true);
+        Thread secondThread = new Thread(
+            new Runnable() {
+                public void run() {
+                    try {
+                        pm.callEvent(event);
+                    } catch (Throwable ex) {
+                        store.value = ex;
+                    }
+                }});
+        secondThread.start();
+        secondThread.join();
+        if (store.value != null) {
+            throw new RuntimeException((Throwable) store.value);
+        }
+    }
+
+    @Test
+    public void testSyncUnlocked() throws InterruptedException {
+        final Event event = new TestEvent(false);
+        Thread secondThread = new Thread(
+            new Runnable() {
+                public void run() {
+                    try {
+                        pm.callEvent(event);
+                    } catch (Throwable ex) {
+                        store.value = ex;
+                    }
+                }
+            }
+        );
+        secondThread.start();
+        secondThread.join();
+        if (store.value != null) {
+            throw new RuntimeException((Throwable) store.value);
+        }
+    }
+
+    @Test
+    public void testSyncLocked() throws InterruptedException {
+        final Event event = new TestEvent(false);
+        Thread secondThread = new Thread(
+            new Runnable() {
+                public void run() {
+                    try {
+                        synchronized (pm) {
+                            pm.callEvent(event);
+                        }
+                    } catch (Throwable ex) {
+                        store.value = ex;
+                    }
+                }
+            }
+        );
+        secondThread.start();
+        secondThread.join();
+        if (store.value != null) {
+            throw new RuntimeException((Throwable) store.value);
+        }
+    }
+
+    @Test
+    public void testRemovePermissionByNameLower() {
+        this.testRemovePermissionByName("lower");
+    }
+
+    @Test
+    public void testRemovePermissionByNameUpper() {
+        this.testRemovePermissionByName("UPPER");
+    }
+
+    @Test
+    public void testRemovePermissionByNameCamel() {
+        this.testRemovePermissionByName("CaMeL");
+    }
+
+    public void testRemovePermissionByPermissionLower() {
+        this.testRemovePermissionByPermission("lower");
+    }
+
+    @Test
+    public void testRemovePermissionByPermissionUpper() {
+        this.testRemovePermissionByPermission("UPPER");
+    }
+
+    @Test
+    public void testRemovePermissionByPermissionCamel() {
+        this.testRemovePermissionByPermission("CaMeL");
+    }
+
+    private void testRemovePermissionByName(final String name) {
+        final Permission perm = new Permission(name);
+        pm.addPermission(perm);
+        assertThat("Permission \"" + name + "\" was not added", pm.getPermission(name), is(perm));
+        pm.removePermission(name);
+        assertThat("Permission \"" + name + "\" was not removed", pm.getPermission(name), is(nullValue()));
+    }
+
+    private void testRemovePermissionByPermission(final String name) {
+        final Permission perm = new Permission(name);
+        pm.addPermission(perm);
+        assertThat("Permission \"" + name + "\" was not added", pm.getPermission(name), is(perm));
+        pm.removePermission(perm);
+        assertThat("Permission \"" + name + "\" was not removed", pm.getPermission(name), is(nullValue()));
+    }
+
+    @After
+    public void tearDown() {
+        pm.clearPlugins();
+        assertThat(pm.getPermissions(), is(empty()));
+    }
+}