Javadoc improvements per checkstyle

By: md_5 <git@md-5.net>
This commit is contained in:
Bukkit/Spigot 2019-12-22 09:56:28 +11:00
parent d419ccca3f
commit d16413b877
96 changed files with 181 additions and 48 deletions

View file

@ -20,7 +20,20 @@
<property name="message" value="Line has trailing spaces."/>
</module>
<!-- See https://checkstyle.org/config_javadoc.html -->
<module name="JavadocPackage"/>
<module name="TreeWalker">
<!-- See https://checkstyle.org/config_javadoc.html -->
<module name="AtclauseOrder"/>
<module name="InvalidJavadocPosition"/>
<module name="JavadocBlockTagLocation"/>
<module name="JavadocContentLocationCheck"/>
<module name="JavadocMethod"/>
<module name="JavadocType"/>
<module name="MissingJavadocPackage"/>
<module name="NonEmptyAtclauseDescription"/>
<!-- See http://checkstyle.sourceforge.net/config_filters.html -->
<module name="SuppressionCommentFilter"/>

View file

@ -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
*/

View file

@ -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);

View file

@ -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> {

View file

@ -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() {

View file

@ -0,0 +1,4 @@
/**
* Classes relevant to advancements.
*/
package org.bukkit.advancement;

View file

@ -0,0 +1,4 @@
/**
* Classes relevant to attributes.
*/
package org.bukkit.attribute;

View file

@ -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);

View file

@ -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);
}

View file

@ -0,0 +1,4 @@
/**
* Classes relevant to banner blocks.
*/
package org.bukkit.block.banner;

View file

@ -0,0 +1,4 @@
/**
* Generalized BlockData classes.
*/
package org.bukkit.block.data;

View file

@ -0,0 +1,4 @@
/**
* Specific BlockData classes relevant to only a given block or set of blocks.
*/
package org.bukkit.block.data.type;

View file

@ -0,0 +1,4 @@
/**
* Classes relevant to structure blocks.
*/
package org.bukkit.block.structure;

View file

@ -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;

View file

@ -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;

View file

@ -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

View file

@ -0,0 +1,6 @@
/**
* Classes concerning an entity's persistent memory.
*
* Currently only relevant for Villagers.
*/
package org.bukkit.entity.memory;

View file

@ -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

View file

@ -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)) {

View file

@ -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;

View file

@ -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;

View file

@ -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

View file

@ -0,0 +1,4 @@
/**
* Events related to raids.
*/
package org.bukkit.event.raid;

View file

@ -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

View file

@ -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);

View file

@ -0,0 +1,4 @@
/**
* Classes that allow attaching custom data to items.
*/
package org.bukkit.inventory.meta.tags;

View file

@ -0,0 +1,4 @@
/**
* Classes relevant to loot table manipulation and generation.
*/
package org.bukkit.loot;

View file

@ -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

View file

@ -19,7 +19,6 @@ public class Banner extends MaterialData implements Attachable {
}
/**
*
* @param type the type
* @param data the raw data value
* @deprecated Magic value

View file

@ -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
*/

View file

@ -33,6 +33,7 @@ public class ExtendedRails extends Rails {
}
/**
* {@inheritDoc}
*
* @deprecated Magic value
*/

View file

@ -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
*/

View file

@ -0,0 +1,4 @@
/**
* Classes relevant to specific material types.
*/
package org.bukkit.material.types;

View file

@ -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");

View file

@ -0,0 +1,4 @@
/**
* Classes that allow attaching persistent data to various objects.
*/
package org.bukkit.persistence;

View file

@ -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

View file

@ -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);

View file

@ -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;

View file

@ -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;

View file

@ -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 {

View file

@ -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 {

View file

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

View file

@ -200,6 +200,9 @@ public class AnnotationTest {
}
/**
* Checks if the class is anonymous.
*
* @param clazz the class to check
* @return true if given class is anonymous
*/
private static boolean isAnonymous(@NotNull ClassNode clazz) {

View file

@ -0,0 +1,4 @@
/**
* Test Classes.
*/
package org.bukkit.configuration.file;

View file

@ -0,0 +1,4 @@
/**
* Test Classes.
*/
package org.bukkit.configuration;

View file

@ -0,0 +1,4 @@
/**
* Test Classes.
*/
package org.bukkit.conversations;

View file

@ -0,0 +1,4 @@
/**
* Test Classes.
*/
package org.bukkit.entity.memory;

View file

@ -0,0 +1,4 @@
/**
* Test Classes.
*/
package org.bukkit.event;

View file

@ -0,0 +1,4 @@
/**
* Test Classes.
*/
package org.bukkit.materials;

View file

@ -65,7 +65,12 @@ public class MetadataValueAdapterTest {
assertEquals("", simpleValue(null).asString());
}
/** Get a fixed value MetadataValue. */
/**
* Get a fixed value MetadataValue.
*
* @param value the value to wrap
* @return the fixed value
*/
private MetadataValue simpleValue(Object value) {
return new FixedMetadataValue(plugin, value);
}

View file

@ -0,0 +1,4 @@
/**
* Test Classes.
*/
package org.bukkit.metadata;

View file

@ -0,0 +1,4 @@
/**
* Test Classes.
*/
package org.bukkit;

View file

@ -0,0 +1,4 @@
/**
* Test Classes.
*/
package org.bukkit.plugin.messaging;

View file

@ -0,0 +1,4 @@
/**
* Test Classes.
*/
package org.bukkit.plugin;

View file

@ -0,0 +1,4 @@
/**
* Test Classes.
*/
package org.bukkit.util.io;

View file

@ -0,0 +1,4 @@
/**
* Test Classes.
*/
package org.bukkit.util;