Merge pull request #397 from Poslovitch/documentation

Documentation - 1

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}.
+ * <p>
+ * 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);
 	}
 
 }

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

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;

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.
+ * <p>
+ * 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
 	
 }

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}).
+ * <p>
+ * 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.1.6
+ */
 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);
 	}
 }

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

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<Integer, List<GuideHandler>> guide_handlers = new HashMap<Integer, List<GuideHandler>>();
+	public static Map<Integer, List<GuideHandler>> guide_handlers = new HashMap<>();
-	public static List<GuideHandler> guide_handlers2 = new ArrayList<GuideHandler>();
+	public static List<GuideHandler> 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<Category> current_categories = new ArrayList<Category>();
+    /**
+     * Lists all the registered categories.
+     */
+	public static List<Category> current_categories = new ArrayList<>();
 
 	public static void registerGuideHandler(GuideHandler handler) {
-		List<GuideHandler> handlers = new ArrayList<GuideHandler>();
+		List<GuideHandler> 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.
+	 * <p>
+	 * 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.
+     * <p>
+     * This convenience method spares from doing the code below:
+     * <pre>
+     *     {@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();
+	 *     }*
+     * </pre>
+
+     * @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 <code>true</code> if the item is a SlimefunItem, enabled, researched and if the player has the permission to use it,
+	 *         <code>false</code> 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 <code>true</code> if the item is enabled, researched and the player has the permission to use it,
+	 *         <code>false</code> 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 <code>true</code>
+	 * @param  message  whether a message should be sent to the player or not
+	 *
+	 * @return <code>true</code> if the item is not null and if the player has the permission to use it,
+	 *         <code>false</code> 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 <code>true</code> if the item is a SlimefunItem and is enabled in the world the player is in,
+	 *         <code>false</code> 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 <code>true</code> if the item is enabled in the world the player is in,
+	 *         <code>false</code> 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<String> listIDs() {
-		List<String> ids = new ArrayList<String>();
+		List<String> 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<ItemStack> listCategories() {
-		List<ItemStack> items = new ArrayList<ItemStack>();
+		List<ItemStack> 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.
+	 * <p>
+	 * It can be directly accessed by {@link #emeraldenchants}.
+	 *
+	 * @return <code>true</code> if EmeraldEnchants is enabled,
+	 *         <code>false</code> otherwise.
+	 */
 	public static boolean isEmeraldEnchantsInstalled() {
 		return emeraldenchants;
 	}
 
 	public static List<GuideHandler> getGuideHandlers(int tier) {
-		return guide_handlers.containsKey(tier) ? guide_handlers.get(tier): new ArrayList<GuideHandler>();
+		return guide_handlers.containsKey(tier) ? guide_handlers.get(tier): new ArrayList<>();
 	}
 }