Pulling all pending Bukkit-JavaDoc changes

By: Wesley Wolfe <weswolf@aol.com>

paper-api/src/main/java/org/bukkit/Server.java

@@ -652,7 +652,7 @@ public interface Server extends PluginMessageRecipient {
 
     /**
      * Gets user-specified limit for number of ambient mobs that can spawn in a chunk
-     * @returns The ambient spawn limit
+     * @return The ambient spawn limit
      */
     int getAmbientSpawnLimit();
 

paper-api/src/main/java/org/bukkit/World.java

@@ -671,10 +671,11 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * Spawn a {@link FallingBlock} entity at the given {@link Location} of the specified blockId (converted to {@link Material})
      *
      * @param location The {@link Location} to spawn the FallingBlock
-     * @param blockId see {@see #spawnFallingBlock(org.bukkit.Location, org.bukkit.Material, byte)} material
+     * @param blockId The id of the intended material
      * @param blockData The block data
      * @return The spawned FallingBlock instance
-     * @throws IllegalArgumentException see {@see #spawnFallingBlock(org.bukkit.Location, org.bukkit.Material, byte)}
+     * @throws IllegalArgumentException if location is null, or blockId is invalid
+     * @see #spawnFallingBlock(org.bukkit.Location, org.bukkit.Material, byte)
      */
     public FallingBlock spawnFallingBlock(Location location, int blockId, byte blockData) throws IllegalArgumentException;
 
@@ -999,7 +1000,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
 
     /**
      * Gets the limit for number of ambient mobs that can spawn in a chunk in this world
-     * @returns The ambient spawn limit
+     * @return The ambient spawn limit
      */
     int getAmbientSpawnLimit();
 
@@ -1021,7 +1022,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * @param volume The volume of the sound
      * @param pitch The pitch of the sound
      */
-    void playSound(Location loc, Sound sound, float volume, float pitch);
+    void playSound(Location location, Sound sound, float volume, float pitch);
 
     /**
      * Get existing rules

paper-api/src/main/java/org/bukkit/block/Skull.java

@@ -24,7 +24,7 @@ public interface Skull extends BlockState {
     /**
      * Sets the owner of the skull
      *
-     * @param owner the new owner of the skull
+     * @param name the new owner of the skull
      * @return true if the owner was successfully set
      */
     public boolean setOwner(String name);

paper-api/src/main/java/org/bukkit/configuration/ConfigurationSection.java

@@ -297,7 +297,7 @@ public interface ConfigurationSection {
      * <p />
      * If the double does not exist but a default value has been specified, this
      * will return the default value. If the double does not exist and no default
-     * value was specified, this will return null.
+     * value was specified, this will return 0.
      *
      * @param path Path of the double to get.
      * @return Requested double.
@@ -334,7 +334,7 @@ public interface ConfigurationSection {
      * <p />
      * If the long does not exist but a default value has been specified, this
      * will return the default value. If the long does not exist and no default
-     * value was specified, this will return null.
+     * value was specified, this will return 0.
      *
      * @param path Path of the long to get.
      * @return Requested long.

paper-api/src/main/java/org/bukkit/conversations/FixedSetPrompt.java

@@ -31,8 +31,8 @@ public abstract class FixedSetPrompt extends ValidatingPrompt {
 
     /**
      * Utility function to create a formatted string containing all the options declared in the constructor.
-     * The result is formatted like "[bar, cheese, panda]"
-     * @return
+     * 
+     * @return the options formatted like "[bar, cheese, panda]" if bar, cheese, and panda were the options used
      */
     protected String formatFixedSet() {
         return "[" + StringUtils.join(fixedSet, ", ") + "]";

paper-api/src/main/java/org/bukkit/event/Event.java

@@ -17,6 +17,7 @@ public abstract class Event {
 
     /**
      * This constructor is used to explicitly declare an event as synchronous or asynchronous.
+     *
      * @param isAsync true indicates the event will fire asynchronously. false by default
      */
     public Event(boolean isAsync) {
@@ -47,6 +48,7 @@ public abstract class Event {
      * <li>Some implementations may selectively declare a specific event use as asynchronous.
      *          This behavior should be clearly defined.</li>
      * <li>Asynchronous calls are not calculated in the plugin timing system.</li>
+     *
      * @return false by default, true if the event fires asynchronously
      */
     public final boolean isAsynchronous() {

paper-api/src/main/java/org/bukkit/scheduler/BukkitRunnable.java

@@ -42,7 +42,7 @@ public abstract class BukkitRunnable implements Runnable {
      * @return a BukkitTask that contains the id number
      * @throws IllegalArgumentException if plugin is null
      * @throws IllegalStateException if this was already scheduled
-     * @see BukkitScheduler#runTaskAsynchronously(Plugin, Runnable, long, long)
+     * @see BukkitScheduler#runTaskAsynchronously(Plugin, Runnable)
      */
     public synchronized BukkitTask runTaskAsynchronously(Plugin plugin) throws IllegalArgumentException, IllegalStateException  {
         checkState();
@@ -53,12 +53,11 @@ public abstract class BukkitRunnable implements Runnable {
      * Schedules this to run after the specified number of server ticks.
      *
      * @param plugin the reference to the plugin scheduling task
-     * @param task the task to be run
      * @param delay the ticks to wait before running the task
      * @return a BukkitTask that contains the id number
      * @throws IllegalArgumentException if plugin is null
      * @throws IllegalStateException if this was already scheduled
-     * @see BukkitScheduler#runTaskLater(Plugin, Runnable, long, long)
+     * @see BukkitScheduler#runTaskLater(Plugin, Runnable, long)
      */
     public synchronized BukkitTask runTaskLater(Plugin plugin, long delay) throws IllegalArgumentException, IllegalStateException  {
         checkState();
@@ -76,7 +75,7 @@ public abstract class BukkitRunnable implements Runnable {
      * @return a BukkitTask that contains the id number
      * @throws IllegalArgumentException if plugin is null
      * @throws IllegalStateException if this was already scheduled
-     * @see BukkitScheduler#runTaskLaterAsynchronously(Plugin, Runnable, long, long)
+     * @see BukkitScheduler#runTaskLaterAsynchronously(Plugin, Runnable, long)
      */
     public synchronized BukkitTask runTaskLaterAsynchronously(Plugin plugin, long delay) throws IllegalArgumentException, IllegalStateException  {
         checkState();

paper-api/src/main/javadoc/org/bukkit/block/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Classes used to manipulate the voxels in a {@link org.bukkit.World world},
+ * including special states.
+ * <p>
+ */
+package org.bukkit.block;
+

paper-api/src/main/javadoc/org/bukkit/command/defaults/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Commands for emulating the Minecraft commands and other necessary ones for
+ * use by a Bukkit implementation.
+ * <p>
+ */
+package org.bukkit.command.defaults;
+

paper-api/src/main/javadoc/org/bukkit/command/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Classes relating to handling specialized non-chat player input.
+ * <p>
+ */
+package org.bukkit.command;
+

paper-api/src/main/javadoc/org/bukkit/configuration/file/package-info.java

@@ -0,0 +1,8 @@
+/**
+ * Classes dedicated facilitating {@link 
+ * org.bukkit.configuration.Configuration configurations} to be read and
+ * stored on the filesystem.
+ * <p>
+ */
+package org.bukkit.configuration.file;
+

paper-api/src/main/javadoc/org/bukkit/configuration/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Classes dedicated to handling a plugin's runtime configuration.
+ * <p>
+ */
+package org.bukkit.configuration;
+

paper-api/src/main/javadoc/org/bukkit/configuration/serialization/package-info.java

@@ -0,0 +1,8 @@
+/**
+ * Classes dedicated to being able to perform serialization specialized for
+ * the Bukkit {@link org.bukkit.configuration.Configuration configuration}
+ * implementation.
+ * <p>
+ */
+package org.bukkit.configuration.serialization;
+

paper-api/src/main/javadoc/org/bukkit/conversations/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Classes dedicated to facilitate direct player-to-plugin communication.
+ * <p>
+ */
+package org.bukkit.conversations;
+

paper-api/src/main/javadoc/org/bukkit/enchantments/package-info.java

@@ -0,0 +1,8 @@
+/**
+ * Classes relating to the specialized enhancements to {@link
+ * org.bukkit.inventory.ItemStack item stacks}, as part of the {@link
+ * org.bukkit.inventory.meta.ItemMeta meta data}.
+ * <p>
+ */
+package org.bukkit.enchantments;
+

paper-api/src/main/javadoc/org/bukkit/entity/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Interfaces for non-voxel objects that can exist in a {@link
+ * org.bukkit.World world}, including all players, monsters, projectiles, etc.
+ * <p>
+ */
+package org.bukkit.entity;
+

paper-api/src/main/javadoc/org/bukkit/event/block/package-info.java

@@ -0,0 +1,8 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to when a {@link
+ * org.bukkit.block.Block block} is changed or interacts with the {@link
+ * org.bukkit.World world}.
+ * <p>
+ */
+package org.bukkit.event.block;
+

paper-api/src/main/javadoc/org/bukkit/event/enchantment/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * {@link org.bukkit.event.Event Events} triggered from an {@link
+ * org.bukkit.inventory.EnchantingInventory enchantment table}.
+ * <p>
+ */
+package org.bukkit.event.enchantment;
+

paper-api/src/main/javadoc/org/bukkit/event/entity/package-info.java

@@ -0,0 +1,8 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to {@link
+ * org.bukkit.entity.Entity entities}, excluding some directly referencing
+ * some more specific entity types.
+ * <p>
+ */
+package org.bukkit.event.entity;
+

paper-api/src/main/javadoc/org/bukkit/event/hanging/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to {@link
+ * org.bukkit.entity.Hanging entities that hang}.
+ * <p>
+ */
+package org.bukkit.event.hanging;
+

paper-api/src/main/javadoc/org/bukkit/event/inventory/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to {@link
+ * org.bukkit.inventory.Inventory inventory} manipulation.
+ * <p>
+ */
+package org.bukkit.event.inventory;
+

paper-api/src/main/javadoc/org/bukkit/event/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Classes dedicated to handling triggered code executions.
+ * <p>
+ */
+package org.bukkit.event;
+

paper-api/src/main/javadoc/org/bukkit/event/painting/package-info.java

@@ -0,0 +1,8 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to {@link
+ * org.bukkit.entity.Painting paintings}, but deprecated for more general
+ * {@link org.bukkit.event.hanging hanging} events.
+ * <p>
+ */
+package org.bukkit.event.painting;
+

paper-api/src/main/javadoc/org/bukkit/event/player/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to {@link
+ * org.bukkit.entity.Player players}.
+ * <p>
+ */
+package org.bukkit.event.player;
+

paper-api/src/main/javadoc/org/bukkit/event/server/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to programmatic state
+ * changes on the server.
+ * <p>
+ */
+package org.bukkit.event.server;
+

paper-api/src/main/javadoc/org/bukkit/event/vehicle/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to {@link
+ * org.bukkit.entity.Vehicle vehicular entities}.
+ * <p>
+ */
+package org.bukkit.event.vehicle;
+

paper-api/src/main/javadoc/org/bukkit/event/weather/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to weather.
+ * <p>
+ */
+package org.bukkit.event.weather;
+

paper-api/src/main/javadoc/org/bukkit/event/world/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * {@link org.bukkit.event.Event Events} triggered by various {@link
+ * org.bukkit.World world} states or changes.
+ * <p>
+ */
+package org.bukkit.event.world;
+

paper-api/src/main/javadoc/org/bukkit/generator/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Classes to facilitate {@link org.bukkit.World world} generation
+ * implementation.
+ * <p>
+ */
+package org.bukkit.generator;
+

paper-api/src/main/javadoc/org/bukkit/help/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Classes used to manipulate the default command and topic assistance system.
+ * <p>
+ */
+package org.bukkit.help;
+

paper-api/src/main/javadoc/org/bukkit/inventory/meta/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * The interfaces used when manipulating extra data can can be stored inside
+ * {@link org.bukkit.inventory.ItemStack item stacks}.
+ * <p>
+ */
+package org.bukkit.inventory.meta;
+

paper-api/src/main/javadoc/org/bukkit/inventory/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Classes involved in manipulating player inventories and item interactions.
+ * <p>
+ */
+package org.bukkit.inventory;
+

paper-api/src/main/javadoc/org/bukkit/map/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Classes to facilitate plugin handling of {@link org.bukkit.Material#MAP
+ * map} displays.
+ * <p>
+ */
+package org.bukkit.map;
+

paper-api/src/main/javadoc/org/bukkit/material/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Classes that represents various voxel types and states.
+ * <p>
+ */
+package org.bukkit.material;
+

paper-api/src/main/javadoc/org/bukkit/metadata/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Classes dedicated to providing a layer of plugin specified data on various
+ * Minecraft concepts.
+ * <p>
+ */
+package org.bukkit.metadata;
+

paper-api/src/main/javadoc/org/bukkit/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * More generalized classes in the API.
+ * <p>
+ */
+package org.bukkit;
+

paper-api/src/main/javadoc/org/bukkit/permissions/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Classes dedicated to providing binary state properties to players.
+ * <p>
+ */
+package org.bukkit.permissions;
+

paper-api/src/main/javadoc/org/bukkit/plugin/java/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Classes for handling {@link org.bukkit.plugin.Plugin plugins} written in
+ * java.
+ * <p>
+ */
+package org.bukkit.plugin.java;
+

paper-api/src/main/javadoc/org/bukkit/plugin/messaging/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Classes dedicated to specialized plugin to client protocols.
+ * <p>
+ */
+package org.bukkit.plugin.messaging;
+

paper-api/src/main/javadoc/org/bukkit/plugin/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Classes specifically relating to loading software modules at runtime.
+ * <p>
+ */
+package org.bukkit.plugin;
+

paper-api/src/main/javadoc/org/bukkit/potion/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Classes to represent various {@link org.bukkit.Material#POTION potion}
+ * properties and manipulation.
+ * <p>
+ */
+package org.bukkit.potion;
+

paper-api/src/main/javadoc/org/bukkit/scheduler/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Classes dedicated to letting {@link org.bukkit.plugin.Plugin plugins} run
+ * code at specific time intervals, including thread safety.
+ * <p>
+ */
+package org.bukkit.scheduler;
+

paper-api/src/main/javadoc/org/bukkit/util/noise/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Classes dedicated to facilitating deterministic noise.
+ * <p>
+ */
+package org.bukkit.util.noise;
+

paper-api/src/main/javadoc/org/bukkit/util/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Multi and single purpose classes to facilitate various programmatic
+ * concepts.
+ * <p>
+ */
+package org.bukkit.util;
+

paper-api/src/main/javadoc/org/bukkit/util/permissions/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Static methods for miscellaneous {@link org.bukkit.permissions.Permission
+ * permission} functionality.
+ * <p>
+ */
+package org.bukkit.util.permissions;
+

paper-api/src/main/javadoc/overview.html

@@ -0,0 +1,17 @@
+<body>
+    <p>Bukkit, the plugin development framework.</p>
+
+    <p>
+    The documentation is for developing plugins and is split into the
+    respective packages for each subject matter. This documentation does not
+    cover running a server, contributing code back to the project, or setting
+    up a workspace. Working knowledge of the Java language is a prerequisite
+    for developing plugins.
+    </p><p>
+    For basic plugin development, see the {@link org.bukkit.plugin plugin
+    package}. It covers the basic requirements of a plugin jar.
+    </p><p>
+    For handling events and triggered code, see the {@link org.bukkit.event
+    event package}.
+    </p>
+</body>