Added and Fixed lots of JavaDocs

This commit is contained in:
Sn0wStorm
2019-11-25 22:16:16 +01:00
parent c287b6350f
commit 16c03f9da1
32 changed files with 513 additions and 308 deletions
+64 -53
View File
@@ -18,15 +18,22 @@ import org.jetbrains.annotations.Nullable;
import java.util.List;
/**
* Convenience methods to get common objects or do common things
* Convenience methods to get common objects or do common things.
* <p>Contains shortcuts and collects of some of the main functions of this Plugin
*
* <p>Next to this there are lots of public Methods in many Objects
* like Brew, Barrel, BCauldron, BRecipe, etc
* <p>In the api package, you can also find custom Events.
*/
public class BreweryApi {
/**
* Remove any data that this Plugin may associate with the given Block
* Currently Cauldrons and Barrels (Cauldron, Wood, Woodstairs, Fence, Sign)
* Does not remove any actual Blocks
* Returns true if anything was removed
* Remove any data that this Plugin may associate with the given Block.
* <p>Currently Cauldrons and Barrels (Cauldron, Wood, Woodstairs, Fence, Sign)
* <p>Does not remove any actual Blocks
* <p>Returns true if anything was removed
*
* @return true if anything was removed
*/
public static boolean removeAny(Block block) {
if (removeCauldron(block)) return true;
@@ -34,8 +41,8 @@ public class BreweryApi {
}
/**
* Like removeAny() but removes data as if the given player broke the Block
* Currently only makes a difference for Logging
* <p>Like removeAny() but removes data as if the given player broke the Block.
* <p>Currently only makes a difference for Logging
*/
public static boolean removeAnyByPlayer(Block block, Player player) {
if (removeCauldron(block)) return true;
@@ -47,17 +54,20 @@ public class BreweryApi {
// # # # # # Player # # # # #
// # # # # # # # # # # # #
/**
* Get the BPlayer for the given Player, containing drunkeness and hangover data.
*/
public static BPlayer getBPlayer(Player player) {
return BPlayer.get(player);
}
/**
* Set the Players drunkeness state
* Set the Players drunkeness state.
*
* @param player The Player to set the drunkeness on
* @param drunkeness The amount of drunkeness 0-100 to apply to the player
* @param quality The Quality 1-10 the drunkeness of the player should have
* zero Quality keeps the players current quality
* @param quality The Quality 1-10 the drunkeness of the player should have.
* <br>zero Quality keeps the players current quality
*/
public static void setPlayerDrunk(Player player, int drunkeness, int quality) {
if (drunkeness < 0) {
@@ -100,10 +110,10 @@ public class BreweryApi {
// # # # # # # # # # # # #
/**
* Get a Brew from an ItemStack
* Reads the Brew data from the saved data on the item
* Checks if item is actually a Brew
* Returns null if item is not a Brew
* Get a Brew from an ItemStack.
* <p>Reads the Brew data from the saved data on the item
* <p>Checks if item is actually a Brew
* <p>Returns null if item is not a Brew
*/
@Nullable
public static Brew getBrew(ItemStack item) {
@@ -111,10 +121,10 @@ public class BreweryApi {
}
/**
* Get a Brew from an ItemMeta
* Reads the Brew data from the saved data in the Meta
* Checks if meta has a Brew saved
* Returns null if meta is not a Brew
* Get a Brew from an ItemMeta.
* <p>Reads the Brew data from the saved data in the Meta
* <p>Checks if meta has a Brew saved
* <p>Returns null if meta is not a Brew
*/
@Nullable
public static Brew getBrew(ItemMeta meta) {
@@ -123,14 +133,14 @@ public class BreweryApi {
/**
* Performant way to check if an item is a brew.
* Does not give any guarantees that getBrew() will return notnull for this item, i.e. if it is a brew but couldn't be loaded
* <p>Does not give any guarantees that getBrew() will return notnull for this item, i.e. if it is a brew but couldn't be loaded
*/
public static boolean isBrew(ItemStack item) {
return Brew.isBrew(item);
}
/**
* Create a Brew from the given Recipe
* Create a Brew from the given Recipe.
*
* @param recipe The Recipe to create a brew from
* @return The Brew that was created. Can use brew.createItem() to get an ItemStack
@@ -145,9 +155,9 @@ public class BreweryApi {
// # # # # # # # # # # # #
/**
* Get a Barrel from a Block
* May be any Wood, Fence, Sign that is part of a Barrel
* Returns null if block is not part of a Barrel
* Get a Barrel from a Block.
* <p>May be any Wood, Fence, Sign that is part of a Barrel
* <p>Returns null if block is not part of a Barrel
*/
@Nullable
public static Barrel getBarrel(Block block) {
@@ -155,9 +165,9 @@ public class BreweryApi {
}
/**
* Get the Inventory of a Block part of a Barrel
* May be any Wood, Fence or Sign that is part of a Barrel
* Returns null if block is not part of a Barrel
* Get the Inventory of a Block part of a Barrel.
* <p>May be any Wood, Fence or Sign that is part of a Barrel
* <p>Returns null if block is not part of a Barrel
*/
@Nullable
public static Inventory getBarrelInventory(Block block) {
@@ -169,7 +179,7 @@ public class BreweryApi {
}
/**
* Remove any Barrel that this Block may be Part of
* Remove any Barrel that this Block may be Part of.
* Does not remove any actual Block
*
* @param block The Block thats part of the barrel, potions will drop there
@@ -181,7 +191,7 @@ public class BreweryApi {
}
/**
* Remove any Barrel that this Block may be Part of, as if broken by the Player
* Remove any Barrel that this Block may be Part of, as if broken by the Player.
* Does not remove any actual Block from the World
*
* @param block The Block thats part of the barrel, potions will drop there
@@ -203,8 +213,8 @@ public class BreweryApi {
// # # # # # # # # # # # #
/**
* Get a BCauldron from a Block
* Returns null if block is not a BCauldron
* Get a BCauldron from a Block.
* <p>Returns null if block is not a BCauldron
*/
@Nullable
public static BCauldron getCauldron(Block block) {
@@ -212,9 +222,9 @@ public class BreweryApi {
}
/**
* Remove any data associated with a Cauldron at that given Block
* Returns true if a Cauldron was removed
* Does not remove the Block from the World
* Remove any data associated with a Cauldron at that given Block.
* <p>Returns true if a Cauldron was removed
* <p>Does not remove the Block from the World
*/
public static boolean removeCauldron(Block block) {
return BCauldron.remove(block);
@@ -226,9 +236,9 @@ public class BreweryApi {
// # # # # # # # # # # # #
/**
* Get a BRecipe by its name
* The name is the middle one of the three if three are set in the config
* Returns null if recipe with that name does not exist
* Get a BRecipe by its name.
* <p>The name is the middle one of the three if three are set in the config
* <p>Returns null if recipe with that name does not exist
*/
@Nullable
public static BRecipe getRecipe(String name) {
@@ -237,15 +247,15 @@ public class BreweryApi {
/**
* Add a New Recipe.
* Brews can be made out of this Recipe.
* The recipe can be changed or removed later.
* <p>Brews can be made out of this Recipe.
* <p>The recipe can be changed or removed later.
*
* @param recipe The Recipe to add
* @param saveForever Not Implemented yet
* If the recipe should be saved forever, even after the Server restarts
* If True: Recipe will be saved until removed manually
* If False: Recipe will be removed when the Server restarts, existing potions using
* this Recipe will become bad after continued aging, if the recipe is not added again.
* @param saveForever Not Implemented yet.
* <br>If the recipe should be saved forever, even after the Server restarts
* <br>If True: Recipe will be saved until removed manually
* <br>If False: Recipe will be removed when the Server restarts, existing potions using
* <br>this Recipe will become bad after continued aging, if the recipe is not added again.
*/
public static void addRecipe(BRecipe recipe, boolean saveForever) {
//recipe.setSaveInData(saveForever);
@@ -258,7 +268,7 @@ public class BreweryApi {
/**
* Removes a Recipe from the List of all Recipes.
* This can also remove Recipes that were loaded from config, though these will be readded when reloading the config
* <p>This can also remove Recipes that were loaded from config, though these will be readded when reloading the config
*
* @param name The name of the recipe to remove
* @return The Recipe that was removed, null if none was removed
@@ -296,8 +306,8 @@ public class BreweryApi {
// # # # # # # # # # # # #
/**
* Get A BCauldronRecipe by its name
* Returns null if recipe with that name does not exist
* Get A BCauldronRecipe by its name.
* <p>Returns null if recipe with that name does not exist
*/
@Nullable
public static BCauldronRecipe getCauldronRecipe(String name) {
@@ -306,14 +316,14 @@ public class BreweryApi {
/**
* Add a New Cauldron Recipe.
* Base Brews coming out of the Cauldron can be made from this recipe
* The recipe can be changed or removed later.
* <p>Base Brews coming out of the Cauldron can be made from this recipe
* <p>The recipe can be changed or removed later.
*
* @param recipe The Cauldron Recipe to add
* @param saveForever Not Implemented yet
* If the recipe should be saved forever, even after the Server restarts
* If True: Recipe will be saved until removed manually
* If False: Recipe will be removed when the Server restarts
* @param saveForever Not Implemented yet.
* <br>If the recipe should be saved forever, even after the Server restarts
* <br>If True: Recipe will be saved until removed manually
* <br>If False: Recipe will be removed when the Server restarts
*/
public static void addCauldronRecipe(BCauldronRecipe recipe, boolean saveForever) {
//recipe.setSaveInData(saveForever);
@@ -326,7 +336,8 @@ public class BreweryApi {
/**
* Removes a Cauldron Recipe from the List of all Cauldron Recipes.
* This can also remove Cauldron Recipes that were loaded from config, though these will be readded when reloading the config
* <p>This can also remove Cauldron Recipes that were loaded from config,
* though these will be readded when reloading the config
*
* @param name The name of the cauldron recipe to remove
* @return The Cauldron Recipe that was removed, null if none was removed
@@ -7,17 +7,15 @@ import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
import java.util.List;
/**
* The Brewery Config was reloaded
* The Brewery Config was reloaded.
*/
public class ConfigLoadEvent extends Event {
private static final HandlerList handlers = new HandlerList();
/**
* One of the things one might need to do after reloading
* Removes a Recipe, can also remove config recipes
* Removes a Recipe, can also remove config recipes.
* One of the things one might need to do after reloading.
*
* @param name Name of the Recipe to remove
* @return The Recipe that was removed, null if none was removed
@@ -27,8 +25,8 @@ public class ConfigLoadEvent extends Event {
}
/**
* One of the things one might need to do after reloading
* Removes a Cauldron Recipe, can also remove config recipes
* Removes a Cauldron Recipe, can also remove config recipes.
* One of the things one might need to do after reloading.
*
* @param name Name of the Cauldron Recipe to remove
* @return The Cauldron Recipe that was removed, null if none was removed
@@ -15,9 +15,9 @@ import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Player adding an ingredient to a cauldron
* Always one item added at a time
* If needed use the caudrons add method to manually add more Items
* Player adding an ingredient to a cauldron.
* <p>Always one item added at a time.
* <p>If needed use the caudrons add method to manually add more Items
*/
public class IngedientAddEvent extends PlayerEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
@@ -46,17 +46,17 @@ public class IngedientAddEvent extends PlayerEvent implements Cancellable {
/**
* The Recipe item that matches the ingredient.
* This might not be the only recipe item that will match the ingredient
* Will be recalculated if the Ingredient is changed with the setIngredient Method
* <p>This might not be the only recipe item that will match the ingredient
* <p>Will be recalculated if the Ingredient is changed with the setIngredient Method
*/
public RecipeItem getRecipeItem() {
return rItem;
}
/**
* Get the item currently being added to the cauldron by the player
* Can be changed directly (mutable) or with the setter Method
* The amount is ignored and always one added
* Get the item currently being added to the cauldron by the player.
* <p>Can be changed directly (mutable) or with the setter Method
* <p>The amount is ignored and always one added
*
* @return The item being added
*/
@@ -65,10 +65,10 @@ public class IngedientAddEvent extends PlayerEvent implements Cancellable {
}
/**
* Set the ingredient added to the cauldron to something else
* Will always be accepted, even when not in a recipe or the cooked lis
* The amount is ignored and always one added
* This also recalculates the recipeItem!
* Set the ingredient added to the cauldron to something else.
* <p>Will always be accepted, even when not in a recipe or the cooked lis
* <p>The amount is ignored and always one added
* <p>This also recalculates the recipeItem!
*
* @param ingredient The item to add instead
*/
@@ -79,15 +79,15 @@ public class IngedientAddEvent extends PlayerEvent implements Cancellable {
}
/**
* If the amount of the item in the players hand should be decreased
* Default true
* If the amount of the item in the players hand should be decreased.
* (Default true)
*/
public boolean willTakeItem() {
return takeItem;
}
/**
* Set if the amount of the item in the players hand should be decreased
* Set if the amount of the item in the players hand should be decreased.
*
* @param takeItem if the item amount in the hand should be decreased
*/
@@ -96,8 +96,8 @@ public class IngedientAddEvent extends PlayerEvent implements Cancellable {
}
/**
* Get the BlockData of the Cauldron
* May be null if the Cauldron does not exist anymore
* Get the BlockData of the Cauldron.
* <p>May be null if the Cauldron does not exist anymore
*
* @return The BlockData of the cauldron
*/
@@ -111,9 +111,9 @@ public class IngedientAddEvent extends PlayerEvent implements Cancellable {
}
/**
* Get the water fill level of the Cauldron
* 0 = empty, 1 = something in, 2 = full
* Can use BCauldron.EMPTY, BCauldron.SOME, BCauldron.FULL
* Get the water fill level of the Cauldron.
* <p>0 = empty, 1 = something in, 2 = full
* <p>Can use BCauldron.EMPTY, BCauldron.SOME, BCauldron.FULL
*
* @return The fill level as a byte 0-2
*/
@@ -127,7 +127,7 @@ public class IngedientAddEvent extends PlayerEvent implements Cancellable {
}
/**
* If the event is cancelled, no item will be added or taken from the player
* If the event is cancelled, no item will be added or taken from the player.
*/
@Override
public void setCancelled(boolean cancelled) {
@@ -13,7 +13,7 @@ import java.util.Objects;
/**
* The Player writes something in Chat or on a Sign and his words are distorted.
*
* This Event may be Async if the Chat Event is Async!
* <p>This Event may be Async if the Chat Event is Async!
*/
public class PlayerChatDistortEvent extends Event implements Cancellable {
private static final HandlerList handlers = new HandlerList();
@@ -11,8 +11,9 @@ import java.util.List;
/**
* A List of effects is applied to the player.
* This happens for various reasons like Alcohol level, Brew quality, Brew effects, etc.
* Can be changed or cancelled
* <p>This happens for various reasons like Alcohol level, Brew quality, Brew effects, etc.
*
* <p>Can be changed or cancelled
*/
public class PlayerEffectEvent extends PlayerEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
@@ -38,7 +39,7 @@ public class PlayerEffectEvent extends PlayerEvent implements Cancellable {
}
/**
* @return What type of effects are applied, sie EffectType
* @return What type of effects are applied, see EffectType
*/
public EffectType getEffectType() {
return effectType;
@@ -66,27 +67,30 @@ public class PlayerEffectEvent extends PlayerEvent implements Cancellable {
}
/**
* The Type of Effect, or why an effect is being added to the player.
*/
public enum EffectType {
/**
* The Alcohol level demands its toll.
* Regularly applied depending on the players alcohol level
* By default it is just one Confusion effect
* <p>Regularly applied depending on the players alcohol level
* <p>By default it is just one Confusion effect
*/
ALCOHOL,
/**
* Effects of a Brew are applied to the player (drinking the Brew)
* These depend on alcohol and quality of the brew
* Effects of a Brew are applied to the player (drinking the Brew).
* <p>These depend on alcohol and quality of the brew
*/
DRINK,
/**
* When drinking a Brew with low Quality, these effects are applied
* When drinking a Brew with low Quality, these effects are applied.
*/
QUALITY,
/**
* When logging in after drinking, Hangover Effects are applied
* When logging in after drinking, Hangover Effects are applied.
*/
HANGOVER
@@ -8,9 +8,9 @@ import org.bukkit.event.player.PlayerEvent;
import org.jetbrains.annotations.NotNull;
/**
* The player pukes (throws puke items to the ground)
* Those items can never be picked up and despawn after the time set in the config
* Number of items to drop can be changed with count
* The player pukes (throws puke items to the ground).
* <p>Those items can never be picked up and despawn after the time set in the config
* <p>Number of items to drop can be changed with count
*/
public class PlayerPukeEvent extends PlayerEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
@@ -25,14 +25,14 @@ public class PlayerPukeEvent extends PlayerEvent implements Cancellable {
}
/**
* @return The Amount of items being dropped this time
* Get the Amount of items being dropped this time
*/
public int getCount() {
return count;
}
/**
* @param count Set the amount of items being dropped this time
* Set the amount of items being dropped this time
*/
public void setCount(int count) {
this.count = count;
@@ -9,9 +9,9 @@ import org.bukkit.util.Vector;
import org.jetbrains.annotations.NotNull;
/**
* The Players movement is hindered because of drunkeness
* Called each time before pushing the Player with the Vector push 10 times
* The Push Vector can be changed or multiplied
* The Players movement is hindered because of drunkeness.
* <p>Called each time before pushing the Player with the Vector push 10 times
* <p>The Push Vector can be changed or multiplied
*/
public class PlayerPushEvent extends PlayerEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
@@ -29,12 +29,9 @@ public class PlayerPushEvent extends PlayerEvent implements Cancellable {
return bPlayer;
}
// The Vector in which direction and magnitude the player is Pushed
// Can be changed directly or through setPush
/**
* Get the Vector in which direction and magnitude the player is pushed
* Can be changed directly or through setPush
* Get the Vector in which direction and magnitude the player is pushed.
* <p>Can be changed directly or through setPush
*
* @return The current push vector
*/
@@ -43,7 +40,7 @@ public class PlayerPushEvent extends PlayerEvent implements Cancellable {
}
/**
* Set the Push vector
* Set the Push vector.
*
* @param push The new push vector, not null
*/
@@ -8,9 +8,9 @@ import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
/**
* A Player opens a Barrel by rightclicking it
* The PlayerInteractEvent on the Barrel may be cancelled. In that case this never gets called
* Can be cancelled to silently deny opening the Barrel
* A Player opens a Barrel by rightclicking it.
* <p>The PlayerInteractEvent on the Barrel may be cancelled. In that case this never gets called
* <p>Can be cancelled to silently deny opening the Barrel
*/
public class BarrelAccessEvent extends BarrelEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
@@ -26,7 +26,7 @@ public class BarrelAccessEvent extends BarrelEvent implements Cancellable {
/**
* Gets the Block that was actually clicked.
* For access Permissions getSpigot() should be used
* <p>For access Permissions getSpigot() should be used
*/
public Block getClickedBlock() {
return clickedBlock;
@@ -7,8 +7,8 @@ import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
/**
* Called when a Barrel is created by a Player by placing a Sign
* Cancelling this will silently fail the Barrel creation
* Called when a Barrel is created by a Player by placing a Sign.
* <p>Cancelling this will silently fail the Barrel creation
*/
public class BarrelCreateEvent extends BarrelEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
@@ -9,10 +9,10 @@ import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* A Barrel is being destroyed by something, may not be by a Player
* A BarrelRemoveEvent will be called after this, if this is not cancelled
* Use the BarrelRemoveEvent to monitor any and all barrels being removed in a non cancellable way
* Cancelling the Event will stop the barrel from being destroyed
* A Barrel is being destroyed by something, may not be by a Player.
* <p>A BarrelRemoveEvent will be called after this, if this is not cancelled
* <p>Use the BarrelRemoveEvent to monitor any and all barrels being removed in a non cancellable way
* <p>Cancelling the Event will stop the barrel from being destroyed
*/
public class BarrelDestroyEvent extends BarrelEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
@@ -82,6 +82,9 @@ public class BarrelDestroyEvent extends BarrelEvent implements Cancellable {
return handlers;
}
/**
* The Reason why the Barrel is being destroyed.
*/
public enum Reason {
/**
* A Player Broke the Barrel
@@ -5,7 +5,8 @@ import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
/**
* A Barrel is being removed. There may have been a BarrelDestroyEvent before this
* A Barrel is being removed.
* <p>There may have been a BarrelDestroyEvent before this.
* If not, Worldedit, other Plugins etc may be the cause for unexpected removal
*/
public class BarrelRemoveEvent extends BarrelEvent {
@@ -9,9 +9,9 @@ import org.bukkit.inventory.meta.ItemMeta;
import org.jetbrains.annotations.NotNull;
/**
* A Player Drinks a Brew
* The amount of alcohol and quality that will be added to the player can be get/set here
* If cancelled the drinking will fail silently
* A Player Drinks a Brew.
* <p>The amount of alcohol and quality that will be added to the player can be get/set here
* <p>If cancelled the drinking will fail silently
*/
public class BrewDrinkEvent extends BrewEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
@@ -19,6 +19,9 @@ public abstract class BrewEvent extends Event {
return brew;
}
/**
* Gets the Meta of the Item this Brew is attached to
*/
@NotNull
public ItemMeta getItemMeta() {
return meta;
@@ -9,10 +9,10 @@ import org.bukkit.inventory.meta.PotionMeta;
import org.jetbrains.annotations.NotNull;
/**
* A Brew has been created or modified
* Usually happens on Filling from cauldron, distilling and aging.
* Modifications to the Brew or the PotionMeta can be done now
* Cancelling reverts the Brew to the state it was before the modification
* A Brew has been created or modified.
* <p>Usually happens on filling from cauldron, distilling and aging.
* <p>Modifications to the Brew or the PotionMeta can be done now
* <p>Cancelling reverts the Brew to the state it was before the modification
*/
public class BrewModifyEvent extends BrewEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
@@ -25,11 +25,17 @@ public class BrewModifyEvent extends BrewEvent implements Cancellable {
this.type = type;
}
/**
* Get the Type of modification being applied to the Brew.
*/
@NotNull
public Type getType() {
return type;
}
/**
* Get the BrewLore to modify lore on the Brew
*/
@NotNull
public BrewLore getLore() {
return new BrewLore(getBrew(), (PotionMeta) getItemMeta());
@@ -42,7 +48,7 @@ public class BrewModifyEvent extends BrewEvent implements Cancellable {
/**
* Setting the Event cancelled cancels all modificatons to the brew.
* Modifications to the Brew or ItemMeta will not be applied
* <p>Modifications to the Brew or ItemMeta will not be applied
*/
@Override
public void setCancelled(boolean cancelled) {
@@ -60,13 +66,44 @@ public class BrewModifyEvent extends BrewEvent implements Cancellable {
return handlers;
}
/**
* The Type of Modification being applied to the Brew.
*/
public enum Type {
CREATE, // A new Brew is created with arbitrary ways, like the create command
FILL, // Filled from a Cauldron into a new Brew
DISTILL, // Distilled in the Brewing stand
AGE, // Aged in a Barrel
UNLABEL, // Unlabeling Brew with command
STATIC, // Making Brew static with command
UNKNOWN // Unknown modification, unused
/**
* A new Brew is created with arbitrary ways, like the create command.
* <p>Cancelling this will disallow the creation
*/
CREATE,
/**
* Filled from a Cauldron into a new Brew.
*/
FILL,
/**
* Distilled in the Brewing stand.
*/
DISTILL,
/**
* Aged in a Barrel.
*/
AGE,
/**
* Unlabeling Brew with command.
*/
UNLABEL,
/**
* Making Brew static with command.
*/
STATIC,
/**
* Unknown modification, unused.
*/
UNKNOWN
}
}