Improved the API.

src/main/java/com/sk89q/worldguard/bukkit/WorldGuardPlugin.java

@@ -19,6 +19,7 @@
 
 package com.sk89q.worldguard.bukkit;
 
+import com.sk89q.worldguard.protection.managers.RegionManager;
 import org.bukkit.ChatColor;
 import org.bukkit.Location;
 import org.bukkit.World;
@@ -736,6 +737,20 @@ public boolean canBuild(Player player, Block block) {
         return getGlobalRegionManager().canBuild(player, block);
     }
 
+    /**
+     * Gets the region manager for a world.
+     *
+     * @param world world to get the region manager for
+     * @return the region manager or null if regions are not enabled
+     */
+    public RegionManager getRegionManager(World world) {
+        if (!getGlobalStateManager().get(world).useRegions) {
+            return null;
+        }
+
+        return getGlobalRegionManager().get(world);
+    }
+
     /**
      * Replace macros in the text.
      *

src/main/java/com/sk89q/worldguard/protection/ApplicableRegionSet.java

@@ -31,8 +31,12 @@
 import com.sk89q.worldguard.LocalPlayer;
 
 /**
- * Represents a setFlag of regions and their rules as applied to one point or
- * region.
+ * Represents a set of regions for a particular point or area and the rules
+ * that are represented by that set. An instance of this can be used to
+ * query the value of a flag or check if a player can build in the respective
+ * region or point. This object contains the list of applicable regions and so
+ * the expensive search of regions that are in the desired area has already
+ * been completed.
  * 
  * @author sk89q
  */
