Fix javadoc warnings + #421 add javadoc for new API

src/main/java/fr/xephi/authme/AuthMe.java

@@ -548,6 +548,8 @@ public class AuthMe extends JavaPlugin {
      * @param settings The settings instance
      *
      * @see AuthMe#database
+     * @throws ClassNotFoundException if no driver could be found for the datasource
+     * @throws SQLException when initialization of a SQL datasource failed
      */
     public void setupDatabase(NewSetting settings) throws ClassNotFoundException, SQLException {
         if (this.database != null) {

src/main/java/fr/xephi/authme/api/NewAPI.java

@@ -13,7 +13,10 @@ import fr.xephi.authme.security.crypts.HashedPassword;
 import fr.xephi.authme.util.Utils;
 
 /**
- * The current API of AuthMe.
+ * The current API of AuthMe. Recommended method of retrieving the API object:
+ * <code>
+ * NewAPI authmeApi = NewAPI.getInstance();
+ * </code>
  */
 public class NewAPI {
 
@@ -23,7 +26,7 @@ public class NewAPI {
     /**
      * Constructor for NewAPI.
      *
-     * @param plugin AuthMe
+     * @param plugin The AuthMe plugin instance
      */
     public NewAPI(AuthMe plugin) {
         this.plugin = plugin;
@@ -32,16 +35,17 @@ public class NewAPI {
     /**
      * Constructor for NewAPI.
      *
-     * @param server Server
+     * @param server The server instance
      */
     public NewAPI(Server server) {
         this.plugin = (AuthMe) server.getPluginManager().getPlugin("AuthMe");
     }
 
     /**
-     * Hook into AuthMe
+     * Get the API object for AuthMe.
      *
-     * @return The API object
+     * @return The API object, or null if the AuthMe plugin instance could not be retrieved
+     * from the server environment
      */
     public static NewAPI getInstance() {
         if (singleton != null) {
@@ -69,7 +73,6 @@ public class NewAPI {
      * Return whether the given player is authenticated.
      *
      * @param player The player to verify
-     *
      * @return true if the player is authenticated
      */
     public boolean isAuthenticated(Player player) {
@@ -77,18 +80,22 @@ public class NewAPI {
     }
 
     /**
-     * @param player a Player
+     * Check whether the given player is an NPC.
      *
-     * @return true if player is a npc
+     * @param player The player to verify
+     * @return true if the player is an npc
      */
     public boolean isNPC(Player player) {
         return Utils.isNPC(player);
     }
 
     /**
-     * @param player a Player
+     * Check whether the given player is unrestricted. For such players, AuthMe will not require
+     * them to authenticate.
      *
+     * @param player The player to verify
      * @return true if the player is unrestricted
+     * @see fr.xephi.authme.settings.properties.RestrictionSettings#UNRESTRICTED_NAMES
      */
     public boolean isUnrestricted(Player player) {
         return Utils.isUnrestricted(player);
@@ -97,30 +104,21 @@ public class NewAPI {
     /**
      * Get the last location of a player.
      *
-     * @param player Player The player to process
-     *
+     * @param player The player to process
      * @return Location The location of the player
      */
     public Location getLastLocation(Player player) {
-        try {
         PlayerAuth auth = PlayerCache.getInstance().getAuth(player.getName());
-
         if (auth != null) {
             return new Location(Bukkit.getWorld(auth.getWorld()), auth.getQuitLocX(), auth.getQuitLocY(), auth.getQuitLocZ());
-            } else {
-                return null;
         }
-
-        } catch (NullPointerException ex) {
         return null;
     }
-    }
 
     /**
      * Return whether the player is registered.
      *
      * @param playerName The player name to check
-     *
      * @return true if player is registered, false otherwise
      */
     public boolean isRegistered(String playerName) {
@@ -133,7 +131,6 @@ public class NewAPI {
      *
      * @param playerName      The player to check the password for
      * @param passwordToCheck The password to check
-     *
      * @return true if the password is correct, false otherwise
      */
     public boolean checkPassword(String playerName, String passwordToCheck) {
@@ -141,11 +138,10 @@ public class NewAPI {
     }
 
     /**
-     * Register a player.
+     * Register a player with the given password.
      *
      * @param playerName The player to register
      * @param password   The password to register the player with
-     *
      * @return true if the player was registered successfully
      */
     public boolean registerPlayer(String playerName, String password) {
@@ -163,7 +159,7 @@ public class NewAPI {
     }
 
     /**
-     * Force a player to login.
+     * Force a player to login, i.e. the player is logged in without needing his password.
      *
      * @param player The player to log in
      */
@@ -181,7 +177,7 @@ public class NewAPI {
     }
 
     /**
-     * Force a player to register.
+     * Register a player with the given password.
      *
      * @param player   The player to register
      * @param password The password to use
@@ -191,7 +187,7 @@ public class NewAPI {
     }
 
     /**
-     * Force a player to unregister.
+     * Unregister a player from AuthMe.
      *
      * @param player The player to unregister
      */

src/main/java/fr/xephi/authme/datasource/SQLite.java

@@ -30,8 +30,9 @@ public class SQLite implements DataSource {
     /**
      * Constructor for SQLite.
      *
-     * @throws ClassNotFoundException Exception
-     * @throws SQLException           Exception
+     * @param settings The settings instance
+     * @throws ClassNotFoundException if no driver could be found for the datasource
+     * @throws SQLException when initialization of a SQL datasource failed
      */
     public SQLite(NewSetting settings) throws ClassNotFoundException, SQLException {
         this.database = settings.getProperty(DatabaseSettings.MYSQL_DATABASE);

src/main/java/fr/xephi/authme/events/AuthMeAsyncPreLoginEvent.java

@@ -6,7 +6,7 @@ import org.bukkit.event.HandlerList;
 
 /**
  * This event is called when a player uses the /login command with correct credentials.
- * {@link #setCanLogin(boolean) {@code event.setCanLogin(false)}} prevents the player from logging in.
+ * {@link #setCanLogin(boolean) <code>event.setCanLogin(false)</code>} prevents the player from logging in.
  */
 public class AuthMeAsyncPreLoginEvent extends CustomEvent {
 

src/main/java/fr/xephi/authme/output/Messages.java

@@ -96,6 +96,7 @@ public class Messages {
      *
      * @param key The key of the message to send
      * @param replacements The replacements to apply for the tags
+     * @return The message from the file with replacements
      */
     public String retrieveSingle(MessageKey key, String... replacements) {
         String message = retrieveSingle(key);
@@ -111,7 +112,7 @@ public class Messages {
     }
 
     /**
-     * Reload the messages manager.
+     * Reset the messages manager to retrieve messages from the given file instead of the current one.
      *
      * @param messagesFile The new file to load messages from
      */