From 7c9f03038f2d1a1ed021f7f7838f99be2c95ff67 Mon Sep 17 00:00:00 2001
From: Artemis-the-gr8 <artemis.the.gr8@gmail.com>
Date: Tue, 16 Aug 2022 17:14:22 +0200
Subject: [PATCH] Added javadoc configuration and improved documentation (#100)

---
 .idea/misc.xml                                |  3 +-
 dependency-reduced-pom.xml                    | 39 +++++++++++++++++-
 pom.xml                                       | 40 ++++++++++++++++++-
 .../artemis/the/gr8/playerstats/Main.java     | 16 ++++++++
 .../the/gr8/playerstats/api/ApiFormatter.java |  5 ++-
 .../the/gr8/playerstats/api/PlayerStats.java  |  6 ++-
 .../gr8/playerstats/api/RequestGenerator.java |  2 +-
 .../the/gr8/playerstats/api/StatManager.java  |  6 ++-
 .../the/gr8/playerstats/api/package-info.java |  4 ++
 .../playerstats/listeners/JoinListener.java   |  5 ++-
 .../msg/msgutils/LanguageKeyHandler.java      | 38 ++++++++++++++++--
 11 files changed, 150 insertions(+), 14 deletions(-)
 create mode 100644 src/main/java/com/github/artemis/the/gr8/playerstats/api/package-info.java

diff --git a/.idea/misc.xml b/.idea/misc.xml
index 0ea1570..983b6e5 100644
--- a/.idea/misc.xml
+++ b/.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">
diff --git a/dependency-reduced-pom.xml b/dependency-reduced-pom.xml
index cd70b12..0301fbc 100644
--- a/dependency-reduced-pom.xml
+++ b/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>
diff --git a/pom.xml b/pom.xml
index 1f0d901..5b81367 100644
--- a/pom.xml
+++ b/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>
diff --git a/src/main/java/com/github/artemis/the/gr8/playerstats/Main.java b/src/main/java/com/github/artemis/the/gr8/playerstats/Main.java
index 97b4bcd..8802a60 100644
--- a/src/main/java/com/github/artemis/the/gr8/playerstats/Main.java
+++ b/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();
diff --git a/src/main/java/com/github/artemis/the/gr8/playerstats/api/ApiFormatter.java b/src/main/java/com/github/artemis/the/gr8/playerstats/api/ApiFormatter.java
index b45ab4a..86ef278 100644
--- a/src/main/java/com/github/artemis/the/gr8/playerstats/api/ApiFormatter.java
+++ b/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
- * about the default formatting PlayerStats uses, see the class description of
+ * Formats messages meant for usage outside PlayerStats.
+ * <p> For more information about the default formatting
+ * PlayerStats uses, see the class description of
  * StatResult.
 
  * @see StatResult
diff --git a/src/main/java/com/github/artemis/the/gr8/playerstats/api/PlayerStats.java b/src/main/java/com/github/artemis/the/gr8/playerstats/api/PlayerStats.java
index 3d5bf1a..3a34c04 100644
--- a/src/main/java/com/github/artemis/the/gr8/playerstats/api/PlayerStats.java
+++ b/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
diff --git a/src/main/java/com/github/artemis/the/gr8/playerstats/api/RequestGenerator.java b/src/main/java/com/github/artemis/the/gr8/playerstats/api/RequestGenerator.java
index 4ea376d..865fe50 100644
--- a/src/main/java/com/github/artemis/the/gr8/playerstats/api/RequestGenerator.java
+++ b/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> {
diff --git a/src/main/java/com/github/artemis/the/gr8/playerstats/api/StatManager.java b/src/main/java/com/github/artemis/the/gr8/playerstats/api/StatManager.java
index f559448..56dd71a 100644
--- a/src/main/java/com/github/artemis/the/gr8/playerstats/api/StatManager.java
+++ b/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();
-}
+}
\ No newline at end of file
diff --git a/src/main/java/com/github/artemis/the/gr8/playerstats/api/package-info.java b/src/main/java/com/github/artemis/the/gr8/playerstats/api/package-info.java
new file mode 100644
index 0000000..47869c3
--- /dev/null
+++ b/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;
diff --git a/src/main/java/com/github/artemis/the/gr8/playerstats/listeners/JoinListener.java b/src/main/java/com/github/artemis/the/gr8/playerstats/listeners/JoinListener.java
index acbaaa5..371dbac 100644
--- a/src/main/java/com/github/artemis/the/gr8/playerstats/listeners/JoinListener.java
+++ b/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;
diff --git a/src/main/java/com/github/artemis/the/gr8/playerstats/msg/msgutils/LanguageKeyHandler.java b/src/main/java/com/github/artemis/the/gr8/playerstats/msg/msgutils/LanguageKeyHandler.java
index 90db036..49884b5 100644
--- a/src/main/java/com/github/artemis/the/gr8/playerstats/msg/msgutils/LanguageKeyHandler.java
+++ b/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,
-     * or return null if no enum constant can be retrieved or entityType is UNKNOWN.
+     * @param entity the EntityType to get the Key for
+     * @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";