Add some JavaDoc

src/main/java/net/citizensnpcs/api/CitizensAPI.java

@@ -56,6 +56,9 @@ public static File getDataFolder() {
         return getImplementation().getDataFolder();
     }
 
+    /**
+     * @return The default NPC selector
+     */
     public static NPCSelector getDefaultNPCSelector() {
         return getImplementation().getDefaultNPCSelector();
     }

src/main/java/net/citizensnpcs/api/ai/GoalController.java

@@ -5,7 +5,9 @@
 
 /**
  * Represents a collection of goals that are prioritised and executed, allowing behaviour trees via a
- * {@link GoalSelector}.
+ * {@link GoalSelector} or by implementing {@link Behavior}.
+ *
+ * In general, using {@link Behavior} is preferred due to mapping more closely to traditional behavior trees.
  *
  * The highest priority {@link Goal} that returns true in {@link Goal#shouldExecute(GoalSelector)} is executed. Any
  * existing goals with a lower priority are replaced via {@link Goal#reset()}.

src/main/java/net/citizensnpcs/api/ai/PrioritisableGoal.java

@@ -1,5 +1,8 @@
 package net.citizensnpcs.api.ai;
 
+/**
+ * A dynamically prioritisable {@link Goal}.
+ */
 public interface PrioritisableGoal extends Goal {
     int getPriority();
 }

src/main/java/net/citizensnpcs/api/ai/SimpleGoalController.java

@@ -1,5 +1,6 @@
 package net.citizensnpcs.api.ai;
 
+import java.util.ArrayList;
 import java.util.Collections;
 import java.util.Iterator;
 import java.util.List;
@@ -11,6 +12,10 @@
 import net.citizensnpcs.api.ai.tree.BehaviorGoalAdapter;
 import net.citizensnpcs.api.ai.tree.ForwardingBehaviorGoalAdapter;
 
