Javadoc updates

src/nu/nerd/SafeBuckets/Commands.java

@@ -30,6 +30,10 @@
  */
 public class Commands implements TabExecutor {
 
+    // ------------------------------------------------------------------------
+    /**
+     * An ordered set of this plugin's subcommands.
+     */
     private static final LinkedHashSet<String> SUBCOMMANDS = new LinkedHashSet<>(Arrays.asList(
         "flowsel", "reload", "safe", "safesel", "unsafe"
     ));
@@ -254,9 +258,15 @@ private boolean playerFlowCommand(CommandSender sender) {
 
     // ------------------------------------------------------------------------
     /**
-     * Flows applicable liquids within a WorldEdit selection.
+     * A bulk safety-status-change operation. If state is true, liquid source
+     * blocks and waterloggables will be made safe, and all liquids with Levellable
+     * level nonzero will be removed (i.e. set to Material.AIR); if false, the
+     * liquids within the WorldEdit selection will be flowed.
+     *
+     * @apiNote Requires WorldEdit.
      *
      * @param player the player performing the action.
+     * @param state true to make safe; false to flow.
      */
     private void bulkSafetyToggle(Player player, boolean state) {
         int blocksAffected = 0;

src/nu/nerd/SafeBuckets/PlayerFlowCache.java

@@ -62,7 +62,8 @@ static boolean isCached(Player player) {
 
     // ------------------------------------------------------------------------
     /**
-     * Forces a player's flow session to expire, removing them from the cache and flow mode.
+     * Forces a player's flow session to expire, removing them from the cache and
+     * flow mode.
      *
      * @param player the player.
      */

src/nu/nerd/SafeBuckets/PlayerFlowMode.java

@@ -14,7 +14,8 @@ enum PlayerFlowMode {
 
     // ------------------------------------------------------------------------
     /**
-     * Players will only be able to flow liquids in WorldGuard regions of which they are a member.
+     * Players will only be able to flow liquids in WorldGuard regions of which
+     * they are a member.
      */
     MEMBER
 

src/nu/nerd/SafeBuckets/SafeBuckets.java

@@ -70,7 +70,8 @@ public void onEnable() {
 
     // ------------------------------------------------------------------------
     /**
-     * If true, the given block is safe. Consults cache before calling the BlockStore API.
+     * Returns true if the given block is safe. This method consults an internal
+     * cache for a result before calling the BlockStoreAPI if none is found.
      *
      * @param block the block.
      * @return true if the given block is safe.
@@ -94,7 +95,8 @@ static boolean isSafe(Block block) {
 
     // ------------------------------------------------------------------------
     /**
-     * Sets the safety status of a given block and updates cache & BlockStore.
+     * Sets the safety status of a given block, updating the block's status both
+     * in the internal cache and BlockStore.
      *
      * @param block the block.
      * @param state the safety status (true = safe).
@@ -124,8 +126,10 @@ static void setSafe(Block block, boolean state) {
 
     // ------------------------------------------------------------------------
     /**
-     * Removes the safety status of the given block from both cache and BlockStore. Removal is not synonymous
-     * with setSafe(*, false).
+     * Removes the safety status of the given block from both cache and BlockStore.
+     * Removal is not necessarily synonymous with setSafe(*, false): the effects
+     * are the same but the false safety status implies intention while no status
+     * implies mundaneness.
      *
      * @param block the block.
      */
@@ -181,6 +185,8 @@ static ItemStack getBucket(Material liquidContainer, boolean safe) {
     /**
      * Determines if a player can flow a given block.
      *
+     * @apiNote Requires WorldGuard.
+     *
      * @param player the player.
      * @param block the block.
      * @return true if the player can flow the given block.
@@ -212,7 +218,8 @@ static boolean isPlayerFlowPermitted(Player player, Block block) {
 
     // ------------------------------------------------------------------------
     /**
-     * A logging method used instead of {@link java.util.logging.Logger} to faciliate prefix coloring.
+     * A logging method used instead of {@link java.util.logging.Logger} to
+     * faciliate prefix coloring.
      *
      * @param msg the message to log.
      */

src/nu/nerd/SafeBuckets/SafeBucketsListener.java

@@ -27,7 +27,6 @@
 import org.bukkit.event.block.BlockDispenseEvent;
 import org.bukkit.event.block.BlockFadeEvent;
 import org.bukkit.event.block.BlockFromToEvent;
-import org.bukkit.event.block.BlockPhysicsEvent;
 import org.bukkit.event.block.BlockPlaceEvent;
 import org.bukkit.event.player.PlayerBucketEmptyEvent;
 import org.bukkit.event.player.PlayerBucketFillEvent;
@@ -122,7 +121,7 @@ public boolean setBlock(BlockVector3 loc, BlockStateHolder block) throws WorldEd
 
     // ------------------------------------------------------------------------
     /**
-     * Prevents ice from melting.
+     * Prevents ice (except frosted ice) from melting.
      */
     @EventHandler(priority = EventPriority.HIGHEST, ignoreCancelled = true)
     public void onBlockFade(BlockFadeEvent event) {
@@ -137,9 +136,16 @@ public void onBlockFade(BlockFadeEvent event) {
 
     // ------------------------------------------------------------------------
     /**
-     * When a block of ice is broken the water that replaces it will be made safe
-     * unless the player is holding a tool enchanted with Silk Touch, in which
-     * case no water appears. When a dispenser is broken, remove its safety status.
+     * Handles a few things. If the broken block is...
+     *
+     *  (i) a dispenser, the block's safety information is removed from BlockStore;
+     *  (ii) kelp, the block's material will change from kelp to water and thus
+     *       needs to be made safe again;
+     *  (iii) generally waterloggable, it will be made safe since the water block
+     *        will usually persist (e.g. broken fence);
+     *  (iv) meltable ice, the resulting water block will be made safe, unless
+     *       the player is using a silk touch tool or the block does not actually
+     *       turn into water.
      */
     @EventHandler(priority = EventPriority.HIGHEST, ignoreCancelled = true)
     public void onBlockBreak(BlockBreakEvent event) {
@@ -190,7 +196,15 @@ public void onBlockBreak(BlockBreakEvent event) {
 
     // ------------------------------------------------------------------------
     /**
-     * Handle the placing of blocks in the world.
+     * Handles a few things. If the placed block is...
+     *
+     *  (i) kelp, the height limit will be checked, and the resulting block will
+     *      be made safe if it is not kelp-limited;
+     *  (ii) seagrass, the block(s) will be made safe;
+     *  (iii) a dispenser, the block will be made safe;
+     *  (iv) water or lava, the block will not change safety state since the game
+     *       will not stop the block from flowing;
+     *  (v) generally waterloggable, it will be made safe.
      */
     @EventHandler(priority = EventPriority.MONITOR, ignoreCancelled = true)
     public void onBlockPlace(BlockPlaceEvent event) {