From 96b32ffd503aad439a59a83458dbd88925333d2a Mon Sep 17 00:00:00 2001 From: Thomas Guimbretiere Date: Thu, 18 Dec 2014 00:02:42 +0100 Subject: [PATCH] Partial javadoc --- .../mobius/waila/api/IWailaConfigHandler.java | 42 +++++++--- .../mobius/waila/api/IWailaDataAccessor.java | 9 +- .../mobius/waila/api/IWailaDataProvider.java | 83 ++++++++++++++----- .../waila/api/IWailaEntityAccessor.java | 9 +- .../waila/api/IWailaEntityProvider.java | 67 +++++++++++++-- 5 files changed, 162 insertions(+), 48 deletions(-) diff --git a/src/main/java/mcp/mobius/waila/api/IWailaConfigHandler.java b/src/main/java/mcp/mobius/waila/api/IWailaConfigHandler.java index faede63..9752e42 100644 --- a/src/main/java/mcp/mobius/waila/api/IWailaConfigHandler.java +++ b/src/main/java/mcp/mobius/waila/api/IWailaConfigHandler.java @@ -3,26 +3,42 @@ package mcp.mobius.waila.api; import java.util.HashMap; import java.util.Set; +/** + * Read-only interface for Waila internal config storage.
+ * An instance of this interface is passed to most of Waila callbacks as a way to change the behavior depending on client settings. + * + * @author ProfMobius + * + */ public interface IWailaConfigHandler { - /* Returns a set of all the currently loaded modules in the config handler */ + /** Returns a set of all the currently loaded modules in the config handler. + * + * @return + */ public Set getModuleNames(); - /* Returns all the currently available options for a given module */ + /** + * Returns all the currently available options for a given module + * + * @param modName Module name + * @return + */ public HashMap getConfigKeys(String modName); - /* Add a new option to a given module + /** + * Returns the current value of an option (true/false) with a default value if not set. * - * modName is the name of the module to add the option to (ie : Buildcraft, IndustrialCraft2, etc) - * key is the config key (ie : bc.tankcontent, ic2.inputvalue) - * name is the human readable name of the option (ie : "Tank content", "Max EU Input") - * */ - //public void addConfig(String modName, String key, String name); - - /* Returns the current value of an option (true/false) with a default value defvalue if not set*/ + * @param key Option to lookup + * @param defvalue Default values + * @return Value of the option or defvalue if not set. + */ public boolean getConfig(String key, boolean defvalue); - /* Returns the current value of an option (true/false) with a default value true if not set*/ + /** + * Returns the current value of an option (true/false) with a default value true if not set + * + * @param key Option to lookup + * @return Value of the option or true if not set. + */ public boolean getConfig(String key); - - //public void setConfig(String key, boolean value); } diff --git a/src/main/java/mcp/mobius/waila/api/IWailaDataAccessor.java b/src/main/java/mcp/mobius/waila/api/IWailaDataAccessor.java index 0288624..2273082 100644 --- a/src/main/java/mcp/mobius/waila/api/IWailaDataAccessor.java +++ b/src/main/java/mcp/mobius/waila/api/IWailaDataAccessor.java @@ -10,9 +10,12 @@ import net.minecraft.util.Vec3; import net.minecraft.world.World; import net.minecraftforge.common.util.ForgeDirection; -/* The Accessor is used to get some basic data out of the game without having to request - * direct access to the game engine. - * It will also return things that are unmodified by the overriding systems (like getWailaStack). +/** + * The Accessor is used to get some basic data out of the game without having to request direct access to the game engine.
+ * It will also return things that are unmodified by the overriding systems (like getWailaStack).
+ * An instance of this interface is passed to most of Waila Block/TileEntity callbacks. + * @author ProfMobius + * */ public interface IWailaDataAccessor { diff --git a/src/main/java/mcp/mobius/waila/api/IWailaDataProvider.java b/src/main/java/mcp/mobius/waila/api/IWailaDataProvider.java index 991c921..eb7e98b 100644 --- a/src/main/java/mcp/mobius/waila/api/IWailaDataProvider.java +++ b/src/main/java/mcp/mobius/waila/api/IWailaDataProvider.java @@ -8,37 +8,76 @@ import net.minecraft.nbt.NBTTagCompound; import net.minecraft.tileentity.TileEntity; import net.minecraft.world.World; +/** + * Callback class interface used to provide Block/TileEntity tooltip informations to Waila.
+ * All methods in this interface shouldn't to be called by the implementing mod. An instance of the class is to be + * registered to Waila via the {@link IWailaRegistrar} instance provided in the original registration callback method + * (cf. {@link IWailaRegistrar} documentation for more information). + * @author ProfMobius + * + */ public interface IWailaDataProvider{ - /* - * Use this method to return an item stack in case the default lookup system fails. - * Return null if you want to use the default lookup system. - * You get the world, the player and the location of the block. With that, it is easy to gather information & tile entities + + /** + * Callback used to override the default Waila lookup system.
+ * Will be used if the implementing class is registered via {@link IWailaRegistrar}.{@link registerStackProvider}.
+ * @param accessor Contains most of the relevant information about the current environment. + * @param config Current configuration of Waila. + * @return null if override is not required, an ItemStack otherwise. */ ItemStack getWailaStack(IWailaDataAccessor accessor, IWailaConfigHandler config); - /* Waila HUD is divided into 3 zones. The head corresponds to the item name, - * body to where you mostly want to put informations, and I reserve the tail for modname display - */ - - /* Those 3 methods works exactly the same way, except they are related to a different zone in Waila HUD. - * You get in input world, player and the block location. You also get the itemstack as returned by the default lookup system or getWailaStack(). - * ConfigHandler provides the current Waila config state so you can show/hide elements depending on the configuration. Refer the ConfigHandler class for more info. - * currenttip represents the current list of text lines in the tooltip zone. - * For example, getWailaHead() will have the current item name as currenttip. - * You can modify the tips, add more, remove some, etc. - * When you are done, just returns the currenttip and it will display in Waila. + /** + * Callback used to add lines to one of the three sections of the tooltip (Head, Body, Tail).
+ * Will be used if the implementing class is registered via {@link IWailaRegistrar}.{@link registerHeadProvider} client side.
+ * You are supposed to always return the modified input currenttip.
* - * Always return the currenttip is you don't want to modify the current zone. + * @param itemStack Current block scanned, in ItemStack form. + * @param currenttip Current list of tooltip lines (might have been processed by other providers and might be processed by other providers). + * @param accessor Contains most of the relevant information about the current environment. + * @param config Current configuration of Waila. + * @return Modified input currenttip */ - List getWailaHead(ItemStack itemStack, List currenttip, IWailaDataAccessor accessor, IWailaConfigHandler config); + + /** + * Callback used to add lines to one of the three sections of the tooltip (Head, Body, Tail).
+ * Will be used if the implementing class is registered via {@link IWailaRegistrar}.{@link registerBodyProvider} client side.
+ * You are supposed to always return the modified input currenttip.
+ * + * @param itemStack Current block scanned, in ItemStack form. + * @param currenttip Current list of tooltip lines (might have been processed by other providers and might be processed by other providers). + * @param accessor Contains most of the relevant information about the current environment. + * @param config Current configuration of Waila. + * @return Modified input currenttip + */ List getWailaBody(ItemStack itemStack, List currenttip, IWailaDataAccessor accessor, IWailaConfigHandler config); + + /** + * Callback used to add lines to one of the three sections of the tooltip (Head, Body, Tail).
+ * Will be used if the implementing class is registered via {@link IWailaRegistrar}.{@link registerTailProvider} client side.
+ * You are supposed to always return the modified input currenttip.
+ * + * @param itemStack Current block scanned, in ItemStack form. + * @param currenttip Current list of tooltip lines (might have been processed by other providers and might be processed by other providers). + * @param accessor Contains most of the relevant information about the current environment. + * @param config Current configuration of Waila. + * @return Modified input currenttip + */ List getWailaTail(ItemStack itemStack, List currenttip, IWailaDataAccessor accessor, IWailaConfigHandler config); - /* This method is used server side to return a custom NBT tag for tes properly registered with the Registrar.registerNBTProvider. - * It is an override to the classical way of getting NBT data via writeToNBT. - * NBTTagCompound tag argument is the current NBT tag passed along by the various providers (first provider will be empty). - * You HAVE TO return it if you registered as a provider, even if you are not doing anything to it (similar to the tooltip lists). - * */ + /** + * Callback used server side to return a custom synchronization NBTTagCompound.
+ * Will be used if the implementing class is registered via {@link IWailaRegistrar}.{@link registerNBTProvider} server and client side.
+ * You are supposed to always return the modified input NBTTagCompound tag.
+ * @param player The player requesting data synchronization (The owner of the current connection). + * @param te The TileEntity targeted for synchronization. + * @param tag Current synchronization tag (might have been processed by other providers and might be processed by other providers). + * @param world TileEntity's World. + * @param x X position of the TileEntity. + * @param y Y position of the TileEntity. + * @param z Z position of the TileEntity. + * @return Modified input NBTTagCompound tag. + */ NBTTagCompound getNBTData(EntityPlayerMP player, TileEntity te, NBTTagCompound tag, World world, int x, int y, int z); } diff --git a/src/main/java/mcp/mobius/waila/api/IWailaEntityAccessor.java b/src/main/java/mcp/mobius/waila/api/IWailaEntityAccessor.java index 788067a..a4c0076 100644 --- a/src/main/java/mcp/mobius/waila/api/IWailaEntityAccessor.java +++ b/src/main/java/mcp/mobius/waila/api/IWailaEntityAccessor.java @@ -7,9 +7,12 @@ import net.minecraft.util.MovingObjectPosition; import net.minecraft.util.Vec3; import net.minecraft.world.World; -/* The Accessor is used to get some basic data out of the game without having to request - * direct access to the game engine. - * It will also return things that are unmodified by the overriding systems (like getWailaStack). +/** + * The Accessor is used to get some basic data out of the game without having to request direct access to the game engine.
+ * It will also return things that are unmodified by the overriding systems (like getWailaStack).
+ * An instance of this interface is passed to most of Waila Entity callbacks. + * @author ProfMobius + * */ public interface IWailaEntityAccessor { diff --git a/src/main/java/mcp/mobius/waila/api/IWailaEntityProvider.java b/src/main/java/mcp/mobius/waila/api/IWailaEntityProvider.java index 68768f8..5a9acd8 100644 --- a/src/main/java/mcp/mobius/waila/api/IWailaEntityProvider.java +++ b/src/main/java/mcp/mobius/waila/api/IWailaEntityProvider.java @@ -7,20 +7,73 @@ import net.minecraft.entity.player.EntityPlayerMP; import net.minecraft.nbt.NBTTagCompound; import net.minecraft.world.World; +/** + * Callback class interface used to provide Entity tooltip informations to Waila.
+ * All methods in this interface shouldn't to be called by the implementing mod. An instance of the class is to be + * registered to Waila via the {@link IWailaRegistrar} instance provided in the original registration callback method + * (cf. {@link IWailaRegistrar} documentation for more information). + * @author ProfMobius + * + */ public interface IWailaEntityProvider { - /* A way to get an override on the entity returned by the raytracing */ + /** + * Callback used to override the default Waila lookup system.
+ * Will be used if the implementing class is registered via {@link IWailaRegistrar}.{@link registerOverrideEntityProvider}.
+ * @param accessor Contains most of the relevant information about the current environment. + * @param config Current configuration of Waila. + * @return null if override is not required, an Entity otherwise. + */ Entity getWailaOverride(IWailaEntityAccessor accessor, IWailaConfigHandler config); - /* The classical HEAD/BODY/TAIL text getters */ + /** + * Callback used to add lines to one of the three sections of the tooltip (Head, Body, Tail).
+ * Will be used if the implementing class is registered via {@link IWailaRegistrar}.{@link registerHeadProvider} client side.
+ * You are supposed to always return the modified input currenttip.
+ * + * @param entity Current Entity scanned. + * @param currenttip Current list of tooltip lines (might have been processed by other providers and might be processed by other providers). + * @param accessor Contains most of the relevant information about the current environment. + * @param config Current configuration of Waila. + * @return Modified input currenttip + */ List getWailaHead(Entity entity, List currenttip, IWailaEntityAccessor accessor, IWailaConfigHandler config); + + /** + * Callback used to add lines to one of the three sections of the tooltip (Head, Body, Tail).
+ * Will be used if the implementing class is registered via {@link IWailaRegistrar}.{@link registerBodyProvider} client side.
+ * You are supposed to always return the modified input currenttip.
+ * + * @param entity Current Entity scanned. + * @param currenttip Current list of tooltip lines (might have been processed by other providers and might be processed by other providers). + * @param accessor Contains most of the relevant information about the current environment. + * @param config Current configuration of Waila. + * @return Modified input currenttip + */ List getWailaBody(Entity entity, List currenttip, IWailaEntityAccessor accessor, IWailaConfigHandler config); + + /** + * Callback used to add lines to one of the three sections of the tooltip (Head, Body, Tail).
+ * Will be used if the implementing class is registered via {@link IWailaRegistrar}.{@link registerTailProvider} client side.
+ * You are supposed to always return the modified input currenttip.
+ * + * @param entity Current Entity scanned. + * @param currenttip Current list of tooltip lines (might have been processed by other providers and might be processed by other providers). + * @param accessor Contains most of the relevant information about the current environment. + * @param config Current configuration of Waila. + * @return Modified input currenttip + */ List getWailaTail(Entity entity, List currenttip, IWailaEntityAccessor accessor, IWailaConfigHandler config); - /* This method is used server side to return a custom NBT tag for tes properly registered with the Registrar.registerNBTProvider. - * It is an override to the classical way of getting NBT data via writeToNBT. - * NBTTagCompound tag argument is the current NBT tag passed along by the various providers (first provider will be empty). - * You HAVE TO return it if you registered as a provider, even if you are not doing anything to it (similar to the tooltip lists). - * */ + /** + * Callback used server side to return a custom synchronization NBTTagCompound.
+ * Will be used if the implementing class is registered via {@link IWailaRegistrar}.{@link registerNBTProvider} server and client side.
+ * You are supposed to always return the modified input NBTTagCompound tag.
+ * @param player The player requesting data synchronization (The owner of the current connection). + * @param ent The Entity targeted for synchronization. + * @param tag Current synchronization tag (might have been processed by other providers and might be processed by other providers). + * @param world TileEntity's World. + * @return Modified input NBTTagCompound tag. + */ NBTTagCompound getNBTData(EntityPlayerMP player, Entity ent, NBTTagCompound tag, World world); }