Fix Javadoc Errors / Warnings (#3265)

Companion to CitizensDev/CitizensAPI#90

Author: TheFlagCourier

main/src/main/java/net/citizensnpcs/Metrics.java

@@ -38,7 +38,7 @@
 /**
  * bStats collects some data for plugin authors.
  * <p>
- * Check out https://bStats.org/ to learn more about bStats!
+ * Check out <a href="https://bStats.org/">bStats.org</a> to learn more about bStats!
  */
 
 public class Metrics {
@@ -471,11 +471,11 @@ public String toString() {
         }
 
         /**
-         * Escapes the given string like stated in https://www.ietf.org/rfc/rfc4627.txt.
+         * Escapes the given string like stated in <a href="https://www.ietf.org/rfc/rfc4627.txt">IETF RFC4627</a>.
          *
          * <p>
-         * This method escapes only the necessary characters '"', '\'. and '\u0000' - '\u001F'. Compact escapes are not
-         * used (e.g., '\n' is escaped as "\u000a" and not as "\n").
+         * This method escapes only the necessary characters '"', '&#92;'. and '&#92;u0000' - '&#92;u001F'.
+         * Compact escapes are not used (e.g., '&#92;n' is escaped as "&#92;u000a" and not as "&#92;n").
          *
          * @param value
          *            The value to escape.

main/src/main/java/net/citizensnpcs/npc/skin/Skin.java

@@ -46,7 +46,6 @@ public class Skin {
      *
      * @param skinName
      *            The name of the player the skin belongs to.
-     * @param forceUpdate
      */
     Skin(String skinName) {
         this.skinName = skinName.toLowerCase(Locale.ROOT);

main/src/main/java/net/citizensnpcs/npc/skin/SkinUpdateTracker.java

@@ -43,9 +43,6 @@ public class SkinUpdateTracker {
 
     /**
      * Constructor.
-     *
-     * @param registries
-     *            Map of other registries.
      */
     public SkinUpdateTracker() {
         updater.runTaskTimer(CitizensAPI.getPlugin(), 1, 1);

main/src/main/java/net/citizensnpcs/trait/Controllable.java

@@ -29,7 +29,7 @@
 
 /**
  * Persists the controllable status for /npc controllable
- *
+ * <p>
  * A controllable {@link NPC} can be mounted by a {@link Player} using right click or /npc mount and moved around using
  * e.g. arrow keys.
  */

main/src/main/java/net/citizensnpcs/trait/EntityPoseTrait.java

@@ -55,10 +55,10 @@ private EntityPose(int id) {
             this.id = id;
         }
 
-        @Deprecated
         /**
-         * Internal minecraft ID
+         * @return Internal minecraft ID
          */
+        @Deprecated
         public int id() {
             return id;
         }

main/src/main/java/net/citizensnpcs/trait/HologramTrait.java

@@ -283,6 +283,7 @@ private void reloadLineHolograms() {
      * Removes the line at the specified index
      *
      * @param idx
+     *            Line Index
      */
     public void removeLine(int idx) {
         if (idx < 0 || idx >= lines.size())
@@ -595,12 +596,18 @@ public static interface HologramRenderer {
         void destroy();
 
         /**
-         * @return Any associated hologram entities. Used in {@link #getEntities()}.
+         * Gets hologram entities associated with the Hologram Trait.
+         * @implNote Known implementations:
+         * <ul>
+         *     <li>{@link ItemRenderer#getEntities()}</li>
+         *     <li>{@link SingleEntityHologramRenderer#getEntities()}</li>
+         * </ul>
+         * @return Any associated hologram entities.
          */
         Collection<Entity> getEntities();
 
         /**
-         * If {@link NPC.Metadata.HOLOGRAM_RENDERER} is set on any entity and ProtocolLib is enabled, this method will
+         * If {@link NPC.Metadata#HOLOGRAM_RENDERER} is set on any entity and ProtocolLib is enabled, this method will
          * be called to modify the name per-player. Note: this should be async-safe. This method is fragile and may be
          * moved elsewhere.
          *
@@ -613,7 +620,7 @@ public static interface HologramRenderer {
         String getPerPlayerText(NPC hologram, Player viewer);
 
         /**
-         * If {@link NPC.Metadata.HOLOGRAM_RENDERER} is set on any entity and ProtocolLib is enabled, returns whether
+         * If {@link NPC.Metadata#HOLOGRAM_RENDERER} is set on any entity and ProtocolLib is enabled, returns whether
          * the NPC should be considered sneaking or not to the viewing player. Presently called only when player first
          * sees the NPC (i.e. not proactively).Note: this should be async-safe. This method is fragile and may be moved
          * elsewhere.
@@ -629,7 +636,7 @@ default boolean isSneaking(NPC npc, Player player) {
         }
 
         /**
-         * If {@link NPC.Metadata.HOLOGRAM_RENDERER} is set on any entity, called when it is seen for the first time by
+         * If {@link NPC.Metadata#HOLOGRAM_RENDERER} is set on any entity, called when it is seen for the first time by
          * a Player.
          *
          * @param hologram
@@ -879,7 +886,7 @@ public void render(NPC npc, Vector3d offset) {
         }
 
         /**
-         * Hologram spawning is delegated to {@link #createNPC(Entity, String, Vector3d)}
+         * Hologram spawning is delegated to {@link #createNPC(NPC, String, Vector3d)}
          */
         protected abstract void render0(NPC npc, Vector3d offset);
 

main/src/main/java/net/citizensnpcs/trait/RotationTrait.java

@@ -462,7 +462,9 @@ public void rotateToFace(Location target) {
          * Rotate to have the given yaw and pitch
          *
          * @param yaw
+         *            Side-to-side rotation along the y-axis
          * @param pitch
+         *            Up-and-down rotation perpendicular to the y-axis
          */
         public void rotateToHave(float yaw, float pitch) {
             t = 0;

main/src/main/java/net/citizensnpcs/trait/text/Text.java

@@ -251,6 +251,7 @@ public void setItemInHandPattern(String pattern) {
      * Set the range in blocks before text will be sent.
      *
      * @param range
+     *            Range blocks (or meters)
      */
     public void setRange(double range) {
         this.range = range;

main/src/main/java/net/citizensnpcs/trait/waypoint/WaypointProvider.java

@@ -13,6 +13,7 @@ public interface WaypointProvider extends Persistable {
      * @param sender
      *            The player to link the editor with
      * @param args
+     *            the {@link CommandContext}, or arguments, to be parsed.
      * @return The editor
      */
     public WaypointEditor createEditor(CommandSender sender, CommandContext args);

main/src/main/java/net/citizensnpcs/trait/waypoint/triggers/WaypointTriggerPrompt.java

@@ -5,11 +5,11 @@
 
 /**
  * Marker interface for waypoint trigger prompts.
- *
+ * <p>
  * Prompts are expected to return to the prompt specified under the {@link #RETURN_PROMPT_KEY} key in the
  * {@link ConversationContext} and to set the specified trigger under {@link #CREATED_TRIGGER_KEY} prior to returning.
- *
- * If the returned trigger is <code>null</code> then the prompt is assumed to have failed and an error message will be
+ * <p>
+ * If the returned trigger is {@code null} then the prompt is assumed to have failed and an error message will be
  * displayed.
  */
 public interface WaypointTriggerPrompt extends Prompt {