OpenSource/PaperMC
OpenSource/PaperMC
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2024-12-30 16:19:03 +01:00
Code Issues Projects Releases Packages Wiki Activity
PaperMC/patches/api/Fix-upstream-javadocs.patch

448 lines
18 KiB
Diff
Raw Blame History

From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
From: Zach Brown <1254957+zachbr@users.noreply.github.com>
Date: Sat, 10 Jun 2017 16:59:40 -0500
Subject: [PATCH] Fix upstream javadocs
Upstream still refuses to use Java 8 with the API so they are likely unaware these are even issues.
diff --git a/src/main/java/org/bukkit/Bukkit.java b/src/main/java/org/bukkit/Bukkit.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Bukkit.java
+++ b/src/main/java/org/bukkit/Bukkit.java
@@ -0,0 +0,0 @@ public final class Bukkit {
/**
* Gets every player that has ever played on this server.
+ * <p>
+ * <b>This method can be expensive as it loads all the player data files from the disk.</b>
*
* @return an array containing all previous players
*/
diff --git a/src/main/java/org/bukkit/Server.java b/src/main/java/org/bukkit/Server.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Server.java
+++ b/src/main/java/org/bukkit/Server.java
@@ -0,0 +0,0 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
* </ul>
* <p>
* <b>Note:</b> If set to 0, {@link SpawnCategory} mobs spawning will be disabled.
- * <p>
- * Minecraft default: 1.
- * <br>
- * <b>Note: </b> the {@link SpawnCategory#MISC} are not consider.
*
* @param spawnCategory the category of spawn
* @return the default ticks per {@link SpawnCategory} mobs spawn value
+ * @throws IllegalArgumentException if the category is {@link SpawnCategory#MISC}
*/
public int getTicksPerSpawns(@NotNull SpawnCategory spawnCategory);
@@ -0,0 +0,0 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
/**
* Gets every player that has ever played on this server.
+ * <p>
+ * <b>This method can be expensive as it loads all the player data files from the disk.</b>
*
* @return an array containing all previous players
*/
diff --git a/src/main/java/org/bukkit/block/Bed.java b/src/main/java/org/bukkit/block/Bed.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/block/Bed.java
+++ b/src/main/java/org/bukkit/block/Bed.java
@@ -0,0 +0,0 @@ import org.bukkit.material.Colorable;
/**
* Represents a captured state of a bed.
- * @deprecated does not provide useful information beyond the material itself
*/
-@Deprecated
-public interface Bed extends TileState, Colorable { }
+// Paper start
+// @Deprecated
+public interface Bed extends TileState, Colorable {
+
+ @Override
+ @org.jetbrains.annotations.NotNull org.bukkit.DyeColor getColor();
+
+ /**
+ * <b>Unsupported</b>
+ *
+ * @throws UnsupportedOperationException not supported, set the block type
+ */
+ @Override
+ @org.jetbrains.annotations.Contract("_ -> fail")
+ @Deprecated(forRemoval = true)
+ void setColor(@org.bukkit.UndefinedNullability("not supported") org.bukkit.DyeColor color);
+// Paper end
+}
diff --git a/src/main/java/org/bukkit/entity/ArmorStand.java b/src/main/java/org/bukkit/entity/ArmorStand.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/ArmorStand.java
+++ b/src/main/java/org/bukkit/entity/ArmorStand.java
@@ -0,0 +0,0 @@ public interface ArmorStand extends LivingEntity {
* @param move {@code true} if this armour stand can move, {@code false} otherwise
*/
void setCanMove(boolean move);
+
+ @Override
+ org.bukkit.inventory.@NotNull EntityEquipment getEquipment();
// Paper end
}
diff --git a/src/main/java/org/bukkit/entity/HumanEntity.java b/src/main/java/org/bukkit/entity/HumanEntity.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/HumanEntity.java
+++ b/src/main/java/org/bukkit/entity/HumanEntity.java
@@ -0,0 +0,0 @@ import org.jetbrains.annotations.Nullable;
*/
public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder {
+ // Paper start
+ @Override
+ org.bukkit.inventory.@NotNull EntityEquipment getEquipment();
+ // Paper end
+
/**
* Returns the name of this player
*
diff --git a/src/main/java/org/bukkit/entity/Mob.java b/src/main/java/org/bukkit/entity/Mob.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/Mob.java
+++ b/src/main/java/org/bukkit/entity/Mob.java
@@ -0,0 +0,0 @@ import org.jetbrains.annotations.Nullable;
*/
public interface Mob extends LivingEntity, Lootable {
+ // Paper start
+ @Override
+ org.bukkit.inventory.@org.jetbrains.annotations.NotNull EntityEquipment getEquipment();
+ // Paper end
/**
* Instructs this Mob to set the specified LivingEntity as its target.
* <p>
diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/Player.java
+++ b/src/main/java/org/bukkit/entity/Player.java
@@ -0,0 +0,0 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
/**
* Saves the players current location, health, inventory, motion, and
- * other information into the username.dat file, in the world/player
- * folder
+ * other information into the &lt;uuid&gt;.dat file, in the
+ * &lt;level-name&gt;/playerdata/ folder.
*/
public void saveData();
/**
* Loads the players current location, health, inventory, motion, and
- * other information from the username.dat file, in the world/player
- * folder.
+ * other information from the &lt;uuid&gt;.dat file, in the
+ * &lt;level-name&gt;/playerdata/ folder.
* <p>
* Note: This will overwrite the players current inventory, health,
* motion, etc, with the state from the saved dat file.
@@ -0,0 +0,0 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
*
* Use supplied alternative character to the section symbol to represent legacy color codes.
*
- * @param alternateChar Alternate symbol such as '&'
+ * @param alternateChar Alternate symbol such as '&amp;'
* @param message The message to send
* @deprecated use {@link #sendActionBar(Component)}
*/
diff --git a/src/main/java/org/bukkit/entity/Slime.java b/src/main/java/org/bukkit/entity/Slime.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/Slime.java
+++ b/src/main/java/org/bukkit/entity/Slime.java
@@ -0,0 +0,0 @@ public interface Slime extends Mob {
public int getSize();
/**
+ * Setting the size of the slime (regardless of previous size)
+ * will set the following attributes:
+ * <ul>
+ * <li>{@link org.bukkit.attribute.Attribute#GENERIC_MAX_HEALTH}</li>
+ * <li>{@link org.bukkit.attribute.Attribute#GENERIC_MOVEMENT_SPEED}</li>
+ * <li>{@link org.bukkit.attribute.Attribute#GENERIC_ATTACK_DAMAGE}</li>
+ * </ul>
+ * to their per-size defaults and heal the
+ * slime to its max health (assuming it's alive).
+ *
* @param sz The new size of the slime.
*/
public void setSize(int sz);
diff --git a/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java b/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
+++ b/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
@@ -0,0 +0,0 @@ public class CreatureSpawnEvent extends EntitySpawnEvent {
*/
SHEARED,
/**
- * When eg an effect cloud is spawned as a result of a creeper exploding
+ * When an entity is spawned as a result of an explosion. Like an area effect cloud from
+ * a creeper or a dragon fireball.
*/
EXPLOSION,
/**
diff --git a/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java b/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java
@@ -0,0 +0,0 @@ public class EntityRegainHealthEvent extends EntityEvent implements Cancellable
*/
SATIATED,
/**
- * When a player regains health from eating consumables
+ * When an animal regains health from eating consumables
*/
EATING,
/**
diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
+++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
@@ -0,0 +0,0 @@ public interface EntityEquipment {
public ItemStack getItem(@NotNull EquipmentSlot slot);
/**
- * Gets a copy of the item the entity is currently holding
+ * Gets the item the entity is currently holding
* in their main hand.
*
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player,
+ * or it's an empty stack (has AIR as its type).
+ * For non-empty stacks from players, this returns a live mirror. You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getItemInMainHand(); // will return a mirror
+ * } else {
+ * equipment.getItemInMainHand(); // will return a copy
+ * }
+ * }</pre>
+ *
* @return the currently held item
*/
@NotNull
@@ -0,0 +0,0 @@ public interface EntityEquipment {
void setItemInMainHand(@Nullable ItemStack item, boolean silent);
/**
- * Gets a copy of the item the entity is currently holding
+ * Gets the item the entity is currently holding
* in their off hand.
*
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player,
+ * or it's an empty stack (has AIR as its type).
+ * For non-empty stacks from players, this returns a live mirror. You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getItemInOffHand(); // will return a mirror
+ * } else {
+ * equipment.getItemInOffHand(); // will return a copy
+ * }
+ * }</pre>
+ *
* @return the currently held item
*/
@NotNull
@@ -0,0 +0,0 @@ public interface EntityEquipment {
void setItemInOffHand(@Nullable ItemStack item, boolean silent);
/**
- * Gets a copy of the item the entity is currently holding
+ * Gets the item the entity is currently holding
+ *
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player,
+ * or it's an empty stack (has AIR as its type).
+ * For non-empty stacks from players, this returns a live mirror. You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getItemInHand(); // will return a mirror
+ * } else {
+ * equipment.getItemInHand(); // will return a copy
+ * }
+ * }</pre>
*
* @return the currently held item
* @see #getItemInMainHand()
@@ -0,0 +0,0 @@ public interface EntityEquipment {
void setItemInHand(@Nullable ItemStack stack);
/**
- * Gets a copy of the helmet currently being worn by the entity
+ * Gets the helmet currently being worn by the entity
+ *
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player.
+ * For stacks from players, this returns a live mirror (or null). You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getItemInHand(); // will return a mirror
+ * } else {
+ * equipment.getItemInHand(); // will return a copy
+ * }
+ * }</pre>
*
* @return The helmet being worn
*/
- @Nullable
+ @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getHelmet();
/**
@@ -0,0 +0,0 @@ public interface EntityEquipment {
void setHelmet(@Nullable ItemStack helmet, boolean silent);
/**
- * Gets a copy of the chest plate currently being worn by the entity
+ * Gets the chest plate currently being worn by the entity
+ *
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player.
+ * For stacks from players, this returns a live mirror (or null). You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getChestplate(); // will return a mirror
+ * } else {
+ * equipment.getChestplate(); // will return a copy
+ * }
+ * }</pre>
*
* @return The chest plate being worn
*/
- @Nullable
+ @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getChestplate();
/**
@@ -0,0 +0,0 @@ public interface EntityEquipment {
void setChestplate(@Nullable ItemStack chestplate, boolean silent);
/**
- * Gets a copy of the leggings currently being worn by the entity
+ * Gets the leggings currently being worn by the entity
+ *
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player.
+ * For stacks from players, this returns a live mirror (or null). You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getLeggings(); // will return a mirror
+ * } else {
+ * equipment.getLeggings(); // will return a copy
+ * }
+ * }</pre>
*
* @return The leggings being worn
*/
- @Nullable
+ @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getLeggings();
/**
@@ -0,0 +0,0 @@ public interface EntityEquipment {
void setLeggings(@Nullable ItemStack leggings, boolean silent);
/**
- * Gets a copy of the boots currently being worn by the entity
+ * Gets the boots currently being worn by the entity
+ *
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player.
+ * For stacks from players, this returns a live mirror (or null). You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getBoots(); // will return a mirror
+ * } else {
+ * equipment.getBoots(); // will return a copy
+ * }
+ * }</pre>
*
* @return The boots being worn
*/
- @Nullable
+ @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getBoots();
/**
@@ -0,0 +0,0 @@ public interface EntityEquipment {
void setBoots(@Nullable ItemStack boots, boolean silent);
/**
- * Gets a copy of all worn armor
+ * Gets all worn armor
+ *
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player,
+ * or it's an empty stack (has AIR as its type).
+ * For non-empty stacks from players, this returns a live mirror. You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getArmorContents(); // will return an array of mirror
+ * } else {
+ * equipment.getArmorContents(); // will return an array of copies
+ * }
+ * }</pre>
*
* @return The array of worn armor. Individual items may be null.
*/
- @NotNull
- ItemStack[] getArmorContents();
+ @org.bukkit.UndefinedNullability("not null elements for entities, nullable elements for players") ItemStack @NotNull [] getArmorContents(); // Paper
/**
* Sets the entities armor to the provided array of ItemStacks
diff --git a/src/main/java/org/bukkit/inventory/PlayerInventory.java b/src/main/java/org/bukkit/inventory/PlayerInventory.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
+++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java
@@ -0,0 +0,0 @@ public interface PlayerInventory extends Inventory {
public void setBoots(@Nullable ItemStack boots);
/**
- * Gets a copy of the item the player is currently holding
+ * Gets the item the player is currently holding
* in their main hand.
*
* @return the currently held item
@@ -0,0 +0,0 @@ public interface PlayerInventory extends Inventory {
void setItemInMainHand(@Nullable ItemStack item);
/**
- * Gets a copy of the item the player is currently holding
+ * Gets the item the player is currently holding
* in their off hand.
*
* @return the currently held item
@@ -0,0 +0,0 @@ public interface PlayerInventory extends Inventory {
void setItemInOffHand(@Nullable ItemStack item);
/**
- * Gets a copy of the item the player is currently holding
+ * Gets the item the player is currently holding
*
* @return the currently held item
* @see #getItemInMainHand()
Reference in a new issue View git blame Copy permalink