From 5389f2a46cdc1307dfcd2ce178f94406e5f0f8de Mon Sep 17 00:00:00 2001 From: Poslovitch Date: Mon, 14 Aug 2017 17:43:08 +0200 Subject: [PATCH 1/8] Documented Alloy --- .../Slimefun/Objects/SlimefunItem/Alloy.java | 33 ++++++++++++++++--- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/Alloy.java b/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/Alloy.java index d12d23265..5efc2b40b 100644 --- a/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/Alloy.java +++ b/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/Alloy.java @@ -6,14 +6,37 @@ import me.mrCookieSlime.Slimefun.Objects.Category; import org.bukkit.inventory.ItemStack; +/** + * Represents an alloy, obtainable using the {@code SMELTERY}. + *

+ * An alloy is generally made up of several minerals. + * As an example, {@code BRASS_INGOT} is made up of {@code COPPER_DUST}, {@code ZINC_DUST} and {@code COPPER_INGOT}. + * + * @since 4.0 + */ public class Alloy extends SlimefunItem { - public Alloy(ItemStack item, String name, ItemStack[] recipe) { - super(Categories.RESOURCES, item, name, RecipeType.SMELTERY, recipe); + /** + * Constructs an Alloy automatically bound to {@code Categories.RESOURCES}. + * + * @param item the item corresponding to this Alloy + * @param id the id of this Alloy + * @param recipe the recipe to obtain this Alloy in the Smeltery + */ + public Alloy(ItemStack item, String id, ItemStack[] recipe) { + super(Categories.RESOURCES, item, id, RecipeType.SMELTERY, recipe); } - - public Alloy(Category category, ItemStack item, String name, ItemStack[] recipe) { - super(category, item, name, RecipeType.SMELTERY, recipe); + + /** + * Constructs an Alloy with a definable {@link Category}. + * + * @param category the category to bind this Alloy to + * @param item the item corresponding to this Alloy + * @param id the id of this Alloy + * @param recipe the recipe to obtain this Alloy in the Smeltery + */ + public Alloy(Category category, ItemStack item, String id, ItemStack[] recipe) { + super(category, item, id, RecipeType.SMELTERY, recipe); } } From 00ed41fcbeb50a4ac3e0da6f495511f200a19bf9 Mon Sep 17 00:00:00 2001 From: Poslovitch Date: Mon, 14 Aug 2017 17:43:26 +0200 Subject: [PATCH 2/8] Documented UnregisterReason --- .../Objects/SlimefunItem/UnregisterReason.java | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/UnregisterReason.java b/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/UnregisterReason.java index 4ccce63db..241076845 100644 --- a/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/UnregisterReason.java +++ b/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/UnregisterReason.java @@ -1,8 +1,22 @@ package me.mrCookieSlime.Slimefun.Objects.SlimefunItem; +/** + * Defines how a block handled by Slimefun is being unregistered. + *

+ * It is notably used by {@link me.mrCookieSlime.Slimefun.Objects.SlimefunBlockHandler#onBreak(org.bukkit.entity.Player, org.bukkit.block.Block, SlimefunItem, UnregisterReason)}. + * + * @since 4.0 + */ public enum UnregisterReason { + /** + * An explosion destroys the block. + */ EXPLODE, - PLAYER_BREAK; + + /** + * A player breaks the block. + */ + PLAYER_BREAK } From a6fcd5146b641e7294e679c183bf92a8179ea7be Mon Sep 17 00:00:00 2001 From: Poslovitch Date: Mon, 14 Aug 2017 17:43:37 +0200 Subject: [PATCH 3/8] Documented VanillaItem --- .../Objects/SlimefunItem/VanillaItem.java | 24 ++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/VanillaItem.java b/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/VanillaItem.java index 3355dba1c..e4ca5f0f9 100644 --- a/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/VanillaItem.java +++ b/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/VanillaItem.java @@ -5,9 +5,27 @@ import org.bukkit.inventory.ItemStack; import me.mrCookieSlime.Slimefun.Lists.RecipeType; import me.mrCookieSlime.Slimefun.Objects.Category; +/** + * Represents a vanilla item that is overridden by Slimefun (like {@code ELYTRA}). + *

+ * A VanillaItem uses a non-modified ItemStack (no display name neither lore). + * When a VanillaItem gets disabled, its {@link SlimefunItem.State} goes on {@code State.VANILLA} which automatically + * replace it in the recipes by its vanilla equivalent. + * + * @since 4.0 + */ public class VanillaItem extends SlimefunItem { - - public VanillaItem(Category category, ItemStack item, String name, RecipeType recipeType, ItemStack[] recipe) { - super(category, item, name, recipeType, recipe); + + /** + * Constructs a VanillaItem. + * + * @param category the category to bind this VanillaItem to + * @param item the item corresponding to this VanillaItem + * @param id the id of this VanillaItem + * @param recipeType the type of the recipe to obtain this VanillaItem + * @param recipe the recipe to obtain this VanillaItem + */ + public VanillaItem(Category category, ItemStack item, String id, RecipeType recipeType, ItemStack[] recipe) { + super(category, item, id, recipeType, recipe); } } From 4b284a30052773b6e5635f5c05bba37100f17b30 Mon Sep 17 00:00:00 2001 From: Poslovitch Date: Mon, 14 Aug 2017 18:15:59 +0200 Subject: [PATCH 4/8] Fixed VanillaItem since version --- .../Slimefun/Objects/SlimefunItem/VanillaItem.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/VanillaItem.java b/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/VanillaItem.java index e4ca5f0f9..946e86185 100644 --- a/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/VanillaItem.java +++ b/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/VanillaItem.java @@ -12,7 +12,7 @@ import me.mrCookieSlime.Slimefun.Objects.Category; * When a VanillaItem gets disabled, its {@link SlimefunItem.State} goes on {@code State.VANILLA} which automatically * replace it in the recipes by its vanilla equivalent. * - * @since 4.0 + * @since 4.1.6 */ public class VanillaItem extends SlimefunItem { From 6eecee0eae43b2af33d5fa5361744a477ab27239 Mon Sep 17 00:00:00 2001 From: Poslovitch Date: Mon, 14 Aug 2017 18:16:09 +0200 Subject: [PATCH 5/8] Documented WikiSetup --- src/me/mrCookieSlime/Slimefun/Setup/WikiSetup.java | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/me/mrCookieSlime/Slimefun/Setup/WikiSetup.java b/src/me/mrCookieSlime/Slimefun/Setup/WikiSetup.java index 7d57c116a..a9ac22381 100644 --- a/src/me/mrCookieSlime/Slimefun/Setup/WikiSetup.java +++ b/src/me/mrCookieSlime/Slimefun/Setup/WikiSetup.java @@ -2,8 +2,16 @@ package me.mrCookieSlime.Slimefun.Setup; import me.mrCookieSlime.Slimefun.api.Slimefun; +/** + * Setups the official Wiki links. + * + * @since 4.1.2 + */ public class WikiSetup { + /** + * Setups the official Wiki links. + */ public static void setup() { // Weapons From 1617c76d9df2455347b361020047bf88e0fa14cb Mon Sep 17 00:00:00 2001 From: Poslovitch Date: Tue, 15 Aug 2017 00:06:48 +0200 Subject: [PATCH 6/8] Documented SlimefunItem.State --- .../Objects/SlimefunItem/SlimefunItem.java | 22 ++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/SlimefunItem.java b/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/SlimefunItem.java index 767ad1d93..40992f8a6 100644 --- a/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/SlimefunItem.java +++ b/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/SlimefunItem.java @@ -64,12 +64,28 @@ public class SlimefunItem { EnergyTicker energy; public String hash; - State state; - + private State state; + + /** + * Defines whether a SlimefunItem is enabled, disabled or fall-back to its vanilla behavior. + * + * @since 4.1.10 + */ public enum State { + /** + * This SlimefunItem is enabled. + */ ENABLED, + + /** + * This SlimefunItem is disabled and is not a {@link VanillaItem}. + */ DISABLED, - VANILLA; + + /** + * This SlimefunItem is fall-back to its vanilla behavior, because it is disabled and is a {@link VanillaItem}. + */ + VANILLA } int month = -1; From 39d77b5eb5e175877bbfa1005b4d4c622a015cda Mon Sep 17 00:00:00 2001 From: Poslovitch Date: Tue, 15 Aug 2017 16:37:25 +0200 Subject: [PATCH 7/8] Documented Slimefun (except GuideHandler related) ; deprecated #addDescription() in favor of #addHint() --- .../mrCookieSlime/Slimefun/api/Slimefun.java | 188 +++++++++++++++++- 1 file changed, 177 insertions(+), 11 deletions(-) diff --git a/src/me/mrCookieSlime/Slimefun/api/Slimefun.java b/src/me/mrCookieSlime/Slimefun/api/Slimefun.java index 620e537fa..8e71abc1a 100644 --- a/src/me/mrCookieSlime/Slimefun/api/Slimefun.java +++ b/src/me/mrCookieSlime/Slimefun/api/Slimefun.java @@ -19,39 +19,99 @@ import me.mrCookieSlime.Slimefun.Objects.SlimefunItem.SlimefunItem.State; import me.mrCookieSlime.Slimefun.Objects.SlimefunItem.VanillaItem; import me.mrCookieSlime.Slimefun.Setup.Messages; +/** + * Provides a few convenience methods. + * + * @since 4.0 + */ public class Slimefun { - public static Map> guide_handlers = new HashMap>(); - public static List guide_handlers2 = new ArrayList(); + public static Map> guide_handlers = new HashMap<>(); + public static List guide_handlers2 = new ArrayList<>(); + /** + * Instance of the GPSNetwork. + */ private static GPSNetwork gps = new GPSNetwork(); + /** + * Whether EmeraldEnchants is enabled or not. + */ public static boolean emeraldenchants = false; - public static List current_categories = new ArrayList(); + /** + * Lists all the registered categories. + */ + public static List current_categories = new ArrayList<>(); public static void registerGuideHandler(GuideHandler handler) { - List handlers = new ArrayList(); + List handlers = new ArrayList<>(); if (guide_handlers.containsKey(handler.getTier())) handlers = guide_handlers.get(handler.getTier()); handlers.add(handler); guide_handlers.put(handler.getTier(), handlers); guide_handlers2.add(handler); } + /** + * Returns the GPSNetwork instance. + * + * @return the GPSNetwork instance. + */ public static GPSNetwork getGPSNetwork() { return gps; } + /** + * Returns the value associated to this key for the SlimefunItem corresponding to this id. + * + * @param id the id of the SlimefunItem, not null + * @param key the key of the value to get, not null + * + * @return the value associated to the key for the SlimefunItem corresponding to the id, + * or null if it doesn't exist. + */ public static Object getItemValue(String id, String key) { - return SlimefunStartup.getItemCfg().getValue(id + "." + key); + return getItemConfig().getValue(id + "." + key); } + /** + * Sets a default value associated to this key for the SlimefunItem corresponding to this id. + * + * @param id the id of the SlimefunItem, not null + * @param key the key of the value to set, not null + * @param value the value to set, can be null + */ public static void setItemVariable(String id, String key, Object value) { - SlimefunStartup.getItemCfg().setDefaultValue(id + "." + key, value); + getItemConfig().setDefaultValue(id + "." + key, value); } + /** + * Returns the Config instance of Items.yml file. + *

+ * It calls {@code SlimefunStartup#getItemCfg()}. + * + * @return the Items.yml Config instance. + */ public static Config getItemConfig() { return SlimefunStartup.getItemCfg(); } + /** + * Registers this Research and automatically binds these ItemStacks to it. + *

+ * This convenience method spares from doing the code below: + * 

+     *     {@code
+     *		Research r = new Research(7, "Glowstone Armor", 3);
+     *		r.addItems(SlimefunItem.getByItem(SlimefunItems.GLOWSTONE_HELMET),
+	 *		           SlimefunItem.getByItem(SlimefunItems.GLOWSTONE_CHESTPLATE),
+	 *		           SlimefunItem.getByItem(SlimefunItems.GLOWSTONE_LEGGINGS),
+	 *		           SlimefunItem.getByItem(SlimefunItems.GLOWSTONE_BOOTS));
+	 *		r.register();
+	 *     }*
+     *
+ + * @param research the research to register, not null + * @param items the items to bind, not null + */ public static void registerResearch(Research research, ItemStack... items) { for (ItemStack item: items) { research.addItems(SlimefunItem.getByItem(item)); @@ -59,6 +119,16 @@ public class Slimefun { research.register(); } + /** + * Checks if this player can use this item. + * + * @param p the player to check, not null + * @param item the item to check, not null + * @param message whether a message should be sent to the player or not + * + * @return true if the item is a SlimefunItem, enabled, researched and if the player has the permission to use it, + * false otherwise. + */ public static boolean hasUnlocked(Player p, ItemStack item, boolean message) { SlimefunItem sfItem = SlimefunItem.getByItem(item); State state = SlimefunItem.getState(item); @@ -80,6 +150,16 @@ public class Slimefun { else return false; } + /** + * Checks if this player can use this item. + * + * @param p the player to check, not null + * @param sfItem the item to check, not null + * @param message whether a message should be sent to the player or not + * + * @return true if the item is enabled, researched and the player has the permission to use it, + * false otherwise. + */ public static boolean hasUnlocked(Player p, SlimefunItem sfItem, boolean message) { if (isEnabled(p, sfItem, message) && hasPermission(p, sfItem, message)) { if (sfItem.getResearch() == null) return true; @@ -92,6 +172,16 @@ public class Slimefun { return false; } + /** + * Checks if this player has the permission to use this item. + * + * @param p the player to check, not null + * @param item the item to check, null returns true + * @param message whether a message should be sent to the player or not + * + * @return true if the item is not null and if the player has the permission to use it, + * false otherwise. + */ public static boolean hasPermission(Player p, SlimefunItem item, boolean message) { if (item == null) return true; else if (SlimefunStartup.getItemCfg().getString(item.getName() + ".required-permission").equalsIgnoreCase("")) return true; @@ -102,6 +192,16 @@ public class Slimefun { } } + /** + * Checks if this item is enabled in the world of this player. + * + * @param p the player to get the world he is in, not null + * @param item the item to check, not null + * @param message whether a message should be sent to the player or not + * + * @return true if the item is a SlimefunItem and is enabled in the world the player is in, + * false otherwise. + */ public static boolean isEnabled(Player p, ItemStack item, boolean message) { String world = p.getWorld().getName(); SlimefunItem sfItem = SlimefunItem.getByItem(item); @@ -123,6 +223,16 @@ public class Slimefun { else return true; } + /** + * Checks if this item is enabled in the world of this player. + * + * @param p the player to get the world he is in, not null + * @param sfItem the item to check, not null + * @param message whether a message should be sent to the player or not + * + * @return true if the item is enabled in the world the player is in, + * false otherwise. + */ public static boolean isEnabled(Player p, SlimefunItem sfItem, boolean message) { String world = p.getWorld().getName(); if (SlimefunStartup.getWhitelist().contains(world + ".enabled")) { @@ -142,45 +252,101 @@ public class Slimefun { else return true; } + /** + * Lists all the IDs of the enabled items. + * + * @return the list of all the IDs of the enabled items. + */ public static List listIDs() { - List ids = new ArrayList(); - + List ids = new ArrayList<>(); for (SlimefunItem item: SlimefunItem.list()) { ids.add(item.getName()); } - return ids; } + /** + * Returns a list of all the ItemStacks representing the registered categories. + * + * @return the list of the display items of all the registered categories. + * @see #current_categories + */ public static List listCategories() { - List items = new ArrayList(); + List items = new ArrayList<>(); for (Category c: Category.list()) { items.add(c.getItem()); } return items; } + /** + * Binds this description to the SlimefunItem corresponding to this id. + * + * @param id the id of the SlimefunItem, not null + * @param description the description, not null + * + * @deprecated As of 4.1.10, renamed to {@link #addHint(String, String...)} for better name convenience. + */ + @Deprecated public static void addDescription(String id, String... description) { getItemConfig().setDefaultValue(id + ".description", Arrays.asList(description)); } + /** + * Binds this hint to the SlimefunItem corresponding to this id. + * + * @param id the id of the SlimefunItem, not null + * @param hint the hint, not null + * + * @since 4.1.10, rename of {@link #addDescription(String, String...)}. + */ + public static void addHint(String id, String... hint) { + getItemConfig().setDefaultValue(id + ".hint", Arrays.asList(hint)); + } + + /** + * Binds this YouTube link to the SlimefunItem corresponding to this id. + * + * @param id the id of the SlimefunItem, not null + * @param link the link of the YouTube video, not null + */ public static void addYoutubeVideo(String id, String link) { getItemConfig().setDefaultValue(id + ".youtube", link); } + /** + * Binds this link as a Wiki page to the SlimefunItem corresponding to this id. + * + * @param id the id of the SlimefunItem, not null + * @param link the link of the Wiki page, not null + */ public static void addWikiPage(String id, String link) { getItemConfig().setDefaultValue(id + ".wiki", link); } + /** + * Convenience method to simplify binding an official Wiki page to the SlimefunItem corresponding to this id. + * + * @param id the id of the SlimefunItem, not null + * @param page the ending of the link corresponding to the page, not null + */ public static void addOfficialWikiPage(String id, String page) { addWikiPage(id, "https://github.com/TheBusyBiscuit/Slimefun4/wiki/" + page); } + /** + * Returns whether EmeraldEnchants is enabled or not. + *

+ * It can be directly accessed by {@link #emeraldenchants}. + * + * @return true if EmeraldEnchants is enabled, + * false otherwise. + */ public static boolean isEmeraldEnchantsInstalled() { return emeraldenchants; } public static List getGuideHandlers(int tier) { - return guide_handlers.containsKey(tier) ? guide_handlers.get(tier): new ArrayList(); + return guide_handlers.containsKey(tier) ? guide_handlers.get(tier): new ArrayList<>(); } } \ No newline at end of file From 4a7ebf937736966cb07834238ab7fb86555caf71 Mon Sep 17 00:00:00 2001 From: Poslovitch Date: Tue, 15 Aug 2017 16:56:01 +0200 Subject: [PATCH 8/8] Made EnderTalisman use the new addHint instead of addDescription --- .../Slimefun/Objects/SlimefunItem/EnderTalisman.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/EnderTalisman.java b/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/EnderTalisman.java index 6f870768c..5624d4441 100644 --- a/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/EnderTalisman.java +++ b/src/me/mrCookieSlime/Slimefun/Objects/SlimefunItem/EnderTalisman.java @@ -22,7 +22,7 @@ public class EnderTalisman extends SlimefunItem { this.suffix = parent.getSuffix(); this.effects = parent.getEffects(); this.chance = parent.getChance(); - Slimefun.addDescription("ENDER_" + parent.getName(), "&eEnder Talismans have the advantage", "&eof still working while they", "&eare in your Ender Chest"); + Slimefun.addHint("ENDER_" + parent.getName(), "&eEnder Talismans have the advantage", "&eof still working while they", "&eare in your Ender Chest"); } public PotionEffect[] getEffects() { return this.effects; }