Pulling all pending Bukkit-JavaDoc changes

A special thanks goes to @aerouk for almost all of the changes found here.

By: Wesley Wolfe <weswolf@aol.com>
This commit is contained in:
Bukkit/Spigot
2013-12-15 01:07:43 -05:00
parent 800679913f
commit bb50f1a774
310 changed files with 4218 additions and 2904 deletions

View File

@@ -53,7 +53,8 @@ public class CreatureSpawnEvent extends EntityEvent implements Cancellable {
/**
* Gets the type of creature being spawned.
*
* @return A CreatureType value detailing the type of creature being spawned
* @return A CreatureType value detailing the type of creature being
* spawned
* @deprecated In favour of {@link #getEntityType()}.
*/
@Deprecated
@@ -64,7 +65,8 @@ public class CreatureSpawnEvent extends EntityEvent implements Cancellable {
/**
* Gets the reason for why the creature is being spawned.
*
* @return A SpawnReason value detailing the reason for the creature being spawned
* @return A SpawnReason value detailing the reason for the creature being
* spawned
*/
public SpawnReason getSpawnReason() {
return spawnReason;
@@ -89,7 +91,8 @@ public class CreatureSpawnEvent extends EntityEvent implements Cancellable {
*/
NATURAL,
/**
* When an entity spawns as a jockey of another entity (mostly spider jockeys)
* When an entity spawns as a jockey of another entity (mostly spider
* jockeys)
*/
JOCKEY,
/**

View File

@@ -73,16 +73,19 @@ public class CreeperPowerEvent extends EntityEvent implements Cancellable {
/**
* Power change caused by a lightning bolt
* <p>
* Powered state: true
*/
LIGHTNING,
/**
* Power change caused by something else (probably a plugin)
* <p>
* Powered state: true
*/
SET_ON,
/**
* Power change caused by something else (probably a plugin)
* <p>
* Powered state: false
*/
SET_OFF

View File

@@ -8,7 +8,7 @@ import org.bukkit.entity.LivingEntity;
/**
* Called when an {@link Entity} breaks a door
* <p>
* Canceling the event will cause the event to be delayed
* Cancelling the event will cause the event to be delayed
*/
public class EntityBreakDoorEvent extends EntityChangeBlockEvent {
public EntityBreakDoorEvent(final LivingEntity entity, final Block targetBlock) {

View File

@@ -22,7 +22,8 @@ public class EntityChangeBlockEvent extends EntityEvent implements Cancellable {
* @param what the LivingEntity causing the change
* @param block the block (before the change)
* @param to the future material being changed to
* @deprecated Provided as a backward compatibility before the data byte was provided, and type increased to all entities
* @deprecated Provided as a backward compatibility before the data byte
* was provided, and type increased to all entities
*/
@Deprecated
public EntityChangeBlockEvent(final LivingEntity what, final Block block, final Material to) {

View File

@@ -29,7 +29,8 @@ public class EntityCombustEvent extends EntityEvent implements Cancellable {
}
/**
* @return the amount of time (in seconds) the combustee should be alight for
* @return the amount of time (in seconds) the combustee should be alight
* for
*/
public int getDuration() {
return duration;
@@ -38,7 +39,8 @@ public class EntityCombustEvent extends EntityEvent implements Cancellable {
/**
* The number of seconds the combustee should be alight for.
* <p>
* This value will only ever increase the combustion time, not decrease existing combustion times.
* This value will only ever increase the combustion time, not decrease
* existing combustion times.
*
* @param duration the time in seconds to be alight for.
*/

View File

@@ -161,7 +161,8 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
*/
BLOCK_EXPLOSION,
/**
* Damage caused by being in the area when an entity, such as a Creeper, explodes.
* Damage caused by being in the area when an entity, such as a
* Creeper, explodes.
* <p>
* Damage: variable
*/
@@ -215,7 +216,8 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
*/
FALLING_BLOCK,
/**
* Damage caused in retaliation to another attack by the Thorns enchantment.
* Damage caused in retaliation to another attack by the Thorns
* enchantment.
* <p>
* Damage: 1-4 (Thorns)
*/

View File

@@ -31,8 +31,8 @@ public class EntityDeathEvent extends EntityEvent {
/**
* Gets how much EXP should be dropped from this death.
* <p>
* This does not indicate how much EXP should be taken from the entity in question,
* merely how much should be created after its death.
* This does not indicate how much EXP should be taken from the entity in
* question, merely how much should be created after its death.
*
* @return Amount of EXP to drop.
*/
@@ -43,8 +43,8 @@ public class EntityDeathEvent extends EntityEvent {
/**
* Sets how much EXP should be dropped from this death.
* <p>
* This does not indicate how much EXP should be taken from the entity in question,
* merely how much should be created after its death.
* This does not indicate how much EXP should be taken from the entity in
* question, merely how much should be created after its death.
*
* @param exp Amount of EXP to drop.
*/

View File

@@ -35,8 +35,8 @@ public class EntityExplodeEvent extends EntityEvent implements Cancellable {
}
/**
* Returns the list of blocks that would have been removed or were
* removed from the explosion event.
* Returns the list of blocks that would have been removed or were removed
* from the explosion event.
*
* @return All blown-up blocks
*/
@@ -46,8 +46,9 @@ public class EntityExplodeEvent extends EntityEvent implements Cancellable {
/**
* Returns the location where the explosion happened.
* It is not possible to get this value from the Entity as
* the Entity no longer exists in the world.
* <p>
* It is not possible to get this value from the Entity as the Entity no
* longer exists in the world.
*
* @return The location of the explosion
*/

View File

@@ -8,8 +8,8 @@ import org.bukkit.util.Vector;
/**
* Called before an entity exits a portal.
* <p>
* This event allows you to modify the velocity of the entity after they
* have successfully exeted the portal.
* This event allows you to modify the velocity of the entity after they have
* successfully exited the portal.
*/
public class EntityPortalExitEvent extends EntityTeleportEvent {
private static final HandlerList handlers = new HandlerList();
@@ -23,7 +23,8 @@ public class EntityPortalExitEvent extends EntityTeleportEvent {
}
/**
* Gets a copy of the velocity that the entity has before entering the portal.
* Gets a copy of the velocity that the entity has before entering the
* portal.
*
* @return velocity of entity before entering portal
*/
@@ -32,7 +33,8 @@ public class EntityPortalExitEvent extends EntityTeleportEvent {
}
/**
* Gets a copy of the velocity that the entity will have after exiting the portal.
* Gets a copy of the velocity that the entity will have after exiting the
* portal.
*
* @return velocity of entity after exiting portal
*/

View File

@@ -74,7 +74,8 @@ public class EntityRegainHealthEvent extends EntityEvent implements Cancellable
/**
* Gets the reason for why the entity is regaining health
*
* @return A RegainReason detailing the reason for the entity regaining health
* @return A RegainReason detailing the reason for the entity regaining
* health
*/
public RegainReason getRegainReason() {
return regainReason;
@@ -95,11 +96,13 @@ public class EntityRegainHealthEvent extends EntityEvent implements Cancellable
public enum RegainReason {
/**
* When a player regains health from regenerating due to Peaceful mode (difficulty=0)
* When a player regains health from regenerating due to Peaceful mode
* (difficulty=0)
*/
REGEN,
/**
* When a player regains health from regenerating due to their hunger being satisfied
* When a player regains health from regenerating due to their hunger
* being satisfied
*/
SATIATED,
/**

View File

@@ -30,7 +30,8 @@ public class EntityShootBowEvent extends EntityEvent implements Cancellable {
}
/**
* Gets the bow ItemStack used to fire the arrow; is null if the shooter is a skeleton
* Gets the bow ItemStack used to fire the arrow; is null if the shooter
* is a skeleton
*
* @return the bow involved in this event, or null
*/

View File

@@ -38,8 +38,9 @@ public class EntityTargetEvent extends EntityEvent implements Cancellable {
/**
* Get the entity that this is targeting.
* This will be null in the case that the event is called when
* the mob forgets its target.
* <p>
* This will be null in the case that the event is called when the mob
* forgets its target.
*
* @return The entity
*/
@@ -49,12 +50,13 @@ public class EntityTargetEvent extends EntityEvent implements Cancellable {
/**
* Set the entity that you want the mob to target instead.
* <p>
* It is possible to be null, null will cause the entity to be
* target-less.
* <p>
* This is different from cancelling the event. Cancelling the event
* will cause the entity to keep an original target, while setting to be
* null will cause the entity to be reset
* This is different from cancelling the event. Cancelling the event will
* cause the entity to keep an original target, while setting to be null
* will cause the entity to be reset.
*
* @param target The entity to target
*/
@@ -96,15 +98,19 @@ public class EntityTargetEvent extends EntityEvent implements Cancellable {
PIG_ZOMBIE_TARGET,
/**
* When the target is forgotten for whatever reason.
* Currently only occurs in with spiders when there is a high brightness
* <p>
* Currently only occurs in with spiders when there is a high
* brightness.
*/
FORGOT_TARGET,
/**
* When the target attacks the owner of the entity, so the entity targets it.
* When the target attacks the owner of the entity, so the entity
* targets it.
*/
TARGET_ATTACKED_OWNER,
/**
* When the owner of the entity attacks the target attacks, so the entity targets it.
* When the owner of the entity attacks the target attacks, so the
* entity targets it.
*/
OWNER_ATTACKED_TARGET,
/**
@@ -116,7 +122,7 @@ public class EntityTargetEvent extends EntityEvent implements Cancellable {
*/
DEFEND_VILLAGE,
/**
* For custom calls to the event
* For custom calls to the event.
*/
CUSTOM
}

View File

@@ -4,7 +4,8 @@ import org.bukkit.entity.Entity;
import org.bukkit.entity.LivingEntity;
/**
* Called when an Entity targets a {@link LivingEntity} and can only target LivingEntity's.
* Called when an Entity targets a {@link LivingEntity} and can only target
* LivingEntity's.
*/
public class EntityTargetLivingEntityEvent extends EntityTargetEvent{
public EntityTargetLivingEntityEvent(final Entity entity, final LivingEntity target, final TargetReason reason) {
@@ -17,10 +18,11 @@ public class EntityTargetLivingEntityEvent extends EntityTargetEvent{
/**
* Set the Entity that you want the mob to target.
* <p>
* It is possible to be null, null will cause the entity to be
* target-less.
* <p>
* Must be a LivingEntity, or null
* Must be a LivingEntity, or null.
*
* @param target The entity to target
*/

View File

@@ -6,8 +6,8 @@ import org.bukkit.event.Cancellable;
import org.bukkit.event.HandlerList;
/**
* Thrown when a non-player entity (such as an Enderman) tries to teleport from one
* location to another.
* Thrown when a non-player entity (such as an Enderman) tries to teleport
* from one location to another.
*/
public class EntityTeleportEvent extends EntityEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();

View File

@@ -1,73 +1,75 @@
package org.bukkit.event.entity;
import org.bukkit.entity.ThrownExpBottle;
import org.bukkit.event.HandlerList;
/**
* Called when a ThrownExpBottle hits and releases experience.
*/
public class ExpBottleEvent extends ProjectileHitEvent {
private static final HandlerList handlers = new HandlerList();
private int exp;
private boolean showEffect = true;
public ExpBottleEvent(final ThrownExpBottle bottle, final int exp) {
super(bottle);
this.exp = exp;
}
@Override
public ThrownExpBottle getEntity() {
return (ThrownExpBottle) entity;
}
/**
* This method indicates if the particle effect should be shown.
*
* @return true if the effect will be shown, false otherwise
*/
public boolean getShowEffect() {
return this.showEffect;
}
/**
* This method sets if the particle effect will be shown.
* This does not change the experience created.
*
* @param showEffect
* true indicates the effect will be shown,
* false indicates no effect will be shown
*/
public void setShowEffect(final boolean showEffect) {
this.showEffect = showEffect;
}
/**
* This method retrieves the amount of experience to be created.
* The number indicates a total amount to be divided into orbs.
*
* @return the total amount of experience to be created
*/
public int getExperience() {
return exp;
}
/**
* This method sets the amount of experience to be created.
* The number indicates a total amount to be divided into orbs.
*
* @param exp the total amount of experience to be created
*/
public void setExperience(final int exp) {
this.exp = exp;
}
@Override
public HandlerList getHandlers() {
return handlers;
}
public static HandlerList getHandlerList() {
return handlers;
}
}
package org.bukkit.event.entity;
import org.bukkit.entity.ThrownExpBottle;
import org.bukkit.event.HandlerList;
/**
* Called when a ThrownExpBottle hits and releases experience.
*/
public class ExpBottleEvent extends ProjectileHitEvent {
private static final HandlerList handlers = new HandlerList();
private int exp;
private boolean showEffect = true;
public ExpBottleEvent(final ThrownExpBottle bottle, final int exp) {
super(bottle);
this.exp = exp;
}
@Override
public ThrownExpBottle getEntity() {
return (ThrownExpBottle) entity;
}
/**
* This method indicates if the particle effect should be shown.
*
* @return true if the effect will be shown, false otherwise
*/
public boolean getShowEffect() {
return this.showEffect;
}
/**
* This method sets if the particle effect will be shown.
* <p>
* This does not change the experience created.
*
* @param showEffect true indicates the effect will be shown, false
* indicates no effect will be shown
*/
public void setShowEffect(final boolean showEffect) {
this.showEffect = showEffect;
}
/**
* This method retrieves the amount of experience to be created.
* <p>
* The number indicates a total amount to be divided into orbs.
*
* @return the total amount of experience to be created
*/
public int getExperience() {
return exp;
}
/**
* This method sets the amount of experience to be created.
* <p>
* The number indicates a total amount to be divided into orbs.
*
* @param exp the total amount of experience to be created
*/
public void setExperience(final int exp) {
this.exp = exp;
}
@Override
public HandlerList getHandlers() {
return handlers;
}
public static HandlerList getHandlerList() {
return handlers;
}
}

View File

@@ -23,7 +23,8 @@ public class FoodLevelChangeEvent extends EntityEvent implements Cancellable {
}
/**
* Gets the resultant food level that the entity involved in this event should be set to.
* Gets the resultant food level that the entity involved in this event
* should be set to.
* <p>
* Where 20 is a full food bar and 0 is an empty one.
*
@@ -34,9 +35,11 @@ public class FoodLevelChangeEvent extends EntityEvent implements Cancellable {
}
/**
* Sets the resultant food level that the entity involved in this event should be set to
* Sets the resultant food level that the entity involved in this event
* should be set to
*
* @param level the resultant food level that the entity involved in this event should be set to
* @param level the resultant food level that the entity involved in this
* event should be set to
*/
public void setFoodLevel(int level) {
if (level > 20) level = 20;

View File

@@ -35,15 +35,15 @@ public class HorseJumpEvent extends EntityEvent implements Cancellable {
* <p>
* Power is a value that defines how much of the horse's jump strength
* should be used for the jump. Power is effectively multiplied times
* the horse's jump strength to determine how high the jump is;
* 0 represents no jump strength while 1 represents full jump strength.
* the horse's jump strength to determine how high the jump is; 0
* represents no jump strength while 1 represents full jump strength.
* Setting power to a value above 1 will use additional jump strength
* that the horse does not usually have.
* <p>
* Power does not affect how high the horse is capable of jumping,
* only how much of its jumping capability will be used in this jump.
* To set the horse's overall jump strength, see
* {@link Horse#setJumpStrength(double)}.
* Power does not affect how high the horse is capable of jumping, only
* how much of its jumping capability will be used in this jump. To set
* the horse's overall jump strength, see {@link
* Horse#setJumpStrength(double)}.
*
* @return jump strength
*/
@@ -54,12 +54,12 @@ public class HorseJumpEvent extends EntityEvent implements Cancellable {
/**
* Sets the power of the jump.
* <p>
* Jump power can be set to a value above 1.0 which will increase
* the strength of this jump above the horse's actual jump strength.
* Jump power can be set to a value above 1.0 which will increase the
* strength of this jump above the horse's actual jump strength.
* <p>
* Setting the jump power to 0 will result in the jump animation
* still playing, but the horse not leaving the ground. Only
* canceling this event will result in no jump animation at all.
* Setting the jump power to 0 will result in the jump animation still
* playing, but the horse not leaving the ground. Only canceling this
* event will result in no jump animation at all.
*
* @param power power of the jump
*/

View File

@@ -44,8 +44,8 @@ public class PigZapEvent extends EntityEvent implements Cancellable {
}
/**
* Gets the zombie pig that will replace the pig,
* provided the event is not cancelled first.
* Gets the zombie pig that will replace the pig, provided the event is
* not cancelled first.
*
* @return resulting entity
*/

View File

@@ -1,93 +1,94 @@
package org.bukkit.event.entity;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Map;
import org.apache.commons.lang.Validate;
import org.bukkit.entity.LivingEntity;
import org.bukkit.entity.ThrownPotion;
import org.bukkit.event.Cancellable;
import org.bukkit.event.HandlerList;
/**
* Called when a splash potion hits an area
*/
public class PotionSplashEvent extends ProjectileHitEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
private boolean cancelled;
private final Map<LivingEntity, Double> affectedEntities;
public PotionSplashEvent(final ThrownPotion potion, final Map<LivingEntity, Double> affectedEntities) {
super(potion);
this.affectedEntities = affectedEntities;
}
@Override
public ThrownPotion getEntity() {
return (ThrownPotion) entity;
}
/**
* Gets the potion which caused this event
*
* @return The thrown potion entity
*/
public ThrownPotion getPotion() {
return (ThrownPotion) getEntity();
}
/**
* Retrieves a list of all effected entities
*
* @return A fresh copy of the affected entity list
*/
public Collection<LivingEntity> getAffectedEntities() {
return new ArrayList<LivingEntity>(affectedEntities.keySet());
}
/**
* Gets the intensity of the potion's effects for given entity;
* This depends on the distance to the impact center
*
* @param entity Which entity to get intensity for
* @return intensity relative to maximum effect; 0.0: not affected; 1.0: fully hit by potion effects
*/
public double getIntensity(LivingEntity entity) {
Double intensity = affectedEntities.get(entity);
return intensity != null ? intensity : 0.0;
}
/**
* Overwrites the intensity for a given entity
*
* @param entity For which entity to define a new intensity
* @param intensity relative to maximum effect
*/
public void setIntensity(LivingEntity entity, double intensity) {
Validate.notNull(entity, "You must specify a valid entity.");
if (intensity <= 0.0) {
affectedEntities.remove(entity);
} else {
affectedEntities.put(entity, Math.min(intensity, 1.0));
}
}
public boolean isCancelled() {
return cancelled;
}
public void setCancelled(boolean cancel) {
cancelled = cancel;
}
@Override
public HandlerList getHandlers() {
return handlers;
}
public static HandlerList getHandlerList() {
return handlers;
}
}
package org.bukkit.event.entity;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Map;
import org.apache.commons.lang.Validate;
import org.bukkit.entity.LivingEntity;
import org.bukkit.entity.ThrownPotion;
import org.bukkit.event.Cancellable;
import org.bukkit.event.HandlerList;
/**
* Called when a splash potion hits an area
*/
public class PotionSplashEvent extends ProjectileHitEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
private boolean cancelled;
private final Map<LivingEntity, Double> affectedEntities;
public PotionSplashEvent(final ThrownPotion potion, final Map<LivingEntity, Double> affectedEntities) {
super(potion);
this.affectedEntities = affectedEntities;
}
@Override
public ThrownPotion getEntity() {
return (ThrownPotion) entity;
}
/**
* Gets the potion which caused this event
*
* @return The thrown potion entity
*/
public ThrownPotion getPotion() {
return (ThrownPotion) getEntity();
}
/**
* Retrieves a list of all effected entities
*
* @return A fresh copy of the affected entity list
*/
public Collection<LivingEntity> getAffectedEntities() {
return new ArrayList<LivingEntity>(affectedEntities.keySet());
}
/**
* Gets the intensity of the potion's effects for given entity; This
* depends on the distance to the impact center
*
* @param entity Which entity to get intensity for
* @return intensity relative to maximum effect; 0.0: not affected; 1.0:
* fully hit by potion effects
*/
public double getIntensity(LivingEntity entity) {
Double intensity = affectedEntities.get(entity);
return intensity != null ? intensity : 0.0;
}
/**
* Overwrites the intensity for a given entity
*
* @param entity For which entity to define a new intensity
* @param intensity relative to maximum effect
*/
public void setIntensity(LivingEntity entity, double intensity) {
Validate.notNull(entity, "You must specify a valid entity.");
if (intensity <= 0.0) {
affectedEntities.remove(entity);
} else {
affectedEntities.put(entity, Math.min(intensity, 1.0));
}
}
public boolean isCancelled() {
return cancelled;
}
public void setCancelled(boolean cancel) {
cancelled = cancel;
}
@Override
public HandlerList getHandlers() {
return handlers;
}
public static HandlerList getHandlerList() {
return handlers;
}
}

View File

@@ -1,41 +1,41 @@
package org.bukkit.event.entity;
import org.bukkit.entity.Sheep;
import org.bukkit.event.Cancellable;
import org.bukkit.event.HandlerList;
/**
* Called when a sheep regrows its wool
*/
public class SheepRegrowWoolEvent extends EntityEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
private boolean cancel;
public SheepRegrowWoolEvent(final Sheep sheep) {
super(sheep);
this.cancel = false;
}
public boolean isCancelled() {
return cancel;
}
public void setCancelled(boolean cancel) {
this.cancel = cancel;
}
@Override
public Sheep getEntity() {
return (Sheep) entity;
}
@Override
public HandlerList getHandlers() {
return handlers;
}
public static HandlerList getHandlerList() {
return handlers;
}
}
package org.bukkit.event.entity;
import org.bukkit.entity.Sheep;
import org.bukkit.event.Cancellable;
import org.bukkit.event.HandlerList;
/**
* Called when a sheep regrows its wool
*/
public class SheepRegrowWoolEvent extends EntityEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
private boolean cancel;
public SheepRegrowWoolEvent(final Sheep sheep) {
super(sheep);
this.cancel = false;
}
public boolean isCancelled() {
return cancel;
}
public void setCancelled(boolean cancel) {
this.cancel = cancel;
}
@Override
public Sheep getEntity() {
return (Sheep) entity;
}
@Override
public HandlerList getHandlers() {
return handlers;
}
public static HandlerList getHandlerList() {
return handlers;
}
}