Added javadoc configuration and improved documentation (#100)

.idea/misc.xml

@@ -7,7 +7,8 @@
   </component>
   <component name="ExternalStorageConfigurationManager" enabled="true" />
   <component name="JavadocGenerationManager">
-    <option name="OUTPUT_DIRECTORY" value="$PROJECT_DIR$/javadoc" />
+    <option name="OUTPUT_DIRECTORY" value="$PROJECT_DIR$/target/apidocs" />
+    <option name="OPTION_SCOPE" value="public" />
   </component>
   <component name="MavenProjectsManager">
     <option name="originalFiles">

dependency-reduced-pom.xml

@@ -115,7 +115,7 @@
       </plugin>
       <plugin>
         <artifactId>maven-javadoc-plugin</artifactId>
-        <version>3.2.0</version>
+        <version>3.4.1</version>
         <executions>
           <execution>
             <id>attach-javadocs</id>
@@ -124,6 +124,43 @@
             </goals>
           </execution>
         </executions>
+        <configuration>
+          <name>PlayerStats Javadocs</name>
+          <docTitle>PlayerStats Javadocs</docTitle>
+          <additionalOptions>-Xdoclint:none</additionalOptions>
+          <failOnError>false</failOnError>
+          <quiet>true</quiet>
+          <show>protected</show>
+          <groups>
+            <group>
+              <title>API</title>
+              <packages>com.github.artemis.the.gr8.playerstats.api</packages>
+            </group>
+          </groups>
+          <detectLinks>true</detectLinks>
+          <dependencyLinks>
+            <dependencyLink>
+              <groupId>org.spigotmc</groupId>
+              <artifactId>spigot-api</artifactId>
+              <url>https://hub.spigotmc.org/javadocs/bukkit/</url>
+            </dependencyLink>
+            <dependencyLink>
+              <groupId>net.kyori</groupId>
+              <artifactId>adventure-api</artifactId>
+              <url>https://jd.adventure.kyori.net/api/4.11.0/</url>
+            </dependencyLink>
+            <dependencyLink>
+              <groupId>net.kyori</groupId>
+              <artifactId>adventure-text-minimessage</artifactId>
+              <url>https://jd.adventure.kyori.net/text-minimessage/4.11.0/</url>
+            </dependencyLink>
+            <dependencyLink>
+              <groupId>net.kyori</groupId>
+              <artifactId>adventure-platform-bukkit</artifactId>
+              <url>https://jd.adventure.kyori.net/</url>
+            </dependencyLink>
+          </dependencyLinks>
+        </configuration>
       </plugin>
     </plugins>
   </build>

pom.xml

@@ -209,7 +209,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
-                <version>3.2.0</version>
+                <version>3.4.1</version>
                 <executions>
                     <execution>
                         <id>attach-javadocs</id>
@@ -218,6 +218,44 @@
                         </goals>
                     </execution>
                 </executions>
+                <configuration>
+                    <additionalOptions>-Xdoclint:none</additionalOptions>
+                    <failOnError>false</failOnError>
+                    <quiet>true</quiet>
+                    <show>protected</show>
+                    <groups>
+                        <group>
+                            <title>API</title>
+                            <packages>com.github.artemis.the.gr8.playerstats.api</packages>
+                        </group>
+                    </groups>
+                    <detectLinks>true</detectLinks>
+                    <dependencyLinks>
+                        <dependencyLink>
+                            <groupId>org.spigotmc</groupId>
+                            <artifactId>spigot-api</artifactId>
+                            <url>https://hub.spigotmc.org/javadocs/bukkit/</url>
+                        </dependencyLink>
+
+                        <dependencyLink>
+                            <groupId>net.kyori</groupId>
+                            <artifactId>adventure-api</artifactId>
+                            <url>https://jd.adventure.kyori.net/api/4.11.0/</url>
+                        </dependencyLink>
+
+                        <dependencyLink>
+                            <groupId>net.kyori</groupId>
+                            <artifactId>adventure-text-minimessage</artifactId>
+                            <url>https://jd.adventure.kyori.net/text-minimessage/4.11.0/</url>
+                        </dependencyLink>
+
+                        <dependencyLink>
+                            <groupId>net.kyori</groupId>
+                            <artifactId>adventure-platform-bukkit</artifactId>
+                            <url>https://jd.adventure.kyori.net/</url>
+                        </dependencyLink>
+                    </dependencyLinks>
+                </configuration>
             </plugin>
         </plugins>
     </build>

src/main/java/com/github/artemis/the/gr8/playerstats/Main.java

@@ -26,6 +26,10 @@ import org.bukkit.plugin.java.JavaPlugin;
 import org.bukkit.scheduler.BukkitRunnable;
 import org.jetbrains.annotations.NotNull;
 
+
+/**
+ * PlayerStats' Main class
+ */
 public final class Main extends JavaPlugin {
 
     private static Main instance;
@@ -77,6 +81,10 @@ public final class Main extends JavaPlugin {
         this.getLogger().info("Disabled PlayerStats!");
     }
 
+    /**
+     * @return Adventure's BukkitAudiences object
+     * @throws IllegalStateException if PlayerStats is not enabled
+     */
     public static @NotNull BukkitAudiences getAdventure() throws IllegalStateException {
         if (adventure == null) {
             throw new IllegalStateException("Tried to access Adventure without PlayerStats being enabled!");
@@ -84,6 +92,10 @@ public final class Main extends JavaPlugin {
         return adventure;
     }
 
+    /**
+     * @return PlayerStats' ConfigHandler
+     * @throws IllegalStateException if PlayerStats is not enabled
+     */
     public static @NotNull ConfigHandler getConfigHandler() throws IllegalStateException {
         if (config == null) {
             throw new IllegalStateException("PlayerStats does not seem to be loaded!");
@@ -105,6 +117,10 @@ public final class Main extends JavaPlugin {
         return languageKeyHandler;
     }
 
+    /**
+     * Gets the EnumHandler. If there is no EnumHandler, one will be created.
+     * @return PlayerStat's EnumHandler
+     */
     public static @NotNull EnumHandler getEnumHandler() {
         if (enumHandler == null) {
             enumHandler = new EnumHandler();

src/main/java/com/github/artemis/the/gr8/playerstats/api/ApiFormatter.java

@@ -9,8 +9,9 @@ import org.bukkit.Statistic;
 import org.jetbrains.annotations.Nullable;
 
 /**
- * Formats messages meant for usage outside PlayerStats. For more information
+ * Formats messages meant for usage outside PlayerStats.
- * about the default formatting PlayerStats uses, see the class description of
+ * <p> For more information about the default formatting
+ * PlayerStats uses, see the class description of
  * StatResult.
 
  * @see StatResult

src/main/java/com/github/artemis/the/gr8/playerstats/api/PlayerStats.java

@@ -5,8 +5,10 @@ import com.github.artemis.the.gr8.playerstats.statistic.request.StatRequest;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
 
-/** The outgoing API that you can use to access the core functionality of PlayerStats!
+/**
- * To work with the API, you need to call PlayerStats.{@link #getAPI()} to get an instance of
+ * The outgoing API that represents the core functionality of PlayerStats!
+ *
+ * <p> To work with it, you'll need to call PlayerStats.{@link #getAPI()} to get an instance of
  * {@link PlayerStatsAPI}. You can then use this object to access any of the further methods.
  * <br>
  * <br>Since calculating a top or server statistics can take some time, I strongly

src/main/java/com/github/artemis/the/gr8/playerstats/api/RequestGenerator.java

@@ -7,7 +7,7 @@ import org.bukkit.Statistic;
 import org.bukkit.entity.EntityType;
 import org.jetbrains.annotations.NotNull;
 
-/** Is responsible for creating an executable {@link StatRequest}. This Request holds all
+/** Creates an executable {@link StatRequest}. This Request holds all
  * the information PlayerStats needs to work with, and is used by the {@link StatCalculator}
  * to get the desired statistic data.*/
 public interface RequestGenerator<T> {

src/main/java/com/github/artemis/the/gr8/playerstats/api/StatManager.java

@@ -1,7 +1,11 @@
 package com.github.artemis.the.gr8.playerstats.api;
 
+import com.github.artemis.the.gr8.playerstats.statistic.request.StatRequest;
 import java.util.LinkedHashMap;
 
+/**
+ * Turns user input into a {@link StatRequest} that can be used to get statistic data
+ */
 public interface StatManager {
 
     /** Gets a RequestGenerator that can be used to create a PlayerStatRequest.
@@ -34,4 +38,4 @@ public interface StatManager {
      *
      * @return the RequestGenerator*/
     RequestGenerator<LinkedHashMap<String, Integer>> totalTopStatRequest();
-}
+}

src/main/java/com/github/artemis/the/gr8/playerstats/api/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * The PlayerStats API
+ */
+package com.github.artemis.the.gr8.playerstats.api;

src/main/java/com/github/artemis/the/gr8/playerstats/listeners/JoinListener.java

@@ -4,10 +4,13 @@ import com.github.artemis.the.gr8.playerstats.ThreadManager;
 import org.bukkit.event.EventHandler;
 import org.bukkit.event.Listener;
 import org.bukkit.event.player.PlayerJoinEvent;
+import org.jetbrains.annotations.ApiStatus;
 
-/** Listens for new Players that join, and reloads PlayerStats
+/**
+ * Listens for new Players that join, and reloads PlayerStats
  * if someone joins that hasn't joined before.
  */
+@ApiStatus.Internal
 public class JoinListener implements Listener {
 
     private static ThreadManager threadManager;

src/main/java/com/github/artemis/the/gr8/playerstats/msg/msgutils/LanguageKeyHandler.java

@@ -11,6 +11,7 @@ import org.bukkit.configuration.file.YamlConfiguration;
 import org.bukkit.entity.EntityType;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.ApiStatus.Internal;
 
 import java.io.File;
 import java.util.Arrays;
@@ -28,6 +29,9 @@ public final class LanguageKeyHandler {
     private static File languageKeyFile;
     private static FileConfiguration languageKeys;
 
+    /**
+     * @param plugin an instance of PlayerStats' Main class
+     */
     public LanguageKeyHandler(Main plugin) {
         LanguageKeyHandler.plugin = plugin;
         statNameKeys = generateStatNameKeys();
@@ -42,6 +46,7 @@ public final class LanguageKeyHandler {
         languageKeys = YamlConfiguration.loadConfiguration(languageKeyFile);
     }
 
+    @Internal
     public static void reloadFile() {
         if (!languageKeyFile.exists()) {
             loadFile();
@@ -54,6 +59,9 @@ public final class LanguageKeyHandler {
     /**
      * Checks if a given Key is the language key "stat_type.minecraft.killed"
      * or "commands.kill.success.single" (which results in "Killed %s").
+     *
+     * @param statKey the Key to check
+     * @return true if this Key is key for kill-entity
      */
     public static boolean isKeyForKillEntity(String statKey) {
         return statKey.equalsIgnoreCase("stat_type.minecraft.killed") ||
@@ -72,6 +80,9 @@ public final class LanguageKeyHandler {
     /**
      * Checks if a given Key is the language key "stat_type.minecraft.killed_by"
      * or "stat.minecraft.deaths" (which results in "Number of Deaths").
+     *
+     * @param statKey the Key to check
+     * @return true if this Key is a key for entity-killed-by
      */
     public static boolean isKeyForEntityKilledBy(String statKey) {
         return statKey.equalsIgnoreCase("stat_type.minecraft.killed_by") ||
@@ -91,6 +102,9 @@ public final class LanguageKeyHandler {
     /**
      * Checks if a given Key is the language key "book.byAuthor"
      * (which results in "by %s").
+     *
+     * @param statKey the Key to Check
+     * @return true if this Key is the key for book.byAuthor
      */
     public static boolean isKeyForEntityKilledByArg(String statKey) {
         return statKey.equalsIgnoreCase("book.byAuthor");
@@ -106,6 +120,10 @@ public final class LanguageKeyHandler {
         return "book.byAuthor";
     }
 
+    /**
+     * @param key the String to turn into a normal name
+     * @return a pretty name
+     */
     public static String convertToName(String key) {
         if (key.equalsIgnoreCase("soundCategory.block")) {
             return Unit.BLOCK.getLabel();
@@ -154,6 +172,11 @@ public final class LanguageKeyHandler {
         return languageKeys.getString(realKey);
     }
 
+    /**
+     * @param statistic the Statistic to get the Key for
+     * @return the official Key from the NameSpacedKey for this Statistic,
+     * or return null if no enum constant can be retrieved.
+     */
     public String getStatKey(@NotNull Statistic statistic) {
         if (statistic.getType() == Statistic.Type.UNTYPED) {
             return "stat.minecraft." + statNameKeys.get(statistic);
@@ -164,8 +187,9 @@ public final class LanguageKeyHandler {
     }
 
     /**
-     * Get the official Key from the NameSpacedKey for this entityType,
+     * @param entity the EntityType to get the Key for
-     * or return null if no enum constant can be retrieved or entityType is UNKNOWN.
+     * @return the official Key from the NameSpacedKey for this EntityType,
+     * or return null if no enum constant can be retrieved or EntityType is UNKNOWN.
      */
     public @Nullable String getEntityKey(EntityType entity) {
         if (entity == null || entity == EntityType.UNKNOWN) return null;
@@ -175,7 +199,8 @@ public final class LanguageKeyHandler {
     }
 
     /**
-     * Get the official Key from the NameSpacedKey for this item Material,
+     * @param item the Material to get the Key for
+     * @return the official Key from the NameSpacedKey for this item Material,
      * or return null if no enum constant can be retrieved.
      */
     public @Nullable String getItemKey(Material item) {
@@ -189,7 +214,8 @@ public final class LanguageKeyHandler {
     }
 
     /**
-     * Returns the official Key from the NameSpacedKey for the block Material provided,
+     * @param block the Material to get the Key for
+     * @return the official Key from the NameSpacedKey for the block Material provided,
      * or return null if no enum constant can be retrieved.
      */
     public @Nullable String getBlockKey(Material block) {
@@ -204,6 +230,10 @@ public final class LanguageKeyHandler {
         }
     }
 
+    /**
+     * @param unit the Unit to get the Key for
+     * @return "soundCategory.block" for Unit.Block, null otherwise
+     */
     public @Nullable String getUnitKey(Unit unit) {
         if (unit == Unit.BLOCK) {
             return "soundCategory.block";