SPIGOT-1244, SPIGOT-6860, SPIGOT-6874: Various Javadoc and formatting fixes

By: Parker Hawke <hawkeboyz2@hotmail.com>

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

@@ -212,7 +212,8 @@ public interface Chunk extends PersistentDataHolder {
     /**
      * Gets the amount of time in ticks that this chunk has been inhabited.
      *
-     * Note that the time is incremented once per tick per player in the chunk.
+     * Note that the time is incremented once per tick per player within mob
+     * spawning distance of this chunk.
      *
      * @return inhabited time
      */

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

@@ -230,11 +230,11 @@ public enum Effect {
      */
     POINTED_DRIPSTONE_LAND(1045, Type.SOUND),
     /**
-     * The sound played when a pointed driptone drips lava into a cauldron.
+     * The sound played when a pointed dripstone drips lava into a cauldron.
      */
     POINTED_DRIPSTONE_DRIP_LAVA_INTO_CAULDRON(1046, Type.SOUND),
     /**
-     * The sound played when a pointed driptone drips water into a cauldron.
+     * The sound played when a pointed dripstone drips water into a cauldron.
      */
     POINTED_DRIPSTONE_DRIP_WATER_INTO_CAULDRON(1047, Type.SOUND),
     /**
@@ -267,7 +267,7 @@ public enum Effect {
     /**
      * The particles shown when a dripstone drips lava or water.
      *
-     * This effect requires a driptone at the location as well as lava or water
+     * This effect requires a dripstone at the location as well as lava or water
      * at the root of the dripstone.
      */
     DRIPPING_DRIPSTONE(1504, Type.VISUAL),
@@ -283,11 +283,11 @@ public enum Effect {
      */
     ENDER_DRAGON_DESTROY_BLOCK(2008, Type.VISUAL),
     /**
-     * The particles shown when a sponge drys in an ultra warm world (nether).
+     * The particles shown when a sponge dries in an ultra warm world (nether).
      */
     SPONGE_DRY(2009, Type.VISUAL),
     /**
-     * The particles shown when a lightning hits a lightning rod or oxidised
+     * The particles shown when a lightning hits a lightning rod or oxidized
      * copper.
      *
      * Data is the axis at which the particle should be shown. If no data is
@@ -303,7 +303,7 @@ public enum Effect {
      */
     COPPER_WAX_OFF(3004, Type.VISUAL),
     /**
-     * The particles shown when oxidisation is scraped of an oxidised copper
+     * The particles shown when oxidation is scraped of an oxidized copper
      * block.
      */
     OXIDISED_COPPER_SCRAPE(3005, Type.VISUAL),

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

@@ -3,11 +3,26 @@ package org.bukkit;
 import java.util.Locale;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Represents a fluid type.
+ */
 public enum Fluid implements Keyed {
 
+    /**
+     * Stationary water.
+     */
     WATER,
+    /**
+     * Flowing water.
+     */
     FLOWING_WATER,
+    /**
+     * Stationary lava.
+     */
     LAVA,
+    /**
+     * Flowing lava.
+     */
     FLOWING_LAVA;
 
     private final NamespacedKey key;

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

@@ -9,6 +9,7 @@ import java.util.Map;
 import java.util.function.Consumer;
 import org.bukkit.attribute.Attribute;
 import org.bukkit.attribute.AttributeModifier;
+import org.bukkit.block.Block;
 import org.bukkit.block.data.Ageable;
 import org.bukkit.block.data.AnaloguePowerable;
 import org.bukkit.block.data.Bisected;
@@ -7334,9 +7335,22 @@ public enum Material implements Keyed {
     }
 
     /**
-     * Check if the material is a block and completely blocks vision
+     * Check if the material is a block and occludes light in the lighting engine.
+     * <p>
+     * Generally speaking, most full blocks will occlude light. Non-full blocks are
+     * not occluding (e.g. anvils, chests, tall grass, stairs, etc.), nor are specific
+     * full blocks such as barriers or spawners which block light despite their texture.
+     * <p>
+     * An occluding block will have the following effects:
+     * <ul>
+     *   <li>Chests cannot be opened if an occluding block is above it.
+     *   <li>Mobs cannot spawn inside of occluding blocks.
+     *   <li>Only occluding blocks can be "powered" ({@link Block#isBlockPowered()}).
+     * </ul>
+     * This list may be inconclusive. For a full list of the side effects of an occluding
+     * block, see the <a href="https://minecraft.fandom.com/wiki/Opacity">Minecraft Wiki</a>.
      *
-     * @return True if this material is a block and completely blocks vision
+     * @return True if this material is a block and occludes light
      */
     public boolean isOccluding() {
         if (!isBlock()) {

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

@@ -465,7 +465,7 @@ public interface Tag<T extends Keyed> extends Keyed {
      */
     Tag<Material> CAULDRONS = Bukkit.getTag(REGISTRY_BLOCKS, NamespacedKey.minecraft("cauldrons"), Material.class);
     /**
-     * Vanilla block tag representing all blocks that make cryustal sounds.
+     * Vanilla block tag representing all blocks that make crystal sounds.
      */
     Tag<Material> CRYSTAL_SOUND_BLOCKS = Bukkit.getTag(REGISTRY_BLOCKS, NamespacedKey.minecraft("crystal_sound_blocks"), Material.class);
     /**

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

@@ -13,7 +13,7 @@ public class Vibration {
     private final Destination destination;
     private final int arrivalTime;
 
-    public Vibration(@NotNull Location origin, @NotNull Destination destination, @NotNull int arrivalTime) {
+    public Vibration(@NotNull Location origin, @NotNull Destination destination, int arrivalTime) {
         this.origin = origin;
         this.destination = destination;
         this.arrivalTime = arrivalTime;

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

@@ -1809,7 +1809,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * <ul>
      * <li>A value of 1 will mean the server will attempt to spawn water ambient mobs in
      *     this world on every tick.
-     * <li>A value of 400 will mean the server will attempt to spawn weater ambient mobs
+     * <li>A value of 400 will mean the server will attempt to spawn water ambient mobs
      *     in this world every 400th tick.
      * <li>A value below 0 will be reset back to Minecraft's default.
      * </ul>

paper-api/src/main/java/org/bukkit/entity/Mob.java

@@ -50,7 +50,7 @@ public interface Mob extends LivingEntity, Lootable {
     public boolean isAware();
 
     /**
-     * Get the {@link Sound} this makes while ambiently existing. This sound
+     * Get the {@link Sound} this mob makes while ambiently existing. This sound
      * may change depending on the current state of the entity, and may also
      * return null under specific conditions. This sound is not constant.
      * For instance, villagers will make different passive noises depending

paper-api/src/main/java/org/bukkit/event/player/PlayerArmorStandManipulateEvent.java

@@ -8,7 +8,8 @@ import org.bukkit.inventory.ItemStack;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when a player interacts with an armor stand and will either swap, retrieve or place an item.
+ * Called when a player interacts with an armor stand and will either swap, retrieve or
+ * place an item.
  */
 public class PlayerArmorStandManipulateEvent extends PlayerInteractEntityEvent {
 
@@ -26,12 +27,14 @@ public class PlayerArmorStandManipulateEvent extends PlayerInteractEntityEvent {
     }
 
     /**
-     * Returns the item held by the player. If this Item is null and the armor stand Item is also null,
+     * Returns the item held by the player.
-     * there will be no transaction between the player and the armor stand.
+     * <p>
-     * If the Player's item is null, but the armor stand item is not then the player will obtain the armor stand item.
+     * If this item is empty and the armor stand item is also empty, there will be no
-     * In the case that the Player's item is not null, but the armor stand item is null, the players item will be placed on the armor stand.
+     * transaction between the player and the armor stand. If the player's item is empty
-     * If both items are not null, the items will be swapped.
+     * but the armor stand item is not, the player's item will be placed on the armor
-     * In the case that the event is cancelled the original items will remain the same.
+     * stand. If both items are not empty, the items will be swapped.
+     * <p>
+     * In the case that this event is cancelled, the original items will remain the same.
      * @return the item held by the player.
      */
     @NotNull
@@ -41,10 +44,14 @@ public class PlayerArmorStandManipulateEvent extends PlayerInteractEntityEvent {
 
     /**
      * Returns the item held by the armor stand.
-     * If this Item is null and the player's Item is also null, there will be no transaction between the player and the armor stand.
+     * <p>
-     * If the Player's item is null, but the armor stand item is not then the player will obtain the armor stand item.
+     * If this item is empty and the player's item is also empty, there will be no
-     * In the case that the Player's item is not null, but the armor stand item is null, the players item will be placed on the armor stand.
+     * transaction between the player and the armor stand. If the player's item is empty
-     * If both items are not null, the items will be swapped.
+     * but the armor stand item is not, then the player will obtain the armor stand item.
+     * In the case that the player's item is not empty but the armor stand item is empty,
+     * the player's item will be placed on the armor stand. If both items are not empty,
+     * the items will be swapped.
+     * <p>
      * In the case that the event is cancelled the original items will remain the same.
      * @return the item held by the armor stand.
      */

paper-api/src/main/java/org/bukkit/util/StructureSearchResult.java

@@ -20,7 +20,7 @@ public interface StructureSearchResult {
      * @return the found structure.
      */
     @NotNull
-     Structure getStructure();
+    Structure getStructure();
 
     /**
      * Return the location of the structure.