@@ -57,47 +61,60 @@ public ApplicableRegionSet(Collection<ProtectedRegion> applicable,
      * Checks if a player can build in an area.
      * 
      * @param player
-     * @return
+     * @return build ability
      */
     public boolean canBuild(LocalPlayer player) {
         return internalGetState(DefaultFlag.BUILD, player, null, null);
     }
     
     /**
-     * Checks if a player can use items in an area.
+     * Checks if a player can use buttons and such in an area.
      * 
      * @param player
-     * @return
+     * @return able to use items
      */
     public boolean canUse(LocalPlayer player) {
-        return internalGetState(DefaultFlag.USE, player, null, null);
+        return !allows(DefaultFlag.USE, player)
+                && !canBuild(player);
     }
 
     /**
      * Gets the state of a state flag. This cannot be used for the build flag.
      *
-     * @param flag
-     * @return
+     * @see #allows(com.sk89q.worldguard.protection.flags.StateFlag, com.sk89q.worldguard.LocalPlayer) 
+     * @deprecated use the {@link #allows(StateFlag, LocalPlayer)} that takes a player
+     * @param flag flag to check
+     * @return whether it is allowed
+     * @throws IllegalArgumentException if the build flag is given
      */
+    @Deprecated
     public boolean allows(StateFlag flag) {
+        if (flag == DefaultFlag.BUILD) {
+            throw new IllegalArgumentException("Can't use build flag with allows()");
+        }
         return internalGetState(flag, null, null, null);
     }
     
     /**
      * Gets the state of a state flag. This cannot be used for the build flag.
      * 
-     * @param flag
-     * @return
+     * @param flag flag to check
+     * @param player player (used by some flags)
+     * @return whether the state is allows for it
+     * @throws IllegalArgumentException if the build flag is given
      */
     public boolean allows(StateFlag flag, LocalPlayer player) {
+        if (flag == DefaultFlag.BUILD) {
+            throw new IllegalArgumentException("Can't use build flag with allows()");
+        }
         return internalGetState(flag, null, flag.getGroupFlag(), player);
     }
     
     /**
      * Indicates whether a player is an owner of all regions in this set.
      * 
-     * @param player
-     * @return
+     * @param player player
+     * @return whether the player is an owner of all regions
      */
     public boolean isOwnerOfAll(LocalPlayer player) {
         for (ProtectedRegion region : applicable) {
@@ -113,8 +130,8 @@ public boolean isOwnerOfAll(LocalPlayer player) {
      * Indicates whether a player is an owner or member of all regions in
      * this set.
      * 
-     * @param player
-     * @return
+     * @param player player
+     * @return whether the player is a member of all regions
      */
     public boolean isMemberOfAll(LocalPlayer player) {
         for (ProtectedRegion region : applicable) {
@@ -269,14 +286,18 @@ private void clearParents(Set<ProtectedRegion> needsClear,
     }
 
     /**
-     * Gets the value of a flag. Do not use this for state flags.
+     * Gets the value of a flag. Do not use this for state flags
+     * (use {@link #allows(StateFlag, LocalPlayer)} for that).
      * 
-     * @param flag 
-     * @param <T> 
-     * @param <V> 
-     * @return
+     * @param flag flag to check
+     * @return value of the flag
+     * @throws IllegalArgumentException if a StateFlag is given
      */
     public <T extends Flag<V>, V> V getFlag(T flag) {
+        if (flag instanceof StateFlag) {
+            throw new IllegalArgumentException("Cannot use StateFlag with getFlag()");
+        }
+
         int lastPriority = 0;
         boolean found = false;
 

src/main/java/com/sk89q/worldguard/protection/GlobalRegionManager.java

@@ -208,6 +208,18 @@ public RegionManager get(World world) {
 
         return manager;
     }
+
+    /**
+     * Returns whether the player can bypass.
+     *
+     * @param player
+     * @param world
+     * @return
+     */
+    public boolean hasBypass(LocalPlayer player, World world) {
+        return player.hasPermission("worldguard.region.bypass."
+                        + world.getName());
+    }
     
     /**
      * Returns whether the player can bypass.

src/main/java/com/sk89q/worldguard/protection/managers/RegionManager.java

@@ -50,9 +50,10 @@ public RegionManager(ProtectionDatabase loader) {
     }
 
     /**
-     * Load the list of regions.
+     * Load the list of regions. If the regions do not load properly, then
+     * the existing list should be used (as stored previously).
      *
-     * @throws IOException
+     * @throws IOException thrown on load error
      */
     public void load() throws IOException {
         loader.load(this);
@@ -61,78 +62,86 @@ public void load() throws IOException {
     /**
      * Save the list of regions.
      *
-     * @throws IOException
+     * @throws IOException thrown on save error
      */
     public void save() throws IOException {
         loader.save(this);
     }
 
     /**
-     * Get a list of protected regions.
+     * Get a map of protected regions. Use one of the region manager methods
+     * if possible if working with regions.
      * 
-     * @return
+     * @return map of regions, with keys being region IDs (lowercase)
      */
     public abstract Map<String, ProtectedRegion> getRegions();
 
     /**
-     * Set a list of protected regions.
+     * Set a list of protected regions. Keys should be lowercase in the given
+     * map fo regions.
      * 
-     * @param regions
+     * @param regions map of regions
      */
     public abstract void setRegions(Map<String, ProtectedRegion> regions);
 
     /**
-     * Adds a region.
+     * Adds a region. If a region by the given name already exists, then
+     * the existing region will be replaced.
      * 
-     * @param region
+     * @param region region to add
      */
     public abstract void addRegion(ProtectedRegion region);
 
     /**
      * Return whether a region exists by an ID.
      * 
-     * @param id
-     * @return
+     * @param id id of the region, can be mixed-case
+     * @return whether the region exists
      */
     public abstract boolean hasRegion(String id);
 
     /**
      * Get a region by its ID.
      * 
-     * @param id
-     * @return
+     * @param id id of the region, can be mixed-case
+     * @return region or null if it doesn't exist
      */
     public abstract ProtectedRegion getRegion(String id);
 
     /**
      * Removes a region, including inheriting children.
      * 
-     * @param id
+     * @param id id of the region, can be mixed-case
      */
     public abstract void removeRegion(String id);
 
     /**
-     * Get an object for a point for rules to be applied with.
+     * Get an object for a point for rules to be applied with. Use this
+     * in order to query for flag data or membership data for a given
+     * point. If checking multiple flags for a single location,
      * 
-     * @param pt
-     * @return
+     * @param pt point
+     * @return applicable region set
      */
     public abstract ApplicableRegionSet getApplicableRegions(Vector pt);
 
     /**
-     * Get an object for a point for rules to be applied with.
-     * 
-     * @param region
-     * @return
+     * Get an object for a point for rules to be applied with. This gets
+     * a set for the given reason.
+     *
+     * @deprecated not yet fully supported
+     * @param region region
+     * @return regino set
      */
+    @Deprecated
     public abstract ApplicableRegionSet getApplicableRegions(
             ProtectedRegion region);
 
     /**
      * Get a list of region IDs that contain a point.
      * 
-     * @param pt
-     * @return
+     * @param pt point
+     * @return list of region Ids
      */
     public abstract List<String> getApplicableRegionsIDs(Vector pt);
 
@@ -140,25 +149,25 @@ public abstract ApplicableRegionSet getApplicableRegions(
      * Returns true if the provided region overlaps with any other region that
      * is not owned by the player.
      * 
-     * @param region
-     * @param player
-     * @return
+     * @param region region to check
+     * @param player player to check against
+     * @return whether there is an overlap
      */
     public abstract boolean overlapsUnownedRegion(ProtectedRegion region,
             LocalPlayer player);
 
     /**
      * Get the number of regions.
-     * 
-     * @return
+     *
+     * @return number of regions
      */
     public abstract int size();
 
     /**
      * Get the number of regions for a player.
-     * 
-     * @param player
-     * @return
+     *
+     * @param player player
+     * @return name number of regions that a player owns
      */
     public abstract int getRegionCountOfPlayer(LocalPlayer player);
 }