Add documentation

3 files changed, 89 insertions, 22 deletions

diff --git a/src/main/java/com/leonardobishop/quests/player/QPlayerManager.java b/src/main/java/com/leonardobishop/quests/player/QPlayerManager.java
index ac7504fe..ba942978 100644
--- a/src/main/java/com/leonardobishop/quests/player/QPlayerManager.java
+++ b/src/main/java/com/leonardobishop/quests/player/QPlayerManager.java
@@ -45,7 +45,7 @@ public class QPlayerManager {
     }
 
     /**
-     * Unloads and saves the player to disk.
+     * Unloads and saves the player to disk. Must be invoked from the main thread.
      *
      * @param uuid the uuid of the player
      */
@@ -76,7 +76,7 @@ public class QPlayerManager {
 
     /**
      * Load the player from disk if they exist, otherwise create a new {@link QuestProgressFile}.
-     * Will have no effect if player is already loaded.
+     * This will have no effect if player is already loaded. Can be invoked asynchronously.
      *
      * @param uuid the uuid of the player
      */
@@ -91,6 +91,7 @@ public class QPlayerManager {
                     File file = new File(plugin.getDataFolder() + File.separator + "playerdata" + File.separator + uuid.toString() + ".yml");
                     if (file.exists()) {
                         YamlConfiguration data = YamlConfiguration.loadConfiguration(file);
+                        plugin.getQuestsLogger().debug("Player " + uuid + " has a valid quest progress file.");
                         if (data.isConfigurationSection("quest-progress")) { //Same job as "isSet" + it checks if is CfgSection
                             for (String id : data.getConfigurationSection("quest-progress").getKeys(false)) {
                                 boolean started = data.getBoolean("quest-progress." + id + ".started");
diff --git a/src/main/java/com/leonardobishop/quests/player/questprogressfile/QuestProgressFile.java b/src/main/java/com/leonardobishop/quests/player/questprogressfile/QuestProgressFile.java
index 16ccd020..b2596079 100644
--- a/src/main/java/com/leonardobishop/quests/player/questprogressfile/QuestProgressFile.java
+++ b/src/main/java/com/leonardobishop/quests/player/questprogressfile/QuestProgressFile.java
@@ -42,6 +42,16 @@ public class QuestProgressFile {
         this.plugin = plugin;
     }
 
+    /**
+     * Attempt to complete a quest for the player. This will also play all effects (such as titles, messages etc.)
+     * and also dispatches all rewards for the player.
+     *
+     * Warning: rewards will not be sent and the {@link PlayerFinishQuestEvent} will not be fired if the
+     * player is not online
+     *
+     * @param quest the quest to complete
+     * @return true (always)
+     */
     public boolean completeQuest(Quest quest) {
         QuestProgress questProgress = getQuestProgress(quest);
         questProgress.setStarted(false);
@@ -82,7 +92,15 @@ public class QuestProgressFile {
         return true;
     }
 
+    /**
+     * Attempt to track a quest for the player. This will also play all effects (such as titles, messages etc.)
+     *
+     * Warning: will fail if the player is not online.
+     *
+     * @param quest the quest to track
+     */
     public void trackQuest(Quest quest) {
+        //TODO change how this works
         Player player = Bukkit.getPlayer(playerUUID);
         if (quest == null) {
             playerPreferences.setTrackedQuestId(null);
@@ -99,7 +117,7 @@ public class QuestProgressFile {
 
     /**
      * Check if the player can start a quest.
-     * <p>
+     *
      * Warning: will fail if the player is not online.
      *
      * @param quest the quest to check
@@ -150,12 +168,12 @@ public class QuestProgressFile {
     }
 
     /**
-     * Start a quest for the player.
-     * <p>
+     * Attempt to start a quest for the player. This will also play all effects (such as titles, messages etc.)
+     *
      * Warning: will fail if the player is not online.
      *
-     * @param quest the quest to check
-     * @return the quest start result
+     * @param quest the quest to start
+     * @return the quest start result -- {@code QuestStartResult.QUEST_SUCCESS} indicates success
      */
     // TODO PlaceholderAPI support
     public QuestStartResult startQuest(Quest quest) {
@@ -239,6 +257,12 @@ public class QuestProgressFile {
         return code;
     }
 
+    /**
+     * Attempt to cancel a quest for the player. This will also play all effects (such as titles, messages etc.)
+     *
+     * @param quest the quest to start
+     * @return true if the quest was cancelled, false otherwise
+     */
     public boolean cancelQuest(Quest quest) {
         QuestProgress questProgress = getQuestProgress(quest);
         Player player = Bukkit.getPlayer(this.playerUUID);
@@ -269,6 +293,13 @@ public class QuestProgressFile {
         this.questProgress.put(questProgress.getQuestId(), questProgress);
     }
 
+    /**
+     * Gets all started quests.
+     * Note: if quest autostart is enabled then this may produce unexpected results as quests are
+     * not "started" by the player if autostart is true. Consider {@link #hasStartedQuest(Quest)} instead.
+     *
+     * @return
+     */
     public List<Quest> getStartedQuests() {
         List<Quest> startedQuests = new ArrayList<>();
         for (QuestProgress questProgress : questProgress.values()) {
@@ -280,19 +311,7 @@ public class QuestProgressFile {
     }
 
     /**
-     * @return {@code List<Quest>} all quest
-     * @deprecated use {@code getAllQuestsFromProgress(QuestsProgressFilter)} instead
-     * <p>
-     * Returns all {@code Quest}s a player has encountered
-     * (not to be confused with a collection of quest progress)
-     */
-    @Deprecated
-    public List<Quest> getQuestsProgress(String filter) {
-        return getAllQuestsFromProgress(QuestsProgressFilter.fromLegacy(filter));
-    }
-
-    /**
-     * Returns all {@code Quest}s a player has encountered
+     * Returns all {@link Quest} a player has encountered
      * (not to be confused with a collection of quest progress)
      *
      * @return {@code List<Quest>} all quests
@@ -353,10 +372,22 @@ public class QuestProgressFile {
         return questProgress.values();
     }
 
+    /**
+     * Checks whether or not the player has {@link QuestProgress} for a specified quest
+     *
+     * @param quest the quest to check for
+     * @return true if they have quest progress
+     */
     public boolean hasQuestProgress(Quest quest) {
         return questProgress.containsKey(quest.getId());
     }
 
+    /**
+     * Gets whether or not the player has started a specific quest.
+     *
+     * @param quest the quest to test for
+     * @return true if the quest is started or quest autostart is enabled and the quest is ready to start, false otherwise
+     */
     public boolean hasStartedQuest(Quest quest) {
         if (Options.QUEST_AUTOSTART.getBooleanValue()) {
             QuestStartResult response = canStartQuest(quest);
@@ -366,6 +397,12 @@ public class QuestProgressFile {
         }
     }
 
+    /**
+     * Gets the remaining cooldown before being able to start a specific quest.
+     *
+     * @param quest the quest to test for
+     * @return 0 if no cooldown remaining or the cooldown is disabled, otherwise the cooldown in milliseconds
+     */
     public long getCooldownFor(Quest quest) {
         QuestProgress questProgress = getQuestProgress(quest);
         if (quest.isCooldownEnabled() && questProgress.isCompleted()) {
@@ -377,6 +414,12 @@ public class QuestProgressFile {
         return 0;
     }
 
+    /**
+     * Tests whether or not the player meets the requirements to start a specific quest.
+     *
+     * @param quest the quest to test for
+     * @return true if they can start the quest
+     */
     public boolean hasMetRequirements(Quest quest) {
         for (String id : quest.getRequirements()) {
             Quest q = plugin.getQuestManager().getQuestById(id);
@@ -392,10 +435,21 @@ public class QuestProgressFile {
         return true;
     }
 
+    /**
+     * Get the {@link UUID} of the player this QuestProgressFile represents
+     *
+     * @return UUID
+     */
     public UUID getPlayerUUID() {
         return playerUUID;
     }
 
+    /**
+     * Get the {@link QuestProgress} for a specified {@link Quest}, and generates a new one if it does not exist
+     *
+     * @param quest the quest to get progress for
+     * @return {@link QuestProgress} or null if the quest does not exist
+     */
     public QuestProgress getQuestProgress(Quest quest) {
         if (questProgress.containsKey(quest.getId())) {
             return questProgress.get(quest.getId());
@@ -405,6 +459,13 @@ public class QuestProgressFile {
         return null;
     }
 
+    /**
+     * Generate a new blank {@link QuestProgress} for a specified {@code questid}.
+     * Has no effect if there is already an existing {@link QuestProgress} for {@code questid}.
+     *
+     * @param questid the quest to generate progress for
+     * @return true if successful
+     */
     public boolean generateBlankQuestProgress(String questid) {
         if (plugin.getQuestManager().getQuestById(questid) != null) {
             Quest quest = plugin.getQuestManager().getQuestById(questid);
@@ -424,6 +485,11 @@ public class QuestProgressFile {
         return playerPreferences;
     }
 
+    /**
+     * Save the quest progress file to disk at /playerdata/[uuid]. Must be invoked from the main thread.
+     *
+     * @param async save the file asynchronously
+     */
     public void saveToDisk(boolean async) {
         plugin.getQuestsLogger().debug("Saving player " + playerUUID + " to disk. Main thread: " + async);
         List<QuestProgress> questProgressValues = new ArrayList<>(questProgress.values());
@@ -477,7 +543,7 @@ public class QuestProgressFile {
     }
 
     /**
-     * Removes any references to quests or tasks which are no longer defined in the config
+     * Removes any references to quests or tasks which are no longer defined in the config.
      */
     public void clean() {
         plugin.getQuestsLogger().debug("Cleaning file " + playerUUID + ".");
diff --git a/src/main/resources/config.yml b/src/main/resources/config.yml
index b195d416..ef7532b9 100644
--- a/src/main/resources/config.yml
+++ b/src/main/resources/config.yml
@@ -114,7 +114,7 @@ gui:
   no-started-quests:
     name: "&c&lNo Started Quests"
     lore:
-    - "&7You have not started any quests."
+    - "&7Go start some!"
     type: "FEATHER"
   quest-cancel-yes:
     name: "&a&lConfirm Cancel"