Javadoc improvements per checkstyle

By: md_5 <git@md-5.net>
2025-08-11 02:02:04 -07:00 · 2019-12-22 09:56:28 +11:00
parent d419ccca3f
commit d16413b877
96 changed files with 181 additions and 48 deletions
--- a/paper-api/src/main/java/org/bukkit/Color.java
+++ b/paper-api/src/main/java/org/bukkit/Color.java
@@ -234,6 +234,7 @@ public final class Color implements ConfigurationSerializable {
    }

    /**
+     * Gets the color as an RGB integer.
     *
     * @return An integer representation of this color, as 0xRRGGBB
     */
@@ -242,6 +243,7 @@ public final class Color implements ConfigurationSerializable {
    }

    /**
+     * Gets the color as an BGR integer.
     *
     * @return An integer representation of this color, as 0xBBGGRR
     */
--- a/paper-api/src/main/java/org/bukkit/FireworkEffect.java
+++ b/paper-api/src/main/java/org/bukkit/FireworkEffect.java
@@ -405,9 +405,7 @@ public final class FireworkEffect implements ConfigurationSerializable {

    @Override
    public int hashCode() {
-        /**
-         * TRUE and FALSE as per boolean.hashCode()
-         */
+        // TRUE and FALSE as per boolean.hashCode()
        final int PRIME = 31, TRUE = 1231, FALSE = 1237;
        int hash = 1;
        hash = hash * PRIME + (flicker ? TRUE : FALSE);
--- a/paper-api/src/main/java/org/bukkit/GameRule.java
+++ b/paper-api/src/main/java/org/bukkit/GameRule.java
@@ -12,6 +12,8 @@ import org.jetbrains.annotations.Nullable;
 * For more information please visit the
 * <a href="https://minecraft.gamepedia.com/Commands/gamerule">Minecraft
 * Wiki</a>
+ *
+ * @param <T> type of rule (Boolean or Integer)
 */
 public final class GameRule<T> {

--- a/paper-api/src/main/java/org/bukkit/Location.java
+++ b/paper-api/src/main/java/org/bukkit/Location.java
@@ -449,8 +449,8 @@ public class Location implements Cloneable, ConfigurationSerializable {
     * function overflows, which will be caused if the length is too long. Not
     * world-aware and orientation independent.
     *
-     * @see Vector
     * @return the magnitude
+     * @see Vector
     */
    public double length() {
        return Math.sqrt(NumberConversions.square(x) + NumberConversions.square(y) + NumberConversions.square(z));
@@ -460,8 +460,8 @@ public class Location implements Cloneable, ConfigurationSerializable {
     * Gets the magnitude of the location squared. Not world-aware and
     * orientation independent.
     *
-     * @see Vector
     * @return the magnitude
+     * @see Vector
     */
    public double lengthSquared() {
        return NumberConversions.square(x) + NumberConversions.square(y) + NumberConversions.square(z);
@@ -474,10 +474,10 @@ public class Location implements Cloneable, ConfigurationSerializable {
     * be returned if the inner result of the sqrt() function overflows, which
     * will be caused if the distance is too long.
     *
-     * @see Vector
     * @param o The other location
     * @return the distance
     * @throws IllegalArgumentException for differing worlds
+     * @see Vector
     */
    public double distance(@NotNull Location o) {
        return Math.sqrt(distanceSquared(o));
@@ -486,10 +486,10 @@ public class Location implements Cloneable, ConfigurationSerializable {
    /**
     * Get the squared distance between this location and another.
     *
-     * @see Vector
     * @param o The other location
     * @return the distance
     * @throws IllegalArgumentException for differing worlds
+     * @see Vector
     */
    public double distanceSquared(@NotNull Location o) {
        if (o == null) {
@@ -508,8 +508,8 @@ public class Location implements Cloneable, ConfigurationSerializable {
     * scalar. Not world-aware.
     *
     * @param m The factor
-     * @see Vector
     * @return the same location
+     * @see Vector
     */
    @NotNull
    public Location multiply(double m) {
@@ -522,8 +522,8 @@ public class Location implements Cloneable, ConfigurationSerializable {
    /**
     * Zero this location's components. Not world-aware.
     *
-     * @see Vector
     * @return the same location
+     * @see Vector
     */
    @NotNull
    public Location zero() {
--- a/paper-api/src/main/java/org/bukkit/advancement/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/advancement/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Classes relevant to advancements.
+ */
+package org.bukkit.advancement;
--- a/paper-api/src/main/java/org/bukkit/attribute/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/attribute/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Classes relevant to attributes.
+ */
+package org.bukkit.attribute;
--- a/paper-api/src/main/java/org/bukkit/block/Campfire.java
+++ b/paper-api/src/main/java/org/bukkit/block/Campfire.java
@@ -10,26 +10,23 @@ import org.jetbrains.annotations.Nullable;
 public interface Campfire extends TileState {

    /**
-     * @see Inventory#getSize()
-     *
     * @return The size of the inventory
+     * @see Inventory#getSize()
     */
    int getSize();

    /**
-     * @see Inventory#getItem(int)
-     *
     * @param index The index of the Slot's ItemStack to return
     * @return The ItemStack in the slot
+     * @see Inventory#getItem(int)
     */
    @Nullable
    ItemStack getItem(int index);

    /**
-     * @see Inventory#setItem(int, org.bukkit.inventory.ItemStack)
-     *
     * @param index The index where to put the ItemStack
     * @param item The ItemStack to set
+     * @see Inventory#setItem(int, org.bukkit.inventory.ItemStack)
     */
    void setItem(int index, @Nullable ItemStack item);

--- a/paper-api/src/main/java/org/bukkit/block/CreatureSpawner.java
+++ b/paper-api/src/main/java/org/bukkit/block/CreatureSpawner.java
@@ -78,8 +78,8 @@ public interface CreatureSpawner extends TileState {
    /**
     * Set the minimum spawn delay amount (in ticks).
     *
-     * @see #getMinSpawnDelay()
     * @param delay the minimum spawn delay amount
+     * @see #getMinSpawnDelay()
     */
    public void setMinSpawnDelay(int delay);

@@ -105,8 +105,8 @@ public interface CreatureSpawner extends TileState {
     * This value <b>must</b> be greater than 0, as well as greater than or
     * equal to {@link #getMinSpawnDelay()}
     *
-     * @see #getMaxSpawnDelay()
     * @param delay the new maximum spawn delay amount
+     * @see #getMaxSpawnDelay()
     */
    public void setMaxSpawnDelay(int delay);

@@ -195,8 +195,8 @@ public interface CreatureSpawner extends TileState {
     * Set the new spawn range.
     * <br>
     *
-     * @see #getSpawnRange()
     * @param spawnRange the new spawn range
+     * @see #getSpawnRange()
     */
    public void setSpawnRange(int spawnRange);
 }
--- a/paper-api/src/main/java/org/bukkit/block/banner/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/block/banner/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Classes relevant to banner blocks.
+ */
+package org.bukkit.block.banner;
--- a/paper-api/src/main/java/org/bukkit/block/data/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/block/data/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Generalized BlockData classes.
+ */
+package org.bukkit.block.data;
--- a/paper-api/src/main/java/org/bukkit/block/data/type/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/block/data/type/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Specific BlockData classes relevant to only a given block or set of blocks.
+ */
+package org.bukkit.block.data.type;
--- a/paper-api/src/main/java/org/bukkit/block/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/block/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Classes used to manipulate the voxels in a {@link org.bukkit.World world},
+ * including special states.
+ */
+package org.bukkit.block;
+
--- a/paper-api/src/main/java/org/bukkit/block/structure/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/block/structure/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Classes relevant to structure blocks.
+ */
+package org.bukkit.block.structure;
--- a/paper-api/src/main/java/org/bukkit/boss/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/boss/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Classes concerning the creation of boss bars that appear at the top of the
+ * player's screen.
+ */
+package org.bukkit.boss;
--- a/paper-api/src/main/java/org/bukkit/command/defaults/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/command/defaults/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Commands for emulating the Minecraft commands and other necessary ones for
+ * use by a Bukkit implementation.
+ */
+package org.bukkit.command.defaults;
+
--- a/paper-api/src/main/java/org/bukkit/command/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/command/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Classes relating to handling specialized non-chat player input.
+ */
+package org.bukkit.command;
+
--- a/paper-api/src/main/java/org/bukkit/configuration/file/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/configuration/file/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Classes dedicated to facilitating
+ * {@link org.bukkit.configuration.Configuration configurations} to be read and
+ * stored on the filesystem.
+ */
+package org.bukkit.configuration.file;
--- a/paper-api/src/main/java/org/bukkit/configuration/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/configuration/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Classes dedicated to handling a plugin's runtime configuration.
+ */
+package org.bukkit.configuration;
+
--- a/paper-api/src/main/java/org/bukkit/configuration/serialization/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/configuration/serialization/package-info.java
@@ -0,0 +1,7 @@
+/**
+ * Classes dedicated to being able to perform serialization specialized for
+ * the Bukkit {@link org.bukkit.configuration.Configuration configuration}
+ * implementation.
+ */
+package org.bukkit.configuration.serialization;
+
--- a/paper-api/src/main/java/org/bukkit/conversations/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/conversations/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Classes dedicated to facilitate direct player-to-plugin communication.
+ */
+package org.bukkit.conversations;
+
--- a/paper-api/src/main/java/org/bukkit/enchantments/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/enchantments/package-info.java
@@ -0,0 +1,7 @@
+/**
+ * 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}.
+ */
+package org.bukkit.enchantments;
+
--- a/paper-api/src/main/java/org/bukkit/entity/EntityType.java
+++ b/paper-api/src/main/java/org/bukkit/entity/EntityType.java
@@ -325,6 +325,7 @@ public enum EntityType implements Keyed {
    }

    /**
+     * Gets the entity type name.
     *
     * @return the entity type's name
     * @deprecated Magic value
@@ -349,6 +350,7 @@ public enum EntityType implements Keyed {
    }

    /**
+     * Gets the entity type id.
     *
     * @return the raw type id
     * @deprecated Magic value
@@ -359,6 +361,7 @@ public enum EntityType implements Keyed {
    }

    /**
+     * Gets an entity type from its name.
     *
     * @param name the entity type's name
     * @return the matching entity type or null
@@ -375,6 +378,7 @@ public enum EntityType implements Keyed {
    }

    /**
+     * Gets an entity from its id.
     *
     * @param id the raw type id
     * @return the matching entity type or null
--- a/paper-api/src/main/java/org/bukkit/entity/memory/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/entity/memory/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Classes concerning an entity's persistent memory.
+ *
+ * Currently only relevant for Villagers.
+ */
+package org.bukkit.entity.memory;
--- a/paper-api/src/main/java/org/bukkit/entity/minecart/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/entity/minecart/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Interfaces for various {@link org.bukkit.entity.Minecart} types.
+ */
+package org.bukkit.entity.minecart;
+
--- a/paper-api/src/main/java/org/bukkit/entity/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/entity/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Interfaces for non-voxel objects that can exist in a {@link
+ * org.bukkit.World world}, including all players, monsters, projectiles, etc.
+ */
+package org.bukkit.entity;
+
--- a/paper-api/src/main/java/org/bukkit/event/block/BlockCanBuildEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/block/BlockCanBuildEvent.java
@@ -32,7 +32,6 @@ public class BlockCanBuildEvent extends BlockEvent {
    }

    /**
-     *
     * @param block the block involved in this event
     * @param player the player placing the block
     * @param type the id of the block to place
--- a/paper-api/src/main/java/org/bukkit/event/block/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/event/block/package-info.java
@@ -0,0 +1,7 @@
+/**
+ * {@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}.
+ */
+package org.bukkit.event.block;
+
--- a/paper-api/src/main/java/org/bukkit/event/enchantment/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/event/enchantment/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * {@link org.bukkit.event.Event Events} triggered from an {@link
+ * org.bukkit.inventory.EnchantingInventory enchantment table}.
+ */
+package org.bukkit.event.enchantment;
+
--- a/paper-api/src/main/java/org/bukkit/event/entity/EntityDamageEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityDamageEvent.java
@@ -77,11 +77,11 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
     *
     * @param type the damage modifier
     * @param damage the scalar value of the damage's modifier
-     * @see #getFinalDamage()
     * @throws IllegalArgumentException if type is null
     * @throws UnsupportedOperationException if the caller does not support
     *     the particular DamageModifier, or to rephrase, when {@link
     *     #isApplicable(DamageModifier)} returns false
+     * @see #getFinalDamage()
     */
    public void setDamage(@NotNull DamageModifier type, double damage) throws IllegalArgumentException, UnsupportedOperationException {
        if (!modifiers.containsKey(type)) {
--- a/paper-api/src/main/java/org/bukkit/event/entity/VillagerReplenishTradeEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/entity/VillagerReplenishTradeEvent.java
@@ -58,8 +58,8 @@ public class VillagerReplenishTradeEvent extends EntityEvent implements Cancella
    /**
     * Set the bonus uses added.
     *
-     * @see VillagerReplenishTradeEvent#getBonus()
     * @param bonus the extra uses added
+     * @see VillagerReplenishTradeEvent#getBonus()
     */
    public void setBonus(int bonus) {
        this.bonus = bonus;
--- a/paper-api/src/main/java/org/bukkit/event/entity/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/event/entity/package-info.java
@@ -0,0 +1,7 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to {@link
+ * org.bukkit.entity.Entity entities}, excluding some directly referencing
+ * some more specific entity types.
+ */
+package org.bukkit.event.entity;
+
--- a/paper-api/src/main/java/org/bukkit/event/hanging/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/event/hanging/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to {@link
+ * org.bukkit.entity.Hanging entities that hang}.
+ */
+package org.bukkit.event.hanging;
+
--- a/paper-api/src/main/java/org/bukkit/event/inventory/InventoryInteractEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/inventory/InventoryInteractEvent.java
@@ -30,8 +30,8 @@ public abstract class InventoryInteractEvent extends InventoryEvent implements C
     * Sets the result of this event. This will change whether or not this
     * event is considered cancelled.
     *
-     * @see #isCancelled()
     * @param newResult the new {@link org.bukkit.event.Event.Result} for this event
+     * @see #isCancelled()
     */
    public void setResult(@NotNull Result newResult) {
        result = newResult;
--- a/paper-api/src/main/java/org/bukkit/event/inventory/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/event/inventory/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to {@link
+ * org.bukkit.inventory.Inventory inventory} manipulation.
+ */
+package org.bukkit.event.inventory;
+
--- a/paper-api/src/main/java/org/bukkit/event/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/event/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Classes dedicated to handling triggered code executions.
+ */
+package org.bukkit.event;
+
--- a/paper-api/src/main/java/org/bukkit/event/player/AsyncPlayerChatEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/player/AsyncPlayerChatEvent.java
@@ -31,7 +31,6 @@ public class AsyncPlayerChatEvent extends PlayerEvent implements Cancellable {
    private final Set<Player> recipients;

    /**
-     *
     * @param async This changes the event to a synchronous state.
     * @param who the chat sender
     * @param message the message sent
--- a/paper-api/src/main/java/org/bukkit/event/player/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/event/player/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to {@link
+ * org.bukkit.entity.Player players}.
+ */
+package org.bukkit.event.player;
+
--- a/paper-api/src/main/java/org/bukkit/event/raid/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/event/raid/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Events related to raids.
+ */
+package org.bukkit.event.raid;
--- a/paper-api/src/main/java/org/bukkit/event/server/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/event/server/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to programmatic state
+ * changes on the server.
+ */
+package org.bukkit.event.server;
+
--- a/paper-api/src/main/java/org/bukkit/event/vehicle/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/event/vehicle/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to {@link
+ * org.bukkit.entity.Vehicle vehicular entities}.
+ */
+package org.bukkit.event.vehicle;
+
--- a/paper-api/src/main/java/org/bukkit/event/weather/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/event/weather/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * {@link org.bukkit.event.Event Events} relating to weather.
+ */
+package org.bukkit.event.weather;
+
--- a/paper-api/src/main/java/org/bukkit/event/world/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/event/world/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * {@link org.bukkit.event.Event Events} triggered by various {@link
+ * org.bukkit.World world} states or changes.
+ */
+package org.bukkit.event.world;
+
--- a/paper-api/src/main/java/org/bukkit/generator/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/generator/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Classes to facilitate {@link org.bukkit.World world} generation
+ * implementation.
+ */
+package org.bukkit.generator;
+
--- a/paper-api/src/main/java/org/bukkit/help/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/help/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Classes used to manipulate the default command and topic assistance system.
+ */
+package org.bukkit.help;
+
--- a/paper-api/src/main/java/org/bukkit/inventory/InventoryView.java
+++ b/paper-api/src/main/java/org/bukkit/inventory/InventoryView.java
@@ -116,6 +116,7 @@ public abstract class InventoryView {
        }

        /**
+         * Gets the id of this view.
         *
         * @return the id of this view
         * @deprecated Magic value
@@ -264,7 +265,7 @@ public abstract class InventoryView {
        // Player crafting slots are indexed differently. The matrix is caught by the first return.
        // Creative mode is the same, except that you can't see the crafting slots (but the IDs are still used)
        if (getType() == InventoryType.CRAFTING || getType() == InventoryType.CREATIVE) {
-            /**
+            /*
             * Raw Slots:
             *
             * 5             1  2     0
@@ -277,7 +278,7 @@ public abstract class InventoryView {
             * 36 37 38 39 40 41 42 43 44
             */

-            /**
+            /*
             * Converted Slots:
             *
             * 39             1  2     0
--- a/paper-api/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
+++ b/paper-api/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
@@ -351,10 +351,10 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
     * @param modifier the {@link AttributeModifier} to remove
     * @return if any attribute modifiers were remove
     *
-     * @see AttributeModifier#getUniqueId()
-     *
     * @throws NullPointerException if the Attribute is null
     * @throws NullPointerException if the AttributeModifier is null
+     *
+     * @see AttributeModifier#getUniqueId()
     */
    boolean removeAttributeModifier(@NotNull Attribute attribute, @NotNull AttributeModifier modifier);

@@ -380,7 +380,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
     * Internal use only! Do not use under any circumstances!
     *
     * @param version version
-     * @deprecated
+     * @deprecated internal use only
     */
    @Deprecated
    void setVersion(int version);
--- a/paper-api/src/main/java/org/bukkit/inventory/meta/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/inventory/meta/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * The interfaces used when manipulating extra data can can be stored inside
+ * {@link org.bukkit.inventory.ItemStack item stacks}.
+ */
+package org.bukkit.inventory.meta;
+
--- a/paper-api/src/main/java/org/bukkit/inventory/meta/tags/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/inventory/meta/tags/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Classes that allow attaching custom data to items.
+ */
+package org.bukkit.inventory.meta.tags;
--- a/paper-api/src/main/java/org/bukkit/inventory/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/inventory/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Classes involved in manipulating player inventories and item interactions.
+ */
+package org.bukkit.inventory;
+
--- a/paper-api/src/main/java/org/bukkit/loot/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/loot/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Classes relevant to loot table manipulation and generation.
+ */
+package org.bukkit.loot;
--- a/paper-api/src/main/java/org/bukkit/map/MapCursor.java
+++ b/paper-api/src/main/java/org/bukkit/map/MapCursor.java
@@ -261,6 +261,7 @@ public final class MapCursor {
        }

        /**
+         * Gets the internal value of the cursor.
         *
         * @return the value
         * @deprecated Magic value
@@ -271,6 +272,7 @@ public final class MapCursor {
        }

        /**
+         * Get a cursor by its internal value.
         *
         * @param value the value
         * @return the matching type
--- a/paper-api/src/main/java/org/bukkit/map/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/map/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Classes to facilitate plugin handling of {@link org.bukkit.Material#MAP
+ * map} displays.
+ */
+package org.bukkit.map;
+
--- a/paper-api/src/main/java/org/bukkit/material/Banner.java
+++ b/paper-api/src/main/java/org/bukkit/material/Banner.java
@@ -19,7 +19,6 @@ public class Banner extends MaterialData implements Attachable {
    }

    /**
-     *
     * @param type the type
     * @param data the raw data value
     * @deprecated Magic value
--- a/paper-api/src/main/java/org/bukkit/material/Cauldron.java
+++ b/paper-api/src/main/java/org/bukkit/material/Cauldron.java
@@ -18,7 +18,6 @@ public class Cauldron extends MaterialData {
    }

    /**
-     *
     * @param type the type
     * @param data the raw data value
     * @deprecated Magic value
@@ -29,7 +28,6 @@ public class Cauldron extends MaterialData {
    }

    /**
-     *
     * @param data the raw data value
     * @deprecated Magic value
     */
--- a/paper-api/src/main/java/org/bukkit/material/ExtendedRails.java
+++ b/paper-api/src/main/java/org/bukkit/material/ExtendedRails.java
@@ -33,6 +33,7 @@ public class ExtendedRails extends Rails {
    }

    /**
+     * {@inheritDoc}
     *
     * @deprecated Magic value
     */
--- a/paper-api/src/main/java/org/bukkit/material/Step.java
+++ b/paper-api/src/main/java/org/bukkit/material/Step.java
@@ -74,16 +74,17 @@ public class Step extends TexturedMaterial {
    }

    /**
+     * {@inheritDoc}
     *
     * @deprecated Magic value
     */
-    @Deprecated
    @Override
    protected int getTextureIndex() {
        return getData() & 0x7;
    }

    /**
+     * {@inheritDoc}
     *
     * @deprecated Magic value
     */
--- a/paper-api/src/main/java/org/bukkit/material/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/material/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Classes that represents various voxel types and states.
+ */
+package org.bukkit.material;
+
--- a/paper-api/src/main/java/org/bukkit/material/types/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/material/types/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Classes relevant to specific material types.
+ */
+package org.bukkit.material.types;
--- a/paper-api/src/main/java/org/bukkit/metadata/MetadataStoreBase.java
+++ b/paper-api/src/main/java/org/bukkit/metadata/MetadataStoreBase.java
@@ -32,9 +32,9 @@ public abstract class MetadataStoreBase<T> {
     * @param subject The object receiving the metadata.
     * @param metadataKey A unique key to identify this metadata.
     * @param newMetadataValue The metadata value to apply.
-     * @see MetadataStore#setMetadata(Object, String, MetadataValue)
     * @throws IllegalArgumentException If value is null, or the owning plugin
     *     is null
+     * @see MetadataStore#setMetadata(Object, String, MetadataValue)
     */
    public synchronized void setMetadata(@NotNull T subject, @NotNull String metadataKey, @NotNull MetadataValue newMetadataValue) {
        Validate.notNull(newMetadataValue, "Value cannot be null");
@@ -90,9 +90,9 @@ public abstract class MetadataStoreBase<T> {
     * @param metadataKey the unique metadata key identifying the metadata to
     *     remove.
     * @param owningPlugin the plugin attempting to remove a metadata item.
+     * @throws IllegalArgumentException If plugin is null
     * @see MetadataStore#removeMetadata(Object, String,
     *     org.bukkit.plugin.Plugin)
-     * @throws IllegalArgumentException If plugin is null
     */
    public synchronized void removeMetadata(@NotNull T subject, @NotNull String metadataKey, @NotNull Plugin owningPlugin) {
        Validate.notNull(owningPlugin, "Plugin cannot be null");
@@ -114,8 +114,8 @@ public abstract class MetadataStoreBase<T> {
     * be recalculated the next time it is accessed.
     *
     * @param owningPlugin the plugin requesting the invalidation.
-     * @see MetadataStore#invalidateAll(org.bukkit.plugin.Plugin)
     * @throws IllegalArgumentException If plugin is null
+     * @see MetadataStore#invalidateAll(org.bukkit.plugin.Plugin)
     */
    public synchronized void invalidateAll(@NotNull Plugin owningPlugin) {
        Validate.notNull(owningPlugin, "Plugin cannot be null");
--- a/paper-api/src/main/java/org/bukkit/metadata/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/metadata/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Classes dedicated to providing a layer of plugin specified data on various
+ * Minecraft concepts.
+ */
+package org.bukkit.metadata;
+
--- a/paper-api/src/main/java/org/bukkit/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * More generalized classes in the API.
+ */
+package org.bukkit;
+
--- a/paper-api/src/main/java/org/bukkit/permissions/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/permissions/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Classes dedicated to providing binary state properties to players.
+ */
+package org.bukkit.permissions;
+
--- a/paper-api/src/main/java/org/bukkit/persistence/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/persistence/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Classes that allow attaching persistent data to various objects.
+ */
+package org.bukkit.persistence;
--- a/paper-api/src/main/java/org/bukkit/plugin/java/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/plugin/java/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Classes for handling {@link org.bukkit.plugin.Plugin plugins} written in
+ * java.
+ */
+package org.bukkit.plugin.java;
+
--- a/paper-api/src/main/java/org/bukkit/plugin/messaging/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/plugin/messaging/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Classes dedicated to specialized plugin to client protocols.
+ */
+package org.bukkit.plugin.messaging;
+
--- a/paper-api/src/main/java/org/bukkit/plugin/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/plugin/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Classes specifically relating to loading software modules at runtime.
+ */
+package org.bukkit.plugin;
+
--- a/paper-api/src/main/java/org/bukkit/potion/Potion.java
+++ b/paper-api/src/main/java/org/bukkit/potion/Potion.java
@@ -117,8 +117,8 @@ public class Potion {
     * Applies the effects that would be applied by this potion to the given
     * {@link LivingEntity}.
     *
-     * @see LivingEntity#addPotionEffects(Collection)
     * @param to The entity to apply the effects to
+     * @see LivingEntity#addPotionEffects(Collection)
     */
    public void apply(@NotNull LivingEntity to) {
        Validate.notNull(to, "entity cannot be null");
@@ -281,6 +281,7 @@ public class Potion {
    private static final int TIER_SHIFT = 5;

    /**
+     * Gets the potion from its damage value.
     *
     * @param damage the damage value
     * @return the produced potion
@@ -382,6 +383,7 @@ public class Potion {
    }

    /**
+     * Gets the potion from its name id.
     *
     * @return the name id
     * @deprecated Non-functional
--- a/paper-api/src/main/java/org/bukkit/potion/PotionEffect.java
+++ b/paper-api/src/main/java/org/bukkit/potion/PotionEffect.java
@@ -144,9 +144,9 @@ public class PotionEffect implements ConfigurationSerializable {
     * Attempts to add the effect represented by this object to the given
     * {@link LivingEntity}.
     *
-     * @see LivingEntity#addPotionEffect(PotionEffect)
     * @param entity The entity to add this effect to
     * @return Whether the effect could be added
+     * @see LivingEntity#addPotionEffect(PotionEffect)
     */
    public boolean apply(@NotNull LivingEntity entity) {
        return entity.addPotionEffect(this);
--- a/paper-api/src/main/java/org/bukkit/potion/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/potion/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Classes to represent various {@link org.bukkit.Material#POTION potion}
+ * properties and manipulation.
+ */
+package org.bukkit.potion;
+
--- a/paper-api/src/main/java/org/bukkit/projectiles/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/projectiles/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Classes to represent the source of a projectile
+ */
+package org.bukkit.projectiles;
+
--- a/paper-api/src/main/java/org/bukkit/scheduler/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/scheduler/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Classes dedicated to letting {@link org.bukkit.plugin.Plugin plugins} run
+ * code at specific time intervals, including thread safety.
+ */
+package org.bukkit.scheduler;
+
--- a/paper-api/src/main/java/org/bukkit/scoreboard/Scoreboard.java
+++ b/paper-api/src/main/java/org/bukkit/scoreboard/Scoreboard.java
@@ -85,6 +85,7 @@ public interface Scoreboard {
     *
     * @param criteria Criteria to search by
     * @return an immutable set of Objectives using the specified Criteria
+     * @throws IllegalArgumentException if criteria is null
     */
    @NotNull
    Set<Objective> getObjectivesByCriteria(@NotNull String criteria) throws IllegalArgumentException;
--- a/paper-api/src/main/java/org/bukkit/scoreboard/Team.java
+++ b/paper-api/src/main/java/org/bukkit/scoreboard/Team.java
@@ -241,9 +241,9 @@ public interface Team {
     * Removes the entry from this team.
     *
     * @param entry the entry to remove
+     * @return if the entry was a part of this team
     * @throws IllegalArgumentException if entry is null
     * @throws IllegalStateException if this team has been unregistered
-     * @return if the entry was a part of this team
     */
    boolean removeEntry(@NotNull String entry) throws IllegalStateException, IllegalArgumentException;

--- a/paper-api/src/main/java/org/bukkit/scoreboard/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/scoreboard/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Interfaces used to manage the client side score display system.
+ */
+package org.bukkit.scoreboard;
+
--- a/paper-api/src/main/java/org/bukkit/util/io/BukkitObjectInputStream.java
+++ b/paper-api/src/main/java/org/bukkit/util/io/BukkitObjectInputStream.java
@@ -20,7 +20,9 @@ public class BukkitObjectInputStream extends ObjectInputStream {
    /**
     * Constructor provided to mirror super functionality.
     *
-     * @throws IOException if an I/O error occurs while reading stream heade
+     * @throws IOException if an I/O error occurs while creating this stream
+     * @throws SecurityException if a security manager exists and denies
+     * enabling subclassing
     * @see ObjectInputStream#ObjectInputStream()
     */
    protected BukkitObjectInputStream() throws IOException, SecurityException {
--- a/paper-api/src/main/java/org/bukkit/util/io/BukkitObjectOutputStream.java
+++ b/paper-api/src/main/java/org/bukkit/util/io/BukkitObjectOutputStream.java
@@ -20,7 +20,9 @@ public class BukkitObjectOutputStream extends ObjectOutputStream {
    /**
     * Constructor provided to mirror super functionality.
     *
-     * @throws IOException if an I/O error occurs while writing stream header
+     * @throws IOException if an I/O error occurs while creating this stream
+     * @throws SecurityException if a security manager exists and denies
+     * enabling subclassing
     * @see ObjectOutputStream#ObjectOutputStream()
     */
    protected BukkitObjectOutputStream() throws IOException, SecurityException {
--- a/paper-api/src/main/java/org/bukkit/util/io/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/util/io/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Classes used to facilitate stream processing for specific Bukkit concepts.
+ */
+package org.bukkit.util.io;
+
--- a/paper-api/src/main/java/org/bukkit/util/noise/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/util/noise/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Classes dedicated to facilitating deterministic noise.
+ */
+package org.bukkit.util.noise;
+
--- a/paper-api/src/main/java/org/bukkit/util/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/util/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Multi and single purpose classes to facilitate various programmatic
+ * concepts.
+ */
+package org.bukkit.util;
+
--- a/paper-api/src/main/java/org/bukkit/util/permissions/package-info.java
+++ b/paper-api/src/main/java/org/bukkit/util/permissions/package-info.java
@@ -0,0 +1,6 @@
+/**
+ * Static methods for miscellaneous {@link org.bukkit.permissions.Permission
+ * permission} functionality.
+ */
+package org.bukkit.util.permissions;
+