Upstream/Paper
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2024-11-13 06:07:40 +01:00
Code Issues Projects Releases Wiki Activity
385f313a8b
Paper/patches/api/0054-Fix-upstream-javadocs.patch
Nassim Jahnke 385f313a8b
Updated Upstream (Bukkit/CraftBukkit/Spigot) (#8092) 
Upstream has released updates that appear to apply and compile correctly.
This update has not been tested by PaperMC and as with ANY update, please do your own testing

Bukkit Changes:
d41796de SPIGOT-7071: Add Player#stopSound(SoundCategory category)
61dae5b2 SPIGOT-7011, SPIGOT-7065: Overhaul of structures

CraftBukkit Changes:
991aeda12 SPIGOT-1729, SPIGOT-7090: Keep precision in teleportation between worlds
5c9a5f628 SPIGOT-7071: Add Player#stopSound(SoundCategory category)
68f888ded SPIGOT-7011, SPIGOT-7065: Overhaul of structures
0231a3746 Remove outdated build delay.

Spigot Changes:
475f6008 Rebuild patches
8ce1761f Rebuild patches
2022-07-04 16:38:06 +02:00

392 lines
16 KiB
Diff
Raw Blame History

From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
From: Zach Brown <zach.brown@destroystokyo.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 aea30cacbf43c4c6d30b0c9e0d59fcd2db444ad8..e25a6532deca1df59eff2ab59697b851535ee952 100644
--- a/src/main/java/org/bukkit/Bukkit.java
+++ b/src/main/java/org/bukkit/Bukkit.java
@@ -1331,6 +1331,8 @@ 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 5e4e6e83ac6b52493cb285561425bed53ffff2b6..2bfbb0ce71c8c5f8bd9bbd908488831b94ce583f 100644
--- a/src/main/java/org/bukkit/Server.java
+++ b/src/main/java/org/bukkit/Server.java
@@ -509,13 +509,10 @@ 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);
@@ -1126,6 +1123,8 @@ 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/entity/ArmorStand.java b/src/main/java/org/bukkit/entity/ArmorStand.java
index 91fc11dda99de506be83d40df8929bf7cd8e8d85..7dc631ebd009f5f5c3ac1699c3f3515c47609c05 100644
--- a/src/main/java/org/bukkit/entity/ArmorStand.java
+++ b/src/main/java/org/bukkit/entity/ArmorStand.java
@@ -360,5 +360,8 @@ 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 2cf43eac30187a43a01c81b3021b2cfec0d4ba8a..864941be2d07de08f63e740ad2becf1dc5790433 100644
--- a/src/main/java/org/bukkit/entity/HumanEntity.java
+++ b/src/main/java/org/bukkit/entity/HumanEntity.java
@@ -21,6 +21,11 @@ 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 be9334a8b5fba9181ad63c211697e798be63da25..0514a141cb93a650be38c63d4336d46e4304f4b6 100644
--- a/src/main/java/org/bukkit/entity/Mob.java
+++ b/src/main/java/org/bukkit/entity/Mob.java
@@ -8,6 +8,10 @@ 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 6e6ec4095ac9d6c17b1ee657133f6521ead35226..cf4beb02cce7b87facd5465291286f1b5e97db59 100644
--- a/src/main/java/org/bukkit/entity/Player.java
+++ b/src/main/java/org/bukkit/entity/Player.java
@@ -303,15 +303,15 @@ 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.
@@ -767,7 +767,7 @@ 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 1119e26e270bb45f517955b19d95a9ec3d113634..4631647c64c89ffdde2d9b63bdab974acfe6cb3d 100644
--- a/src/main/java/org/bukkit/entity/Slime.java
+++ b/src/main/java/org/bukkit/entity/Slime.java
@@ -11,6 +11,16 @@ 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/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
index d5b50a4a954fed35d37f03f1a277cc173ca106df..a91fa5386afd7a1137adb921ad5adb798604772f 100644
--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
+++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
@@ -37,9 +37,23 @@ 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
@@ -61,9 +75,23 @@ 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
@@ -85,7 +113,21 @@ 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()
@@ -110,11 +152,24 @@ 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();
/**
@@ -133,11 +188,24 @@ 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();
/**
@@ -156,11 +224,24 @@ 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();
/**
@@ -179,11 +260,24 @@ 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();
/**
@@ -202,12 +296,25 @@ 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 62fbd7f6d8195bebcab7f704a0a485a1bbeca26c..5461f7fa75f5a065bb333b4a113640b5fe1e3825 100644
--- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
+++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java
@@ -158,7 +158,7 @@ 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
@@ -174,7 +174,7 @@ 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
@@ -190,7 +190,7 @@ 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 New Issue View Git Blame Copy Permalink