+/**
+ * A simple {@link GoalController} implementation that stores goals as a {@link ArrayList}. It works with both
+ * {@link Behavior}, {@link Goal} and will also consider {@link PrioritisableGoal}s if implemented.
+ */
 public class SimpleGoalController implements GoalController {
     private final List<Goal> executingGoals = Lists.newArrayList();
     private int executingPriority = -1;
@@ -59,7 +64,8 @@ public int compareTo(GoalEntry o) {
             public Behavior getBehavior() {
                 return goal instanceof Behavior ? (Behavior) goal
                         : goal instanceof ForwardingBehaviorGoalAdapter
-                                ? ((ForwardingBehaviorGoalAdapter) goal).getWrapped() : null;
+                                ? ((ForwardingBehaviorGoalAdapter) goal).getWrapped()
+                                : null;
             }
 
             @Override
@@ -262,8 +268,9 @@ public void select(Goal goal) {
 
         @Override
         public void selectAdditional(Goal... goals) {
-            for (Goal goal : goals)
+            for (Goal goal : goals) {
                 addGoalToExecution(goal);
+            }
         }
     }
 }

src/main/java/net/citizensnpcs/api/ai/flocking/AlignmentBehavior.java

@@ -2,10 +2,16 @@
 
 import java.util.Collection;
 
-import net.citizensnpcs.api.npc.NPC;
-
 import org.bukkit.util.Vector;
 
+import net.citizensnpcs.api.npc.NPC;
+
+/**
+ * Implements alignment flocking with a particular weight i.e. steering a flock of NPCs in line with each other.
+ *
+ * @see <a href=
+ *      "https://en.wikipedia.org/wiki/Flocking_(behavior)">https://en.wikipedia.org/wiki/Flocking_(behavior)</a>
+ */
 public class AlignmentBehavior implements FlockBehavior {
     private final double weight;
 

src/main/java/net/citizensnpcs/api/ai/flocking/CohesionBehavior.java

@@ -7,6 +7,12 @@
 
 import net.citizensnpcs.api.npc.NPC;
 
+/**
+ * Implements cohesion flocking with a particular weight i.e. steering a flock of NPCs towards each other.
+ *
+ * @see <a href=
+ *      "https://en.wikipedia.org/wiki/Flocking_(behavior)">https://en.wikipedia.org/wiki/Flocking_(behavior)</a>
+ */
 public class CohesionBehavior implements FlockBehavior {
     private final double weight;
 

src/main/java/net/citizensnpcs/api/ai/flocking/FlockBehavior.java

@@ -2,10 +2,21 @@
 
 import java.util.Collection;
 
-import net.citizensnpcs.api.npc.NPC;
-
 import org.bukkit.util.Vector;
 
+import net.citizensnpcs.api.npc.NPC;
+
+/**
+ * An interface to be used with an {@link Flocker} to represent a certain type of behavior such as cohesion, alignment
+ * or separation.
+ */
 public interface FlockBehavior {
+    /**
+     * Returns the displacement vector to be combined with other {@link FlockBehavior} vectors by a {@link Flocker}.
+     *
+     * @param nearby
+     *            the set of NPCs to consider for flocking purposes
+     * @return the displacement {@link Vector}
+     */
     Vector getVector(NPC npc, Collection<NPC> nearby);
 }

src/main/java/net/citizensnpcs/api/ai/flocking/Flocker.java

@@ -7,7 +7,17 @@
 import org.bukkit.util.Vector;
 
 import net.citizensnpcs.api.npc.NPC;
-
+import net.citizensnpcs.api.trait.Trait;
+
+/**
+ * Implements a simple flocking controller as a {@link Runnable}. This should be run every tick, for example as part of
+ * an overridden {@link Trait#run}.
+ *
+ * @see {@link NPCFlock}
+ * @see {@link FlockBehavior}
+ * @see <a href=
+ *      "https://en.wikipedia.org/wiki/Flocking_(behavior)">https://en.wikipedia.org/wiki/Flocking_(behavior)</a>
+ */
 public class Flocker implements Runnable {
     private final List<FlockBehavior> behaviors;
     private final NPCFlock flock;
@@ -33,6 +43,12 @@ public void run() {
         npc.getEntity().setVelocity(npc.getEntity().getVelocity().add(base));
     }
 
+    /**
+     * Sets the maximum length of the resultant flocking vector.
+     *
+     * @param maxForce
+     *            the new maximum length
+     */
     public void setMaxForce(double maxForce) {
         this.maxForce = maxForce;
     }
@@ -43,7 +59,4 @@ private static Vector clip(double max, Vector vector) {
         }
         return vector;
     }
-
-    public static double HIGH_INFLUENCE = 1.0 / 20.0;
-    public static double LOW_INFLUENCE = 1.0 / 200.0;
 }

src/main/java/net/citizensnpcs/api/ai/flocking/GroupNPCFlock.java

@@ -8,6 +8,10 @@
 
 import net.citizensnpcs.api.npc.NPC;
 
+/**
+ * Defines a static flock of NPCs with an optional radius. If the radius is positive then NPCs will only be considered
+ * part of the flock if they are within the base NPC's radius currently.
+ */
 public class GroupNPCFlock implements NPCFlock {
     private final List<NPC> npcs;
     private final double radius;

src/main/java/net/citizensnpcs/api/ai/flocking/NPCFlock.java

@@ -4,6 +4,15 @@
 
 import net.citizensnpcs.api.npc.NPC;
 
+/**
+ * Represents a 'flock' of NPCs to be used as input to a {@link Flocker}.
+ *
+ * @see {@link RadiusNPCFlock}
+ * @see {@link GroupNPCFlock}
+ */
 public interface NPCFlock {
+    /**
+     * Returns the NPCs to be considered part of a flock.
+     */
     public Collection<NPC> getNearby(NPC npc);
 }

src/main/java/net/citizensnpcs/api/ai/flocking/RadiusNPCFlock.java

@@ -9,6 +9,9 @@
 import net.citizensnpcs.api.CitizensAPI;
 import net.citizensnpcs.api.npc.NPC;
 
+/**
+ * A flock of NPCs that is not static but instead uses NPCs within a certain radius as the 'flock'.
+ */
 public class RadiusNPCFlock implements NPCFlock {
     private Collection<NPC> cached;
     private int cacheTicks = 0;
@@ -19,6 +22,14 @@ public RadiusNPCFlock(double radius) {
         this(radius, 30);
     }
 
+    /**
+     *
+     * @param radius
+     *            the radius to look for nearby NPCs, in blocks @see
+     *            {@link Entity#getNearbyEntities(double, double, double)}
+     * @param maxCacheTicks
+     *            the maximum cache ticks to cache the nearby NPC 'flock' (default 30)
+     */
     public RadiusNPCFlock(double radius, int maxCacheTicks) {
         this.radius = radius;
         this.maxCacheTicks = maxCacheTicks;

src/main/java/net/citizensnpcs/api/ai/flocking/SeparationBehavior.java

@@ -6,6 +6,12 @@
 
 import net.citizensnpcs.api.npc.NPC;
 
+/**
+ * Implements separation flocking with a particular weight i.e. steering a flock of NPCs away from each other.
+ *
+ * @see <a href=
+ *      "https://en.wikipedia.org/wiki/Flocking_(behavior)">https://en.wikipedia.org/wiki/Flocking_(behavior)</a>
+ */
 public class SeparationBehavior implements FlockBehavior {
     private final double decayCoef = 0.5D;
     private final double maxAcceleration = 2D;

src/main/java/net/citizensnpcs/api/ai/goals/MoveToGoal.java

@@ -1,13 +1,18 @@
 package net.citizensnpcs.api.ai.goals;
 
+import org.bukkit.Location;
+
+import net.citizensnpcs.api.ai.Goal;
 import net.citizensnpcs.api.ai.event.CancelReason;
 import net.citizensnpcs.api.ai.event.NavigatorCallback;
+import net.citizensnpcs.api.ai.tree.Behavior;
 import net.citizensnpcs.api.ai.tree.BehaviorGoalAdapter;
 import net.citizensnpcs.api.ai.tree.BehaviorStatus;
 import net.citizensnpcs.api.npc.NPC;
 
-import org.bukkit.Location;
-
+/**
+ * A sample {@link Goal}/{@link Behavior} that simply moves an {@link NPC} to a specified {@link Location}.
+ */
 public class MoveToGoal extends BehaviorGoalAdapter {
     private boolean finished;
     private final NPC npc;

src/main/java/net/citizensnpcs/api/ai/goals/TargetNearbyEntityGoal.java

@@ -4,15 +4,22 @@
 import java.util.EnumSet;
 import java.util.Set;
 
+import org.bukkit.entity.Entity;
+import org.bukkit.entity.EntityType;
+
+import net.citizensnpcs.api.ai.Goal;
+import net.citizensnpcs.api.ai.Navigator;
 import net.citizensnpcs.api.ai.event.CancelReason;
 import net.citizensnpcs.api.ai.event.NavigatorCallback;
+import net.citizensnpcs.api.ai.tree.Behavior;
 import net.citizensnpcs.api.ai.tree.BehaviorGoalAdapter;
 import net.citizensnpcs.api.ai.tree.BehaviorStatus;
 import net.citizensnpcs.api.npc.NPC;
 
-import org.bukkit.entity.Entity;
-import org.bukkit.entity.EntityType;
-
+/**
+ * A sample {@link Goal}/{@link Behavior} that will target specific {@link EntityType}s within a certain radius and
+ * start following them using {@link Navigator#setTarget(Entity, boolean)}.
+ */
 public class TargetNearbyEntityGoal extends BehaviorGoalAdapter {
     private final boolean aggressive;
     private boolean finished;

src/main/java/net/citizensnpcs/api/ai/goals/WanderGoal.java

@@ -12,13 +12,18 @@
 import com.google.common.base.Supplier;
 
 import net.citizensnpcs.api.CitizensAPI;
+import net.citizensnpcs.api.ai.Goal;
 import net.citizensnpcs.api.ai.event.NavigationCompleteEvent;
+import net.citizensnpcs.api.ai.tree.Behavior;
 import net.citizensnpcs.api.ai.tree.BehaviorGoalAdapter;
 import net.citizensnpcs.api.ai.tree.BehaviorStatus;
 import net.citizensnpcs.api.astar.pathfinder.MinecraftBlockExaminer;
 import net.citizensnpcs.api.npc.NPC;
 import net.citizensnpcs.api.util.cuboid.QuadTree;
 
+/**
+ * A sample {@link Goal}/{@link Behavior} that will wander within a certain radius or {@link QuadTree}.
+ */
 public class WanderGoal extends BehaviorGoalAdapter implements Listener {
     private final Function<NPC, Location> fallback;
     private boolean forceFinish;
@@ -114,6 +119,21 @@ public static WanderGoal createWithNPCAndRangeAndTree(NPC npc, int xrange, int y
         return createWithNPCAndRangeAndTreeAndFallback(npc, xrange, yrange, tree, null);
     }
 
+    /**
+     * The full builder method.
+     *
+     * @param npc
+     *            the NPC to wander
+     * @param xrange
+     *            x/z range, in blocks
+     * @param yrange
+     *            y range, in blocks
+     * @param tree
+     *            an optional {@link QuadTree} supplier to allow only wandering within a certain {@link QuadTree}
+     * @param fallback
+     *            an optional fallback location
+     * @return the built goal
+     */
     public static WanderGoal createWithNPCAndRangeAndTreeAndFallback(NPC npc, int xrange, int yrange,
             Supplier<QuadTree> tree, Function<NPC, Location> fallback) {
         return new WanderGoal(npc, xrange, yrange, tree, fallback);