Fix Javadoc issues and typos (#360)

* fix javadoc

* use external javadocs if necessary

* ShareHandler shouldn't be public

* remove double spaces

Co-authored-by: Ben Woo <[email protected]>

pom.xml

@@ -16,10 +16,6 @@
             <id>onarandombox</id>
             <url>http://repo.onarandombox.com/content/groups/public</url>
         </repository>
-        <repository>
-            <id>spigot</id>
-            <url>https://hub.spigotmc.org/nexus/content/groups/public/</url>
-        </repository>
         <repository>
             <id>spigot-repo</id>
             <url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
@@ -118,10 +114,15 @@ and adjust the build number accordingly -->
                     </execution>
                 </executions>
             </plugin>
-            <!-- javadocs are broken!
             <plugin>
                 <artifactId>maven-javadoc-plugin</artifactId>
-                <version>2.8.1</version>
+                <version>2.10.4</version>
+                <configuration>
+                    <links>
+                        <link>https://papermc.io/javadocs/paper/1.14/</link>
+                    </links>
+                    <additionalJOption>-J-Dhttp.agent=placeholder</additionalJOption>
+                </configuration>
                 <executions>
                     <execution>
                         <id>javadoc-jar</id>
@@ -132,7 +133,6 @@ and adjust the build number accordingly -->
                     </execution>
                 </executions>
             </plugin>
-            -->
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-surefire-plugin</artifactId>

src/main/java/com/onarandombox/multiverseinventories/DataStrings.java

@@ -1,21 +1,16 @@
 package com.onarandombox.multiverseinventories;
 
 import com.dumptruckman.minecraft.util.Logging;
-import com.onarandombox.multiverseinventories.util.MinecraftTools;
 import net.minidev.json.JSONArray;
 import net.minidev.json.JSONObject;
 import net.minidev.json.parser.JSONParser;
 import net.minidev.json.parser.ParseException;
 import org.bukkit.Bukkit;
 import org.bukkit.Location;
-import org.bukkit.Material;
 import org.bukkit.World;
-import org.bukkit.enchantments.Enchantment;
-import org.bukkit.inventory.ItemStack;
 import org.bukkit.potion.PotionEffect;
 import org.bukkit.potion.PotionEffectType;
 
-import java.util.LinkedHashMap;
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
@@ -42,7 +37,7 @@ public class DataStrings {
      */
     public static final String PLAYER_ARMOR_CONTENTS = "armorContents";
     /**
-     * Player armor contents identifier.
+     * Player off hand item identifier.
      */
     public static final String PLAYER_OFF_HAND_ITEM = "offHandItem";
     /**
@@ -54,7 +49,7 @@ public class DataStrings {
      */
     public static final String PLAYER_BED_SPAWN_LOCATION = "bedSpawnLocation";
     /**
-     * Player bed spawn location identifier.
+     * Player last location identifier.
      */
     public static final String PLAYER_LAST_LOCATION = "lastLocation";
     /**
@@ -70,23 +65,23 @@ public class DataStrings {
      */
     public static final String PLAYER_LAST_KNOWN_NAME = "lastKnownName";
     /**
-     * Player bed spawn location identifier.
+     * Player profile type identifier.
      */
     public static final String PLAYER_PROFILE_TYPE = "profileType";
     /**
      * Player health identifier.
      */
     public static final String PLAYER_HEALTH = "hp";
     /**
-     * Player exp identifier.
+     * Player experience identifier.
      */
     public static final String PLAYER_EXPERIENCE = "xp";
     /**
-     * Player total exp identifier.
+     * Player total experience identifier.
      */
     public static final String PLAYER_TOTAL_EXPERIENCE = "txp";
     /**
-     * Player exp level identifier.
+     * Player experience level identifier.
      */
     public static final String PLAYER_LEVEL = "el";
     /**
@@ -114,7 +109,7 @@ public class DataStrings {
      */
     public static final String PLAYER_REMAINING_AIR = "ra";
     /**
-     * Player saturation identifier.
+     * Player max air identifier.
      */
     public static final String PLAYER_MAX_AIR = "ma";
     /**
@@ -161,7 +156,8 @@ private DataStrings() {
     /**
      * @param locString Parses this string and creates Location.
      * @return New location object or null if no location could be created.
-     * @deprecated Locations do not use special handling because they are {@link org.bukkit.configuration.serialization.ConfigurationSerializable}
+     * @deprecated Locations do not use special handling because they are
+     *             {@link org.bukkit.configuration.serialization.ConfigurationSerializable}.
      */
     @Deprecated
     public static Location parseLocation(String locString) {
@@ -182,7 +178,8 @@ public static Location parseLocation(String locString) {
     }
 
     /**
-     * @deprecated Locations do not use special handling because they are {@link org.bukkit.configuration.serialization.ConfigurationSerializable}
+     * @deprecated Locations do not use special handling because they are
+     *             {@link org.bukkit.configuration.serialization.ConfigurationSerializable}.
      */
     @Deprecated
     public static Location parseLocation(Map locMap) {
@@ -237,9 +234,11 @@ private static Location parseLocMap(Map locMap) {
     }
 
     /**
-     * @param potionsString A player's potion effects in string form to be parsed into Collection<PotionEffect>.
+     * @param potionsString A player's potion effects in string form to be parsed into
+     *                      {@link java.util.Collection}&lt;{@link org.bukkit.potion.PotionEffect}&gt;.
      * @return a collection of potion effects parsed from potionsString.
-     * @deprecated PotionEffect do not use special handling because they are {@link org.bukkit.configuration.serialization.ConfigurationSerializable}
+     * @deprecated PotionEffect do not use special handling because they are
+     *             {@link org.bukkit.configuration.serialization.ConfigurationSerializable}.
      */
     @Deprecated
     public static PotionEffect[] parsePotionEffects(String potionsString) {

src/main/java/com/onarandombox/multiverseinventories/ShareHandler.java

@@ -54,6 +54,9 @@ protected final void addWriteProfile(PlayerProfile profile, Shares shares) {
     }
 
     /**
+     * Finalizes the transfer from one world to another. This handles the switching
+     * inventories/stats for a player and persisting the changes.
+     *
      * @param profile   The player profile that will need data loaded from.
      * @param shares    What from this group needs to be loaded.
      */

src/main/java/com/onarandombox/multiverseinventories/WorldGroup.java

@@ -148,7 +148,7 @@ public Set<String> getWorlds() {
     }
 
     /**
-     * Checks if this group is sharing sharable.  This will check both shares and negative shares of the group.
+     * Checks if this group is sharing sharable. This will check both shares and negative shares of the group.
      * This is the preferred method for checking if a group shares something as shares may contain ALL shares while
      * ones indicated in negative shares means those aren't actually shared.
      *
@@ -160,7 +160,7 @@ public boolean isSharing(Sharable sharable) {
     }
 
     /**
-     * Retrieves the shares for this World Group.  Any changes to this group must be subsequently saved to the data
+     * Retrieves the shares for this World Group. Any changes to this group must be subsequently saved to the data
      * source for the changes to be permanent.
      *
      * @return The shares for this World Group.

src/main/java/com/onarandombox/multiverseinventories/locale/LazyLocaleMessageProvider.java

@@ -4,15 +4,15 @@
 import java.util.Set;
 
 /**
- * Multiverse 2 LazyMessageProvider
- * <p/>
+ * <p>Multiverse 2 LazyMessageProvider</p>
+ *
  * This interface describes a Multiverse-MessageProvider that only loads locales when they're needed.
  */
 public interface LazyLocaleMessageProvider extends MessageProvider {
 
     /**
-     * Loads a localization for a specified {@link Locale}.
-     * <p/>
+     * <p>Loads a localization for a specified {@link Locale}.</p>
+     *
      * If that localization is already loaded, this method will reload it.
      *
      * @param locale The desired {@link Locale}.

src/main/java/com/onarandombox/multiverseinventories/locale/MessageProvider.java

@@ -4,8 +4,8 @@
 import java.util.Locale;
 
 /**
- * Multiverse 2 MessageProvider.
- * <p/>
+ * <p>Multiverse 2 MessageProvider.</p>
+ *
  * This interface describes a Multiverse-MessageProvider.
  */
 public interface MessageProvider {

src/main/java/com/onarandombox/multiverseinventories/profile/GlobalProfile.java

@@ -112,7 +112,7 @@ public void setLoadOnLogin(boolean loadOnLogin) {
     }
 
     /**
-     * Sets the last world the player was known to be in.  This is done automatically on world change.
+     * Sets the last world the player was known to be in. This is done automatically on world change.
      *
      * @param world The world the player is in.
      */

src/main/java/com/onarandombox/multiverseinventories/profile/PlayerProfile.java

@@ -76,7 +76,7 @@ public ProfileType getProfileType() {
      *
      * @param sharable Represents the key for the data wanted from the profile.
      * @param <T>      This indicates the type of return value to be expected.
-     * @return The value of the sharable for this profile.  Null if no value is set.
+     * @return The value of the sharable for this profile. Null if no value is set.
      */
     public <T> T get(Sharable<T> sharable) {
         SharableEntry entry = this.data.get(sharable);

src/main/java/com/onarandombox/multiverseinventories/profile/ProfileDataSource.java

@@ -25,7 +25,7 @@ public interface ProfileDataSource {
      * @param dataName   World/Group to retrieve from.
      * @param profileType The type of profile to load data for, typically based on game mode.
      * @param playerUUID UUID of the player to retrieve for.
-     * @return The player as returned from data.  If no data was found, a new PlayerProfile will be
+     * @return The player as returned from data. If no data was found, a new PlayerProfile will be
      *         created.
      */
     PlayerProfile getPlayerData(ContainerType containerType, String dataName, ProfileType profileType, UUID playerUUID);
@@ -35,7 +35,7 @@ public interface ProfileDataSource {
      *
      * @param containerType The type of container this profile is part of, world or group.
      * @param dataName   The name of the world/group the player's data is associated with.
-     * @param profileType The type of profile we're removing, as per {@link ProfileType}.  If null, this will remove
+     * @param profileType The type of profile we're removing, as per {@link ProfileType}. If null, this will remove
      *                    remove all profile types.
      * @param playerName The name of the player whose data is being removed.
      * @return True if successfully removed.

src/main/java/com/onarandombox/multiverseinventories/profile/ProfileType.java

@@ -16,7 +16,7 @@ private ProfileType(String name) {
     }
 
     /**
-     * @return The name of the profile.  The default profile type will return a blank string.
+     * @return The name of the profile. The default profile type will return a blank string.
      */
     public String getName() {
         return name;

src/main/java/com/onarandombox/multiverseinventories/profile/WorldGroupManager.java

@@ -11,8 +11,8 @@
 public interface WorldGroupManager {
 
     /**
-     * Retrieves the world group associated with the given name.
-     * <p/>
+     * <p>Retrieves the world group associated with the given name.</p>
+     *
      * These groups represent the groups that define a set of worlds and what they share.
      *
      * @param groupName Name of world group to retrieve. Casing is ignored.
@@ -21,8 +21,8 @@ public interface WorldGroupManager {
     WorldGroup getGroup(String groupName);
 
     /**
-     * Returns a list of all the world groups defined in Multiverse-Inventories's groups configuration.
-     * <p/>
+     * <p>Returns a list of all the world groups defined in Multiverse-Inventories's groups configuration.</p>
+     *
      * This list is unmodifiable.
      *
      * @return An unmodifiable list of all world groups.
@@ -57,21 +57,21 @@ public interface WorldGroupManager {
     /**
      * Adds a World Group to the collection in memory, also writing it to the groups configuration.
      *
-     * @param worldGroup World group to add.  Casing is ignored.
+     * @param worldGroup World group to add. Casing is ignored.
      * @param persist    This parameter is unused due to deprecation of the method.
      * @deprecated
      */
     @Deprecated
     void addGroup(WorldGroup worldGroup, boolean persist);
 
     /**
-     * Adds or updates a world group in Multiverse-Inventories.
-     * <p/>
-     * This will update an existing group by persisting changes made to it in the groups configuration.
-     * This should be called when any of the facets of a group such as worlds or shares have been modified.
-     * <p/>
-     * If the group does not exist it will be added to the groups configuration.
-     * <p/>
+     * <p>Adds or updates a world group in Multiverse-Inventories.</p>
+     *
+     * <p>This will update an existing group by persisting changes made to it in the groups configuration.
+     * This should be called when any of the facets of a group such as worlds or shares have been modified.</p>
+     *
+     * <p>If the group does not exist it will be added to the groups configuration.</p>
+     *
      * If worldGroup's name matches the name of a different WorldGroupProfileContainer object that is already
      * known, the previous object will be overwritten with worldGroup parameter.
      *
@@ -88,11 +88,10 @@ public interface WorldGroupManager {
     boolean removeGroup(WorldGroup worldGroup);
 
     /**
-     * Creates a new empty world group.
-     * <p/>
+     * <p>Creates a new empty world group.</p>
+     *
      * Please note if you do not add worlds to this group it will not persist very well.
-     * This does not automatically persist the new group.  It must bed added via
-     * {@link #updateGroup(WorldGroup)}
+     * This does not automatically persist the new group. It must bed added via {@link #updateGroup(WorldGroup)}.
      *
      * @param name A name for the new group.
      * @return The newly created world group.
@@ -119,7 +118,7 @@ public interface WorldGroupManager {
     /**
      * Runs a check for conflicts between groups and displays them to console and sender if not null.
      *
-     * @param sender The sender to relay information to.  If null, info only displayed in console.
+     * @param sender The sender to relay information to. If null, info only displayed in console.
      */
     void checkForConflicts(CommandSender sender);
 }

src/main/java/com/onarandombox/multiverseinventories/share/DefaultSerializer.java

@@ -1,7 +1,7 @@
 package com.onarandombox.multiverseinventories.share;
 
 /**
- * The default Sharable serializer.  It performs no special tasks on the objects being sent to persistence, they are
+ * The default Sharable serializer. It performs no special tasks on the objects being sent to persistence, they are
  * sent as is.
  *
  * @param <T> The type of data this serializer serializes.

src/main/java/com/onarandombox/multiverseinventories/share/DefaultStringSerializer.java

@@ -10,7 +10,7 @@
  * This Sharable serializer attempts to deserialize the string form of objects passed to it through use of
  * T.valueOf(String). Likewise, it serializes data simply by calling Object.toString() on the value passed in.
  *
- * @param <T> The type of data this serializer serializes.  This class MUST have a static valueOf(String) method that
+ * @param <T> The type of data this serializer serializes. This class MUST have a static valueOf(String) method that
  *            returns it's type.
  */
 final class DefaultStringSerializer<T> implements SharableSerializer<T> {

src/main/java/com/onarandombox/multiverseinventories/share/PersistingProfile.java

@@ -3,15 +3,14 @@
 import com.onarandombox.multiverseinventories.profile.PlayerProfile;
 
 /**
- * Simple interface for groups that are going to be saved/loaded.  This is used specifically for when a user's world
+ * Simple interface for groups that are going to be saved/loaded. This is used specifically for when a user's world
  * change is being handled.
  */
 public interface PersistingProfile {
 
     /**
-     * @return The shares that will be saved/loaded for.  This set are all the sharable things
-     *         that will be acted upon when passed through
-     *         {@link com.onarandombox.multiverseinventories.ShareHandler}
+     * @return The shares that will be saved/loaded for the profile. This is the set of all Sharables that will be acted
+     *         upon when passed through the ShareHandler class, or any of its subclasses.
      */
     Shares getShares();
 

src/main/java/com/onarandombox/multiverseinventories/share/ProfileEntry.java

@@ -4,7 +4,7 @@
 import java.util.Map;
 
 /**
- * Indicates how a Sharable should be stored in the profile file.  Serves as a lookup for finding a sharable based on
+ * Indicates how a Sharable should be stored in the profile file. Serves as a lookup for finding a sharable based on
  * it's file tag.
  */
 public final class ProfileEntry {