Pulling all pending Bukkit-JavaDoc changes

By: Edmond Poon <sagaciouszzzz@gmail.com>
This commit is contained in:
Bukkit/Spigot
2013-04-02 00:11:22 -04:00
parent 745a0d7683
commit 761a84cb1b
93 changed files with 539 additions and 505 deletions

View File

@@ -14,7 +14,7 @@ public @interface EventHandler {
/**
* Define the priority of the event.
* <p />
* <p>
* First priority to the last priority executed:
* <ol>
* <li>LOWEST</li>
@@ -29,7 +29,7 @@ public @interface EventHandler {
/**
* Define if the handler ignores a cancelled event.
* <p />
* <p>
* If ignoreCancelled is true and the event is cancelled, the method is
* not called. Otherwise, the method is always called.
*/

View File

@@ -7,7 +7,7 @@ import org.bukkit.event.HandlerList;
/**
* Called when a block is broken by a player.
* <p />
* <p>
* If you wish to have the block drop experience, you must set the experience value above 0.
* By default, experience will be set in the event if:
* <ol>
@@ -16,11 +16,11 @@ import org.bukkit.event.HandlerList;
* <li />The player does not have silk touch
* <li />The block drops experience in vanilla MineCraft
* </ol>
* <p />
* <p>
* Note:
* Plugins wanting to simulate a traditional block drop should set the block to air and utilize their own methods for determining
* what the default drop for the block being broken is and what to do about it, if anything.
* <p />
* <p>
* If a Block Break event is cancelled, the block will not break and experience will not drop.
*/
public class BlockBreakEvent extends BlockExpEvent implements Cancellable {

View File

@@ -6,7 +6,7 @@ import org.bukkit.event.HandlerList;
/**
* Called when a block is destroyed as a result of being burnt by fire.
* <p />
* <p>
* If a Block Burn event is cancelled, the block will not be destroyed as a result of being burnt by fire.
*/
public class BlockBurnEvent extends BlockEvent implements Cancellable {

View File

@@ -6,7 +6,7 @@ import org.bukkit.event.HandlerList;
/**
* Called when we try to place a block, to see if we can build it here or not.
* <p />
* <p>
* Note:
* <ul>
* <li>The Block returned by getBlock() is the block we are trying to place on, not the block we are trying to place.</li>

View File

@@ -8,7 +8,7 @@ import org.bukkit.inventory.ItemStack;
/**
* Called when a block is damaged by a player.
* <p />
* <p>
* If a Block Damage event is cancelled, the block will not be damaged.
*/
public class BlockDamageEvent extends BlockEvent implements Cancellable {

View File

@@ -8,7 +8,7 @@ import org.bukkit.util.Vector;
/**
* Called when an item is dispensed from a block.
* <p />
* <p>
* If a Block Dispense event is cancelled, the block will not dispense the item.
*/
public class BlockDispenseEvent extends BlockEvent implements Cancellable {
@@ -44,7 +44,7 @@ public class BlockDispenseEvent extends BlockEvent implements Cancellable {
/**
* Gets the velocity.
* <p />
* <p>
* Note: Modifying the returned Vector will not change the velocity, you must use {@link #setVelocity(org.bukkit.util.Vector)} instead.
*
* @return A Vector for the dispensed item's velocity

View File

@@ -7,13 +7,13 @@ import org.bukkit.event.HandlerList;
/**
* Called when a block fades, melts or disappears based on world conditions
* <p />
* <p>
* Examples:
* <ul>
* <li>Snow melting due to being near a light source.</li>
* <li>Ice melting due to being near a light source.</li>
* </ul>
* <p />
* <p>
* If a Block Fade event is cancelled, the block will not fade, melt or disappear.
*/
public class BlockFadeEvent extends BlockEvent implements Cancellable {

View File

@@ -8,13 +8,13 @@ import org.bukkit.event.HandlerList;
/**
* Called when a block is formed or spreads based on world conditions.
* Use {@link BlockSpreadEvent} to catch blocks that actually spread and don't just "randomly" form.
* <p />
* <p>
* Examples:
* <ul>
* <li>Snow forming due to a snow storm.</li>
* <li>Ice forming in a snowy Biome like Taiga or Tundra.</li>
* </ul>
* <p />
* <p>
* If a Block Form event is cancelled, the block will not be formed.
*
* @see BlockSpreadEvent

View File

@@ -8,7 +8,7 @@ import org.bukkit.event.HandlerList;
/**
* Represents events with a source block and a destination block, currently only applies to liquid (lava and water)
* and teleporting dragon eggs.
* <p />
* <p>
* If a Block From To event is cancelled, the block will not move (the liquid will not flow).
*/
public class BlockFromToEvent extends BlockEvent implements Cancellable {

View File

@@ -7,7 +7,7 @@ import org.bukkit.event.HandlerList;
/**
* Called when a block grows naturally in the world.
* <p />
* <p>
* Examples:
* <ul>
* <li>Wheat</li>
@@ -16,7 +16,7 @@ import org.bukkit.event.HandlerList;
* <li>Watermelon</li>
* <li>Pumpkin</li>
* </ul>
* <p />
* <p>
* If a Block Grow event is cancelled, the block will not grow.
*/
public class BlockGrowEvent extends BlockEvent implements Cancellable {

View File

@@ -8,7 +8,7 @@ import org.bukkit.event.HandlerList;
/**
* Called when a block is ignited. If you want to catch when a Player places fire, you need to use {@link BlockPlaceEvent}.
* <p />
* <p>
* If a Block Ignite event is cancelled, the block will not be ignited.
*/
public class BlockIgniteEvent extends BlockEvent implements Cancellable {

View File

@@ -9,7 +9,7 @@ import org.bukkit.inventory.ItemStack;
/**
* Called when a block is placed by a player.
* <p />
* <p>
* If a Block Place event is cancelled, the block will not be placed.
*/
public class BlockPlaceEvent extends BlockEvent implements Cancellable {

View File

@@ -7,13 +7,13 @@ import org.bukkit.event.HandlerList;
/**
* Called when a block spreads based on world conditions.
* Use {@link BlockFormEvent} to catch blocks that "randomly" form instead of actually spread.
* <p />
* <p>
* Examples:
* <ul>
* <li>Mushrooms spreading.</li>
* <li>Fire spreading.</li>
* </ul>
* <p />
* <p>
* If a Block Spread event is cancelled, the block will not spread.
*
* @see BlockFormEvent

View File

@@ -6,7 +6,7 @@ import org.bukkit.entity.Entity;
/**
* Called when a block is formed by entities.
* <p />
* <p>
* Examples:
* <ul>
* <li>Snow formed by a {@link org.bukkit.entity.Snowman}.</li>

View File

@@ -6,7 +6,7 @@ import org.bukkit.event.HandlerList;
/**
* Called when leaves are decaying naturally.
* <p />
* <p>
* If a Leaves Decay event is cancelled, the leaves will not decay.
*/
public class LeavesDecayEvent extends BlockEvent implements Cancellable {

View File

@@ -7,7 +7,7 @@ import org.bukkit.event.HandlerList;
/**
* Called when a sign is changed by a player.
* <p />
* <p>
* If a Sign Change event is cancelled, the sign will not be changed.
*/
public class SignChangeEvent extends BlockEvent implements Cancellable {

View File

@@ -9,7 +9,7 @@ import org.bukkit.event.HandlerList;
/**
* Called when a creature is spawned into a world.
* <p />
* <p>
* If a Creature Spawn event is cancelled, the creature will not spawn.
*/
public class CreatureSpawnEvent extends EntityEvent implements Cancellable {

View File

@@ -7,7 +7,7 @@ import org.bukkit.event.HandlerList;
/**
* Called when a Creeper is struck by lightning.
* <p />
* <p>
* If a Creeper Power event is cancelled, the Creeper will not be powered.
*/
public class CreeperPowerEvent extends EntityEvent implements Cancellable {

View File

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

View File

@@ -13,7 +13,7 @@ public class EntityCombustByBlockEvent extends EntityCombustEvent {
/**
* The combuster can be lava or a block that is on fire.
* <p />
* <p>
* WARNING: block may be null.
*
* @return the Block that set the combustee alight.

View File

@@ -11,7 +11,7 @@ public class EntityCombustByEntityEvent extends EntityCombustEvent {
}
/**
* The combuster can be a WeatherStorm a Blaze, or an Entity holding a FIRE_ASPECT enchanted item.
* Get the entity that caused the combustion event.
*
* @return the Entity that set the combustee alight.
*/

View File

@@ -6,7 +6,7 @@ import org.bukkit.event.HandlerList;
/**
* Called when an entity combusts.
* <p />
* <p>
* If an Entity Combust event is cancelled, the entity will not combust.
*/
public class EntityCombustEvent extends EntityEvent implements Cancellable {
@@ -37,7 +37,7 @@ public class EntityCombustEvent extends EntityEvent implements Cancellable {
/**
* The number of seconds the combustee should be alight for.
* <p />
* <p>
* 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

@@ -70,109 +70,109 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
/**
* Damage caused when an entity contacts a block such as a Cactus.
* <p />
* <p>
* Damage: 1 (Cactus)
*/
CONTACT,
/**
* Damage caused when an entity attacks another entity.
* <p />
* <p>
* Damage: variable
*/
ENTITY_ATTACK,
/**
* Damage caused when attacked by a projectile.
* <p />
* <p>
* Damage: variable
*/
PROJECTILE,
/**
* Damage caused by being put in a block
* <p />
* <p>
* Damage: 1
*/
SUFFOCATION,
/**
* Damage caused when an entity falls a distance greater than 3 blocks
* <p />
* <p>
* Damage: fall height - 3.0
*/
FALL,
/**
* Damage caused by direct exposure to fire
* <p />
* <p>
* Damage: 1
*/
FIRE,
/**
* Damage caused due to burns caused by fire
* <p />
* <p>
* Damage: 1
*/
FIRE_TICK,
/**
* Damage caused due to a snowman melting
* <p />
* <p>
* Damage: 1
*/
MELTING,
/**
* Damage caused by direct exposure to lava
* <p />
* <p>
* Damage: 4
*/
LAVA,
/**
* Damage caused by running out of air while in water
* <p />
* <p>
* Damage: 2
*/
DROWNING,
/**
* Damage caused by being in the area when a block explodes.
* <p />
* <p>
* Damage: variable
*/
BLOCK_EXPLOSION,
/**
* Damage caused by being in the area when an entity, such as a Creeper, explodes.
* <p />
* <p>
* Damage: variable
*/
ENTITY_EXPLOSION,
/**
* Damage caused by falling into the void
* <p />
* <p>
* Damage: 4 for players
*/
VOID,
/**
* Damage caused by being struck by lightning
* <p />
* <p>
* Damage: 5
*/
LIGHTNING,
/**
* Damage caused by committing suicide using the command "/kill"
* <p />
* <p>
* Damage: 1000
*/
SUICIDE,
/**
* Damage caused by starving due to having an empty hunger bar
* <p />
* <p>
* Damage: 1
*/
STARVATION,
/**
* Damage caused due to an ongoing poison effect
* <p />
* <p>
* Damage: 1
*/
POISON,
/**
* Damage caused by being hit by a damage potion or spell
* <p />
* <p>
* Damage: variable
*/
MAGIC,
@@ -182,21 +182,21 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
WITHER,
/**
* Damage caused by being hit by a falling block which deals damage
* <p />
* <p>
* <b>Note:</b> Not every block deals damage
* <p />
* <p>
* Damage: variable
*/
FALLING_BLOCK,
/**
* Damage caused in retaliation to another attack by the Thorns enchantment.
* <p />
* <p>
* Damage: 1-4 (Thorns)
*/
THORNS,
/**
* Custom damage.
* <p />
* <p>
* Damage: variable
*/
CUSTOM

View File

@@ -30,7 +30,7 @@ public class EntityDeathEvent extends EntityEvent {
/**
* Gets how much EXP should be dropped from this death.
* <p />
* <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.
*
@@ -42,7 +42,7 @@ public class EntityDeathEvent extends EntityEvent {
/**
* Sets how much EXP should be dropped from this death.
* <p />
* <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.
*

View File

@@ -7,7 +7,7 @@ import org.bukkit.event.HandlerList;
/**
* Called when a non-player entity is about to teleport because it is in contact with a portal
* <p />
* <p>
* For players see {@link org.bukkit.event.player.PlayerPortalEvent PlayerPortalEvent}
*/
public class EntityPortalEvent extends EntityTeleportEvent {

View File

@@ -7,7 +7,7 @@ import org.bukkit.util.Vector;
/**
* Called before an entity exits a portal.
* <p />
* <p>
* This event allows you to modify the velocity of the entity after they
* have successfully exeted the portal.
*/

View File

@@ -51,7 +51,7 @@ public class EntityTargetEvent extends EntityEvent implements Cancellable {
* Set the entity that you want the mob to target instead.
* It is possible to be null, null will cause the entity to be
* target-less.
* <p />
* <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

View File

@@ -19,7 +19,7 @@ public class EntityTargetLivingEntityEvent extends EntityTargetEvent{
* Set the Entity that you want the mob to target.
* It is possible to be null, null will cause the entity to be
* target-less.
* <p />
* <p>
* Must be a LivingEntity, or null
*
* @param target The entity to target

View File

@@ -24,7 +24,7 @@ public class FoodLevelChangeEvent extends EntityEvent implements Cancellable {
/**
* Gets the resultant food level that the entity involved in this event should be set to.
* <p />
* <p>
* Where 20 is a full food bar and 0 is an empty one.
*
* @return The resultant food level

View File

@@ -56,7 +56,7 @@ public class PlayerDeathEvent extends EntityDeathEvent {
/**
* Gets how much EXP the Player should have at respawn.
* <p />
* <p>
* This does not indicate how much EXP should be dropped, please see
* {@link #getDroppedExp()} for that.
*
@@ -68,7 +68,7 @@ public class PlayerDeathEvent extends EntityDeathEvent {
/**
* Sets how much EXP the Player should have at respawn.
* <p />
* <p>
* This does not indicate how much EXP should be dropped, please see
* {@link #setDroppedExp(int)} for that.
*
@@ -116,7 +116,7 @@ public class PlayerDeathEvent extends EntityDeathEvent {
/**
* Gets if the Player should keep all EXP at respawn.
* <p />
* <p>
* This flag overrides other EXP settings
*
* @return True if Player should keep all pre-death exp
@@ -127,7 +127,7 @@ public class PlayerDeathEvent extends EntityDeathEvent {
/**
* Sets if the Player should keep all EXP at respawn.
* <p />
* <p>
* This overrides all other EXP settings
*
* @param keepLevel True to keep all current value levels

View File

@@ -102,7 +102,7 @@ public class PlayerEggThrowEvent extends PlayerEvent {
/**
* Get the number of mob hatches from the egg. By default the number
* will be he number the server would've done
* <p />
* <p>
* 7/8 chance of being 0
* 31/256 ~= 1/8 chance to be 1
* 1/256 chance to be 4
@@ -115,7 +115,7 @@ public class PlayerEggThrowEvent extends PlayerEvent {
/**
* Change the number of mobs coming out of the hatched egg
* <p />
* <p>
* The boolean hatching will override this number.
* Ie. If hatching = false, this number will not matter
*

View File

@@ -63,7 +63,7 @@ public class PlayerFishEvent extends PlayerEvent implements Cancellable {
/**
* Gets the amount of experience received when fishing.
* <p />
* <p>
* Note: This value has no default effect unless the event state is {@link State#CAUGHT_FISH}.
*
* @return the amount of experience to drop
@@ -74,7 +74,7 @@ public class PlayerFishEvent extends PlayerEvent implements Cancellable {
/**
* Sets the amount of experience received when fishing.
* <p />
* <p>
* Note: This value has no default effect unless the event state is {@link State#CAUGHT_FISH}.
*
* @param amount the amount of experience to drop

View File

@@ -54,7 +54,7 @@ public class PlayerInteractEvent extends PlayerEvent implements Cancellable {
/**
* Sets the cancellation state of this event. A canceled event will not
* be executed in the server, but will still pass to other plugins
* <p />
* <p>
* Canceling this event will prevent use of food (player won't lose the
* food item), prevent bows/snowballs/eggs from firing, etc. (player won't
* lose the ammo)

View File

@@ -23,7 +23,7 @@ public class PlayerMoveEvent extends PlayerEvent implements Cancellable {
/**
* Gets the cancellation state of this event. A cancelled event will not
* be executed in the server, but will still pass to other plugins
* <p />
* <p>
* If a move or teleport event is cancelled, the player will be moved or
* teleported back to the Location as defined by getFrom(). This will not
* fire an event
@@ -37,7 +37,7 @@ public class PlayerMoveEvent extends PlayerEvent implements Cancellable {
/**
* Sets the cancellation state of this event. A cancelled event will not
* be executed in the server, but will still pass to other plugins
* <p />
* <p>
* If a move or teleport event is cancelled, the player will be moved or
* teleported back to the Location as defined by getFrom(). This will not
* fire an event

View File

@@ -6,7 +6,7 @@ import org.bukkit.generator.BlockPopulator;
/**
* Thrown when a new chunk has finished being populated.
* <p />
* <p>
* If your intent is to populate the chunk using this event, please see {@link BlockPopulator}
*/
public class ChunkPopulateEvent extends ChunkEvent {