Linting: Fix multiple Javadoc Errors / Warnings

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

@@ -35,9 +35,7 @@ public interface CitizensPlugin extends Plugin {
     public NPCSelector getDefaultNPCSelector();
 
     /**
-     * Gets the Citizens {@link LocationLookup}
-     *
-     * @return
+     * @return Citizen's {@link LocationLookup}
      */
     public LocationLookup getLocationLookup();
 

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

@@ -2,7 +2,7 @@
 
 /**
  * Represents a Goal that can be added to a {@link GoalController}.
- *
+ * <p>
  * A Goal represents an abstract node in a tree of events. It can be anything from attacking players to a villager. By
  * using the {@link GoalSelector} provided in {@link #shouldExecute(GoalSelector)} the Goal can traverse its tree of
  * behaviours.

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

@@ -6,9 +6,9 @@
 /**
  * Represents a collection of goals that are prioritised and executed, allowing behaviour trees via a
  * {@link GoalSelector} or by implementing {@link Behavior}.
- *
+ * <p>
  * In general, using {@link Behavior} is preferred due to mapping more closely to traditional behavior trees.
- *
+ * <p>
  * 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()}.
  */
@@ -35,10 +35,13 @@ public interface GoalController extends Runnable, Iterable<GoalEntry> {
     void addGoal(Goal goal, int priority);
 
     /**
-     * Registers a goal which can reprioritise itself dynamically every tick. Implementation note: this may slow down
-     * individual goal controller ticks as the list must be sorted every tick.
+     * Registers a goal which can re-prioritise itself dynamically every tick.
+     * <p>
+     * Implementation note: This may slow down individual goal controller ticks,
+     * as the list must be sorted every tick.
      *
      * @param goal
+     *            A new {@link PrioritisableGoal}
      */
     void addPrioritisableGoal(PrioritisableGoal goal);
 

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

@@ -136,6 +136,7 @@ public interface Navigator {
      * Sets the current navigation to the specified strategy.
      *
      * @param strategy
+     *            New navigation strategy
      */
     void setTarget(Function<NavigatorParameters, PathStrategy> strategy);
 

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

@@ -259,7 +259,7 @@ public NavigatorParameters destinationTeleportMargin(double margin) {
     /**
      * Returns the distance margin or leeway that the {@link Navigator} will be able to stop from the target
      * destination. The margin will be measured against the block distance.
-     *
+     * <p>
      * For example: if the distance margin were 2, then the {@link Navigator} could stop moving towards the target when
      * it is 2 blocks away from it.
      *
@@ -390,10 +390,10 @@ public PathfinderType pathfinderType() {
     }
 
     /**
-     * Sets whether or not to use an A* pathfinder defined in {@link AStarMachine} for pathfinding.
-     *
+     * Sets whether to use an A* pathfinder defined in {@link AStarMachine} for pathfinding.
+     * <p>
      * If this is set to MINECRAFT, then the Minecraft pathfinder will be used, which may or may not be more consistent.
-     *
+     * <p>
      * Note that certain API features will not be possible if this is set to MINECRAFT - for example,
      * {@link #examiner(BlockExaminer)}.
      *
@@ -579,10 +579,10 @@ public boolean useNewPathfinder() {
     }
 
     /**
-     * Sets whether or not to use an A* pathfinder defined in {@link AStarMachine} for pathfinding.
-     *
+     * Sets whether to use an A* pathfinder defined in {@link AStarMachine} for pathfinding.
+     * <p>
      * If this is set to false, then the Minecraft pathfinder will be used, which may or may not be more consistent.
-     *
+     * <p>
      * Note that certain API features will not be possible if this is set to false - this includes
      * {@link #examiner(BlockExaminer)} and {@link #distanceMargin(double)}.
      *

src/main/java/net/citizensnpcs/api/ai/tree/Behavior.java

@@ -5,13 +5,13 @@
 /**
  * The base class for the second iteration of the {@link Goal} API, which can be made backwards compatible by extending
  * {@link BehaviorGoalAdapter}.
- *
+ * <p>
  * A behavior is a common term for the parts of a <em>behavior tree</em>, which is a simple directed acyclic graph (DAG)
  * for AI. It is a simple state machine using {@link BehaviorStatus}.
- *
+ * <p>
  * Nodes are executed in a top-down fashion through the tree. For legacy reasons, the tree is executed as a number of
  * <em>executing nodes</em> which are transitioned between using the {@link BehaviorStatus} they return.
- *
+ * <p>
  * New child nodes are selected to become <em>executing nodes</em> based on {@link Behavior#shouldExecute()}. The
  * selection behavior can vary, e.g. running a list of nodes using {@link Sequence} or choosing from children nodes
  * using {@link Selector}. The executing nodes are repeatedly {@link Behavior#run()} until the return result changes

src/main/java/net/citizensnpcs/api/ai/tree/Decorator.java

@@ -10,7 +10,7 @@
 /**
  * A decorator is a wrapper over a {@link Behavior}, which can add functionality such as filtering
  * {@link BehaviorStatus}es, conditions, timer loops and more without knowing the internals of the behavior it wraps.
- *
+ * <p>
  * Note that there are often simpler alternatives to a full-blown decorator, which has to be generic for many different
  * scenarios.
  */

src/main/java/net/citizensnpcs/api/ai/tree/ParallelBehavior.java

@@ -3,7 +3,7 @@
 /**
  * A marker interface for {@link Behavior}s that indicates to any parent nodes that the behavior can be run in
  * <em>parallel</em> along with other behaviors.
- *
+ * <p>
  * Parallel behaviors will not affect the success or failure status of any composite nodes; the return
  * {@link BehaviorStatus} will only act as a terminal status or an indication to remove the parallel node.
  */

src/main/java/net/citizensnpcs/api/command/CommandManager.java

@@ -84,7 +84,7 @@ public CommandManager() {
      *
      * Attempt to execute a command using the root {@link Command} given. A list of method arguments may be used when
      * calling the command handler method.
-     *
+     * <p>
      * A command handler method should follow the form <code>command(CommandContext args, CommandSender sender)</code>
      * where {@link CommandSender} can be replaced with {@link Player} to only accept players. The method parameters
      * must include the method args given, if any.
@@ -501,7 +501,7 @@ public void register(Class<?> clazz) {
 
     /**
      * Registers an {@link CommandAnnotationProcessor} that can process annotations before a command is executed.
-     *
+     * <p>
      * Methods with the {@link Command} annotation will have the rest of their annotations scanned and stored if there
      * is a matching {@link CommandAnnotationProcessor}. Annotations that do not have a processor are discarded. The
      * scanning method uses annotations from the declaring class as a base before narrowing using the method's

src/main/java/net/citizensnpcs/api/gui/InventoryMenu.java

@@ -43,20 +43,20 @@
  * A container class for Inventory GUIs. Expects {@link #onInventoryClick(InventoryClickEvent)} and
  * {@link #onInventoryClose(InventoryCloseEvent)} to be called by the user (or registered with the event listener
  * system). Optionally, {@link #run()} can also be called every tick.
- *
+ * <p>
  * Inventory GUIs are defined as a stack of {@link InventoryMenuPage}s, each of which represents a distinct inventory
  * that is transitioned between using either code or user clicks using the {@link InventoryMenuTransition} class. Each
  * {@link InventoryMenuPage} should define a {@link Menu} annotation at the class level.
- *
+ * <p>
  * Each page has a number of {@link InventoryMenuSlot}s which define attributes such as default slot item,
  * interactibility, etc.
- *
+ * <p>
  * You can define sets of slots and transitions using {@link InventoryMenuPattern}.
- *
+ * <p>
  * For each concrete class of slot/transition/pattern there is a corresponding annotation that is defined.
  * {@link InventoryMenuPage}s can either annotate specific instances of these concrete classes which will be injected at
  * runtime or simply place them at the method/class level.
- *
+ * <p>
  * Instances of global/contextual variables can be injected dynamically via {@link InjectContext} which sources
  * variables from the {@link MenuContext}.
  */

src/main/java/net/citizensnpcs/api/gui/InventoryMenuSlot.java

@@ -155,9 +155,10 @@ public void setFilter(Collection<InventoryAction> filter) {
     }
 
     /**
-     * Manually set the {@link ItemStack} for this slot
+     * Manually set the {@link ItemStack} for this slot.
      *
      * @param stack
+     *            An overriding {@link ItemStack}
      */
     public void setItemStack(ItemStack stack) {
         inventory.setItem(index, stack);

src/main/java/net/citizensnpcs/api/npc/BlockBreaker.java

@@ -12,9 +12,9 @@
 /**
  * A {@link Runnable} task that will break a block over time just as a normal Minecraft {@link Player} would. Should be
  * run every tick until completed.
- *
+ * <p>
  * This class also implements the {@link Behavior} interface for ease of use.
- *
+ * <p>
  * Due to NMS constraints, this is currently implemented inside Citizens2.
  */
 public abstract class BlockBreaker extends BehaviorGoalAdapter {

src/main/java/net/citizensnpcs/api/npc/NPC.java

@@ -371,6 +371,7 @@ default void setAlwaysUseNameHologram(boolean use) {
      * entities only - it will generally have no effect on mob types that were originally flyable.
      *
      * @param flyable
+     *            Should the NPC be flyable?
      */
     default void setFlyable(boolean flyable) {
         data().setPersistent(NPC.Metadata.FLYABLE, flyable);
@@ -456,7 +457,7 @@ default boolean spawn(Location location, SpawnReason reason) {
     /**
      * Attempts to spawn this NPC.
      *
-     * @param location
+     * @param at
      *            Location to spawn this NPC
      * @param reason
      *            Reason for spawning

src/main/java/net/citizensnpcs/api/trait/Trait.java

@@ -13,7 +13,7 @@
 /**
  * Represents a Trait linked to an {@link NPC} that can be loaded and saved. This will be kept persisted inside a
  * {@link NPC} across server restarts. Traits must be registered in Citizens' {@link TraitFactory}.
- *
+ * <p>
  * All traits should have a default constructor with no arguments for persistence purposes.
  */
 public abstract class Trait implements Listener, Runnable {

src/main/java/net/citizensnpcs/api/trait/TraitFactory.java

@@ -23,9 +23,7 @@ public interface TraitFactory {
     void deregisterTrait(TraitInfo info);
 
     /**
-     * Returns all currently registered traits, including <em>internal</em> traits
-     *
-     * @return
+     * @return All currently registered traits, including <em>internal</em> traits.
      */
     Collection<TraitInfo> getRegisteredTraits();
 

src/main/java/net/citizensnpcs/api/trait/trait/Equipment.java

@@ -52,7 +52,7 @@ private ItemStack clone(ItemStack item) {
     /**
      * Get an NPC's equipment from the given slot.
      *
-     * @param slot
+     * @param eslot
      *            Slot where the equipment is located
      * @return ItemStack from the given equipment slot
      */
@@ -236,7 +236,7 @@ private void saveOrRemove(DataKey key, ItemStack item) {
     /**
      * Set the armor from the given slot as the given item.
      *
-     * @param slot
+     * @param eslot
      *            Equipment slot
      * @param item
      *            Item to set the armor as

src/main/java/net/citizensnpcs/api/trait/trait/PlayerFilter.java

@@ -104,6 +104,7 @@ public void addPermission(String permission) {
      * Manages NPC hiding from the provided UUID
      *
      * @param uuid
+     *            A {@link Player}'s UUID.
      */
     public void addPlayer(UUID uuid) {
         if (players == null) {