Document flag classes and make BUILD slightly less magic.

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

@@ -270,8 +270,8 @@ private <V> Collection<V> queryAllValues(@Nullable RegionAssociable subject, Fla
         }
 
         // Check to see whether we have a subject if this is BUILD
-        if (flag == DefaultFlag.BUILD && subject == null) {
-            throw new NullPointerException("The BUILD flag is handled in a special fashion and requires a non-null subject parameter");
+        if (flag.requiresSubject() && subject == null) {
+            throw new NullPointerException("The " + flag.getName() + " flag is handled in a special fashion and requires a non-null subject parameter");
         }
 
         int minimumPriority = Integer.MIN_VALUE;
@@ -303,16 +303,15 @@ private <V> Collection<V> queryAllValues(@Nullable RegionAssociable subject, Fla
 
             addParents(ignoredParents, region);
 
-            // The BUILD flag (of lower priorities) can be overridden if
-            // this region has members... this check is here due to legacy
-            // reasons
-            if (priority != minimumPriority && flag == DefaultFlag.BUILD
+            // The BUILD flag is implicitly set on every region where
+            // PASSTHROUGH is not set to ALLOW
+            if (priority != minimumPriority && flag.implicitlySetWithMembership()
                     && getEffectiveFlag(region, DefaultFlag.PASSTHROUGH, subject) != State.ALLOW) {
                 minimumPriority = getPriority(region);
             }
         }
 
-        if (flag == DefaultFlag.BUILD && consideredValues.isEmpty()) {
+        if (flag.usesMembershipAsDefault() && consideredValues.isEmpty()) {
             switch (getMembership(subject)) {
                 case FAIL:
                     return ImmutableList.of();
@@ -365,10 +364,10 @@ public <V> V getEffectiveFlag(final ProtectedRegion region, Flag<V> flag, @Nulla
                     return (V) State.ALLOW;
                 }
 
-            } else if (flag == DefaultFlag.BUILD) {
+            } else if (flag instanceof StateFlag && ((StateFlag) flag).preventsAllowOnGlobal()) {
                 // Legacy behavior -> we can't let people change BUILD on
                 // the global region
-                State value = region.getFlag(DefaultFlag.BUILD);
+                State value = region.getFlag((StateFlag) flag);
                 return value != State.ALLOW ? (V) value : null;
             }
         }

src/main/java/com/sk89q/worldguard/protection/flags/BooleanFlag.java

@@ -24,8 +24,7 @@
 import com.sk89q.worldguard.bukkit.WorldGuardPlugin;
 
 /**
- *
- * @author sk89q
+ * A boolean flag.
  */
 public class BooleanFlag extends Flag<Boolean> {
 
@@ -38,8 +37,7 @@ public BooleanFlag(String name) {
     }
 
     @Override
-    public Boolean parseInput(WorldGuardPlugin plugin, CommandSender sender,
-            String input) throws InvalidFlagFormat {
+    public Boolean parseInput(WorldGuardPlugin plugin, CommandSender sender, String input) throws InvalidFlagFormat {
         input = input.trim();
         
         if (input.equalsIgnoreCase("true") || input.equalsIgnoreCase("yes")

src/main/java/com/sk89q/worldguard/protection/flags/BuildFlag.java

@@ -0,0 +1,52 @@
+/*
+ * WorldGuard, a suite of tools for Minecraft
+ * Copyright (C) sk89q <http://www.sk89q.com>
+ * Copyright (C) WorldGuard team and contributors
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as published by the
+ * Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package com.sk89q.worldguard.protection.flags;
+
+/**
+ * A special implementation of the {@link StateFlag} for
+ * {@link DefaultFlag#BUILD}.
+ */
+class BuildFlag extends StateFlag {
+
+    public BuildFlag(String name, boolean def) {
+        super(name, def);
+    }
+
+    @Override
+    public boolean implicitlySetWithMembership() {
+        return true;
+    }
+
+    @Override
+    public boolean usesMembershipAsDefault() {
+        return true;
+    }
+
+    @Override
+    public boolean preventsAllowOnGlobal() {
+        return true;
+    }
+
+    @Override
+    public boolean requiresSubject() {
+        return true;
+    }
+
+}

src/main/java/com/sk89q/worldguard/protection/flags/CommandStringFlag.java

@@ -24,8 +24,7 @@
 import com.sk89q.worldguard.bukkit.WorldGuardPlugin;
 
 /**
- *
- * @author sk89q
+ * Stores a command/
  */
 public class CommandStringFlag extends Flag<String> {
 
@@ -38,8 +37,7 @@ public CommandStringFlag(String name) {
     }
 
     @Override
-    public String parseInput(WorldGuardPlugin plugin, CommandSender sender,
-            String input) throws InvalidFlagFormat {
+    public String parseInput(WorldGuardPlugin plugin, CommandSender sender, String input) throws InvalidFlagFormat {
         input = input.trim();
         if (!input.startsWith("/")) {
             input = "/" + input;

src/main/java/com/sk89q/worldguard/protection/flags/DefaultFlag.java

@@ -39,7 +39,7 @@ public final class DefaultFlag {
     public static final RegionGroupFlag CONSTRUCT = new RegionGroupFlag("construct", RegionGroup.MEMBERS);
 
     // This flag is unlike the others. It forces the checking of region membership
-    public static final StateFlag BUILD = new StateFlag("build", true);
+    public static final StateFlag BUILD = new BuildFlag("build", true);
 
     // These flags are used in tandem with the BUILD flag - if the player can
     // build, then the following flags do not need to be checked (although they

src/main/java/com/sk89q/worldguard/protection/flags/DoubleFlag.java

@@ -24,8 +24,7 @@
 import com.sk89q.worldguard.bukkit.WorldGuardPlugin;
 
 /**
- *
- * @author sk89q
+ * Stores doubles.
  */
 public class DoubleFlag extends Flag<Double> {
 
@@ -38,8 +37,7 @@ public DoubleFlag(String name) {
     }
 
     @Override
-    public Double parseInput(WorldGuardPlugin plugin, CommandSender sender,
-            String input) throws InvalidFlagFormat {
+    public Double parseInput(WorldGuardPlugin plugin, CommandSender sender, String input) throws InvalidFlagFormat {
         input = input.trim();
 
         try {

src/main/java/com/sk89q/worldguard/protection/flags/EntityTypeFlag.java

@@ -22,9 +22,7 @@
 import org.bukkit.entity.EntityType;
 
 /**
- * Represents an entity type.
- *
- * @author sk89q
+ * Stores an entity type.
  */
 public class EntityTypeFlag extends EnumFlag<EntityType> {
 

src/main/java/com/sk89q/worldguard/protection/flags/EnumFlag.java

@@ -24,8 +24,7 @@
 import com.sk89q.worldguard.bukkit.WorldGuardPlugin;
 
 /**
- *
- * @author sk89q
+ * Stores an enum value.
  */
 public class EnumFlag<T extends Enum<T>> extends Flag<T> {
 
@@ -79,8 +78,7 @@ public T detectValue(String input) {
     }
 
     @Override
-    public T parseInput(WorldGuardPlugin plugin, CommandSender sender,
-            String input) throws InvalidFlagFormat {
+    public T parseInput(WorldGuardPlugin plugin, CommandSender sender, String input) throws InvalidFlagFormat {
         try {
             return findValue(input);
         } catch (IllegalArgumentException e) {

src/main/java/com/sk89q/worldguard/protection/flags/Flag.java

@@ -20,33 +20,45 @@
 package com.sk89q.worldguard.protection.flags;
 
 import com.sk89q.worldguard.bukkit.WorldGuardPlugin;
+import com.sk89q.worldguard.protection.FlagValueCalculator;
 import org.bukkit.command.CommandSender;
 
 import javax.annotation.Nullable;
 import java.util.Collection;
 
 /**
- *
- * @author sk89q
- * @param <T>
+ * A flag carries extra data on a region.
  */
 public abstract class Flag<T> {
 
-    private String name;
-    private RegionGroupFlag regionGroup;
-    
-    public Flag(String name, RegionGroup defaultGroup) {
-        this.name = name;
+    private final String name;
+    private final RegionGroupFlag regionGroup;
 
-        if (defaultGroup != null) {
-            this.regionGroup = new RegionGroupFlag(name + "-group", defaultGroup);
-        }
+    /**
+     * Create a new flag.
+     *
+     * @param name The name of the flag
+     * @param defaultGroup The default group
+     */
+    public Flag(String name, @Nullable RegionGroup defaultGroup) {
+        this.name = name;
+        this.regionGroup = defaultGroup != null ? new RegionGroupFlag(name + "-group", defaultGroup) : null;
     }
 
+    /**
+     * Create a new flag with {@link RegionGroup#ALL} as the default group.
+     *
+     * @param name The name of the flag
+     */
     public Flag(String name) {
         this(name, RegionGroup.ALL);
     }
 
+    /**
+     * Get the name of the flag.
+     *
+     * @return The name of the flag
+     */
     public String getName() {
         return name;
     }
@@ -54,26 +66,13 @@ public String getName() {
     /**
      * Get the default value.
      *
-     * @return the default value, if one exists, otherwise {@code null} may be returned
+     * @return The default value, if one exists, otherwise {@code null} may be returned
      */
     @Nullable
     public T getDefault() {
         return null;
     }
 
-    /**
-     * Whether the flag can take a list of values and choose a "best one."
-     *
-     * <p>This is the case with the {@link StateFlag} where {@code DENY}
-     * overrides {@code ALLOW}, but most flags just return the
-     * first result from a list.</p>
-     *
-     * @return whether a best value can be chosen
-     */
-    public boolean hasConflictStrategy() {
-        return false;
-    }
-
     @Nullable
     public T chooseValue(Collection<T> values) {
         if (!values.isEmpty()) {
@@ -82,15 +81,101 @@ public T chooseValue(Collection<T> values) {
             return null;
         }
     }
-    
+
+    /**
+     * Whether the flag can take a list of values and choose a "best one."
+     *
+     * <p>This is the case with the {@link StateFlag} where {@code DENY}
+     * overrides {@code ALLOW}, but most flags just return the
+     * first result from a list.</p>
+     *
+     * <p>This flag is primarily used to optimize flag lookup in
+     * {@link FlagValueCalculator}.</p>
+     *
+     * @return Whether a best value can be chosen
+     */
+    public boolean hasConflictStrategy() {
+        return false;
+    }
+
+    /**
+     * Whether the flag implicitly has a value set as long as
+     * {@link DefaultFlag#PASSTHROUGH} is not set.
+     *
+     * <p>This value is only changed, at least in WorldGuard, for the
+     * {@link DefaultFlag#BUILD} flag.</p>
+     *
+     * @return Whether the flag is ignored
+     */
+    public boolean implicitlySetWithMembership() {
+        return false;
+    }
+
+    /**
+     * Whether, if the flag is not set at all, the value should be derived
+     * from membership.
+     *
+     * <p>This value is only changed, at least in WorldGuard, for the
+     * {@link DefaultFlag#BUILD} flag.</p>
+     *
+     * @return Whether membership is used
+     */
+    public boolean usesMembershipAsDefault() {
+        return false;
+    }
+
+    /**
+     * Whether the flag requires that a subject is specified in
+     * {@link FlagValueCalculator}.
+     *
+     * <p>This value is only changed, at least in WorldGuard, for the
+     * {@link DefaultFlag#BUILD} flag.</p>
+     *
+     * @return Whether a subject is required
+     */
+    public boolean requiresSubject() {
+        return false;
+    }
+
+    /**
+     * Get the region group flag.
+     *
+     * <p>Every group has a region group flag except for region group flags
+     * themselves.</p>
+     *
+     * @return The region group flag
+     */
     public RegionGroupFlag getRegionGroupFlag() {
         return regionGroup;
     }
 
+    /**
+     * Parse a given input to coerce it to a type compatible with the flag.
+     *
+     * @param plugin The plugin
+     * @param sender The sender
+     * @param input THe input
+     * @return The coerced type
+     * @throws InvalidFlagFormat Raised if the input is invalid
+     */
     public abstract T parseInput(WorldGuardPlugin plugin, CommandSender sender, String input) throws InvalidFlagFormat;
 
+    /**
+     * Convert a raw type that was loaded (from a YAML file, for example)
+     * into the type that this flag uses.
+     *
+     * @param o The object
+     * @return The unmarshalled type
+     */
     public abstract T unmarshal(@Nullable Object o);
 
+    /**
+     * Convert the value stored for this flag into a type that can be
+     * serialized into YAML.
+     *
+     * @param o The object
+     * @return The marshalled type
+     */
     public abstract Object marshal(T o);
 
     @Override

src/main/java/com/sk89q/worldguard/protection/flags/IntegerFlag.java

@@ -24,8 +24,7 @@
 import com.sk89q.worldguard.bukkit.WorldGuardPlugin;
 
 /**
- *
- * @author sk89q
+ * Stores an integer.
  */
 public class IntegerFlag extends Flag<Integer> {
 
@@ -38,8 +37,7 @@ public IntegerFlag(String name) {
     }
 
     @Override
-    public Integer parseInput(WorldGuardPlugin plugin, CommandSender sender,
-            String input) throws InvalidFlagFormat {
+    public Integer parseInput(WorldGuardPlugin plugin, CommandSender sender,String input) throws InvalidFlagFormat {
         input = input.trim();
 
         try {

src/main/java/com/sk89q/worldguard/protection/flags/LazyLocation.java

@@ -27,6 +27,9 @@
 
 import javax.annotation.Nullable;
 
+/**
+ * A location that stores the name of the world in case the world is unloaded.
+ */
 class LazyLocation extends Location {
 
     private final String worldName;
@@ -66,6 +69,4 @@ public LazyLocation add(double x, double y, double z) {
         return this.setPosition(getPosition().add(x, y, z));
     }
 
-
-
 }

src/main/java/com/sk89q/worldguard/protection/flags/RegionGroupFlag.java

@@ -26,8 +26,7 @@
 import javax.annotation.Nullable;
 
 /**
- *
- * @author sk89q
+ * Stores a region group.
  */
 public class RegionGroupFlag extends EnumFlag<RegionGroup> {
 

src/main/java/com/sk89q/worldguard/protection/flags/SetFlag.java

@@ -29,9 +29,7 @@
 import java.util.Set;
 
 /**
- * Represents a flag that consists of a set.
- *
- * @author sk89q
+ * Stores a set of types.
  */
 public class SetFlag<T> extends Flag<Set<T>> {
 
@@ -57,8 +55,7 @@ public Flag<T> getType() {
     }
 
     @Override
-    public Set<T> parseInput(WorldGuardPlugin plugin, CommandSender sender,
-            String input) throws InvalidFlagFormat {
+    public Set<T> parseInput(WorldGuardPlugin plugin, CommandSender sender, String input) throws InvalidFlagFormat {
         Set<T> items = new HashSet<T>();
 
         for (String str : input.split(",")) {

src/main/java/com/sk89q/worldguard/protection/flags/StateFlag.java

@@ -26,8 +26,7 @@
 import java.util.Collection;
 
 /**
- *
- * @author sk89q
+ * Stores a bi-state value.
  */
 public class StateFlag extends Flag<StateFlag.State> {
 
@@ -68,9 +67,21 @@ public State chooseValue(Collection<State> values) {
         }
     }
 
+    /**
+     * Whether setting this flag to {@link State#ALLOW} is prevented on
+     * the global region.
+     *
+     * <p>This value is only changed, at least in WorldGuard, for the
+     * {@link DefaultFlag#BUILD} flag.</p>
+     *
+     * @return Whether {@code ALLOW} is prevented
+     */
+    public boolean preventsAllowOnGlobal() {
+        return false;
+    }
+
     @Override
-    public State parseInput(WorldGuardPlugin plugin, CommandSender sender,
-            String input) throws InvalidFlagFormat {
+    public State parseInput(WorldGuardPlugin plugin, CommandSender sender, String input) throws InvalidFlagFormat {
         input = input.trim();
 
         if (input.equalsIgnoreCase("allow")) {

src/main/java/com/sk89q/worldguard/protection/flags/StringFlag.java

@@ -26,8 +26,7 @@
 import javax.annotation.Nullable;
 
 /**
- *
- * @author sk89q
+ * Stores a string.
  */
 public class StringFlag extends Flag<String> {
 
@@ -60,8 +59,7 @@ public String getDefault() {
     }
 
     @Override
-    public String parseInput(WorldGuardPlugin plugin, CommandSender sender,
-            String input) throws InvalidFlagFormat {
+    public String parseInput(WorldGuardPlugin plugin, CommandSender sender, String input) throws InvalidFlagFormat {
         return input.replaceAll("(?!\\\\)\\\\n", "\n").replaceAll("\\\\\\\\n", "\\n");
     }
 

src/main/java/com/sk89q/worldguard/protection/flags/VectorFlag.java

@@ -19,19 +19,17 @@
 
 package com.sk89q.worldguard.protection.flags;
 
-import java.util.HashMap;
-import java.util.Map;
-
-import org.bukkit.command.CommandSender;
-
 import com.sk89q.minecraft.util.commands.CommandException;
 import com.sk89q.worldedit.Vector;
 import com.sk89q.worldguard.bukkit.BukkitUtil;
 import com.sk89q.worldguard.bukkit.WorldGuardPlugin;
+import org.bukkit.command.CommandSender;
+
+import java.util.HashMap;
+import java.util.Map;
 
 /**
- *
- * @author sk89q
+ * Stores a vector.
  */
 public class VectorFlag extends Flag<Vector> {