Pulling all pending Bukkit-JavaDoc changes

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

3 files changed, 295 insertions, 289 deletions

diff --git a/src/test/java/org/bukkit/TestServer.java b/src/test/java/org/bukkit/TestServer.java
index c521e2b3..2d840320 100644
--- a/src/test/java/org/bukkit/TestServer.java
+++ b/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));
+    }
+}
diff --git a/src/test/java/org/bukkit/event/TestEvent.java b/src/test/java/org/bukkit/event/TestEvent.java
index c06dfe94..25904f5f 100644
--- a/src/test/java/org/bukkit/event/TestEvent.java
+++ b/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;
+    }
+}
diff --git a/src/test/java/org/bukkit/plugin/PluginManagerTest.java b/src/test/java/org/bukkit/plugin/PluginManagerTest.java
index c4a240ee..6b86128e 100644
--- a/src/test/java/org/bukkit/plugin/PluginManagerTest.java
+++ b/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()));
+    }
+}