From a0da423a7b8a45a5ca10912cdc568dcdfc1766a3 Mon Sep 17 00:00:00 2001
From: ljacqu <ljacqu@users.noreply.github.com>
Date: Thu, 31 Dec 2015 13:32:41 +0100
Subject: [PATCH] Minor - Javadoc changes - Add/replace/improve javadoc in the
 commands and encryption section - Note: A simple <p> is the javadoc way to
 make a new paragraph
 http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#format
 - Note: Do not escape '<' and '>' inside of {@code } - Note: '>' does not
 need to be escaped

---
 .../authme/command/CommandDescription.java    | 16 +++++++------
 .../xephi/authme/command/CommandHandler.java  |  7 +++---
 .../xephi/authme/command/CommandService.java  | 23 +++++++++++--------
 .../authme/command/FoundCommandResult.java    |  3 +--
 .../xephi/authme/command/PlayerCommand.java   |  2 +-
 .../crypts/description/AsciiRestricted.java   |  2 +-
 .../security/crypts/description/HasSalt.java  | 12 ++++++----
 .../crypts/description/Recommendation.java    | 10 +++++---
 .../security/crypts/description/SaltType.java |  2 +-
 .../security/crypts/description/Usage.java    |  6 +++++
 .../crypts/AbstractEncryptionMethodTest.java  | 18 +++++++++++++--
 11 files changed, 67 insertions(+), 34 deletions(-)

diff --git a/src/main/java/fr/xephi/authme/command/CommandDescription.java b/src/main/java/fr/xephi/authme/command/CommandDescription.java
index d398af67..22a3f05c 100644
--- a/src/main/java/fr/xephi/authme/command/CommandDescription.java
+++ b/src/main/java/fr/xephi/authme/command/CommandDescription.java
@@ -12,12 +12,13 @@ import static com.google.common.base.Preconditions.checkArgument;
 import static java.util.Arrays.asList;
 
 /**
- * Command description - defines which labels ("names") will lead to a command and points to the
+ * Command description – defines which labels ("names") will lead to a command and points to the
  * {@link ExecutableCommand} implementation that executes the logic of the command.
  *
- * CommandDescription instances are built hierarchically and have one parent or {@code null} for base commands
- * (main commands such as /authme) and may have multiple children extending the mapping of the parent: e.g. if
- * /authme has a child whose label is "register", then "/authme register" is the command that the child defines.
+ * CommandDescription instances are built hierarchically: they have one parent, or {@code null} for base commands
+ * (main commands such as {@code /authme}), and may have multiple children extending the mapping of the parent: e.g. if
+ * {@code /authme} has a child whose label is {@code "register"}, then {@code /authme register} is the command that
+ * the child defines.
  */
 public class CommandDescription {
 
@@ -102,10 +103,11 @@ public class CommandDescription {
     }
 
     /**
-     * Get all relative labels of this command. For example, if this object describes "/authme register" and
-     * "/authme r", then "r" and "register" are the relative labels, whereas "authme" is the label of the parent.
+     * Return all relative labels of this command. For example, if this object describes {@code /authme register} and
+     * {@code /authme r}, then it will return a list with {@code register} and {@code r}. The parent label
+     * {@code authme} is not returned.
      *
-     * @return All relative labels.
+     * @return All labels of the command description.
      */
     public List<String> getLabels() {
         return labels;
diff --git a/src/main/java/fr/xephi/authme/command/CommandHandler.java b/src/main/java/fr/xephi/authme/command/CommandHandler.java
index 3d6d3d24..e3ab671b 100644
--- a/src/main/java/fr/xephi/authme/command/CommandHandler.java
+++ b/src/main/java/fr/xephi/authme/command/CommandHandler.java
@@ -49,9 +49,10 @@ public class CommandHandler {
     }
 
     /**
-     * 
-     * @param sender
-     * @param result
+     * Execute the command for the given command sender.
+     *
+     * @param sender The sender which initiated the command
+     * @param result The mapped result
      */
     private void executeCommand(CommandSender sender, FoundCommandResult result) {
         ExecutableCommand executableCommand = result.getCommandDescription().getExecutableCommand();
diff --git a/src/main/java/fr/xephi/authme/command/CommandService.java b/src/main/java/fr/xephi/authme/command/CommandService.java
index f8b7f852..08a2790e 100644
--- a/src/main/java/fr/xephi/authme/command/CommandService.java
+++ b/src/main/java/fr/xephi/authme/command/CommandService.java
@@ -54,10 +54,11 @@ public class CommandService {
     }
 
     /**
-     * 
-     * @param sender CommandSender
-     * @param messageKey MessageKey
-     * @param replacements String...
+     * Send a message to a player.
+     *
+     * @param sender The command sender to send the message to
+     * @param messageKey The message key to send
+     * @param replacements The replacement arguments for the message key's tags
      */
     public void send(CommandSender sender, MessageKey messageKey, String... replacements) {
         messages.send(sender, messageKey, replacements);
@@ -127,7 +128,7 @@ public class CommandService {
     }
 
     /**
-     * Returns the management instance of the plugin.
+     * Return the management instance of the plugin.
      *
      * @return The Management instance linked to the AuthMe instance
      */
@@ -136,8 +137,9 @@ public class CommandService {
     }
 
     /**
-     * 
-     * @return PermissionManager the PermissionManager
+     * Return the permissions manager.
+     *
+     * @return the permissions manager
      */
     public PermissionsManager getPermissionsManager() {
         // TODO ljacqu 20151226: Might be nicer to pass the perm manager via constructor
@@ -145,9 +147,10 @@ public class CommandService {
     }
 
     /**
-     * 
-     * @param key MessageKey
-     * @return StringArray Array of String
+     * Retrieve a message by its message key.
+     *
+     * @param key The message to retrieve
+     * @return The message
      */
     public String[] retrieveMessage(MessageKey key) {
         return messages.retrieve(key);
diff --git a/src/main/java/fr/xephi/authme/command/FoundCommandResult.java b/src/main/java/fr/xephi/authme/command/FoundCommandResult.java
index 7f19a4f0..520eec24 100644
--- a/src/main/java/fr/xephi/authme/command/FoundCommandResult.java
+++ b/src/main/java/fr/xephi/authme/command/FoundCommandResult.java
@@ -3,10 +3,9 @@ package fr.xephi.authme.command;
 import java.util.List;
 
 /**
- * <p>
  * Result of a command mapping by {@link CommandHandler}. An object of this class represents a successful mapping
  * as well as erroneous ones, as communicated with {@link FoundResultStatus}.
- * </p>
+ * <p>
  * Fields other than {@link FoundResultStatus} are available depending, among other factors, on the status:
  * <ul>
  *   <li>{@link FoundResultStatus#SUCCESS} entails that mapping the input to a command was successful. Therefore,
diff --git a/src/main/java/fr/xephi/authme/command/PlayerCommand.java b/src/main/java/fr/xephi/authme/command/PlayerCommand.java
index 5792dd97..2d7aca0b 100644
--- a/src/main/java/fr/xephi/authme/command/PlayerCommand.java
+++ b/src/main/java/fr/xephi/authme/command/PlayerCommand.java
@@ -35,7 +35,7 @@ public abstract class PlayerCommand implements ExecutableCommand {
 
     /**
      * Return an alternative command (textual representation) that is not restricted to players only.
-     * Example: "authme register &lt;playerName&gt; &lt;password&gt;"
+     * Example: {@code "authme register <playerName> <password>"}
      *
      * @return Alternative command not only for players, or null if not applicable
      */
diff --git a/src/main/java/fr/xephi/authme/security/crypts/description/AsciiRestricted.java b/src/main/java/fr/xephi/authme/security/crypts/description/AsciiRestricted.java
index f515717e..bf179fff 100644
--- a/src/main/java/fr/xephi/authme/security/crypts/description/AsciiRestricted.java
+++ b/src/main/java/fr/xephi/authme/security/crypts/description/AsciiRestricted.java
@@ -6,7 +6,7 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Denotes an encryption algorithm that is restricted to the ASCII charset.
+ * Denotes a hashing algorithm that is restricted to the ASCII charset.
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/src/main/java/fr/xephi/authme/security/crypts/description/HasSalt.java b/src/main/java/fr/xephi/authme/security/crypts/description/HasSalt.java
index 85ad0608..0723a4dd 100644
--- a/src/main/java/fr/xephi/authme/security/crypts/description/HasSalt.java
+++ b/src/main/java/fr/xephi/authme/security/crypts/description/HasSalt.java
@@ -13,13 +13,17 @@ import java.lang.annotation.Target;
 @Retention(RetentionPolicy.RUNTIME)
 public @interface HasSalt {
 
-    /** The type of the salt.
-     * @return salttype The SaltType
+    /**
+     * The type of the salt.
+     *
+     * @return The salt type
      */
     SaltType value();
 
-    /** For text salts, the length of the salt.
-     * @return int Integer
+    /**
+     * For text salts, the length of the salt.
+     *
+     * @return The length of the salt the algorithm uses, or 0 if not defined or not applicable.
      */
     int length() default 0;
 
diff --git a/src/main/java/fr/xephi/authme/security/crypts/description/Recommendation.java b/src/main/java/fr/xephi/authme/security/crypts/description/Recommendation.java
index e57a0c40..4b832a68 100644
--- a/src/main/java/fr/xephi/authme/security/crypts/description/Recommendation.java
+++ b/src/main/java/fr/xephi/authme/security/crypts/description/Recommendation.java
@@ -6,14 +6,18 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Annotation to mark a hash algorithm with the usage recommendation, see {@link Usage}.
+ * Annotation to mark a hash algorithm with the usage recommendation.
+ *
+ * @see Usage
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Recommendation {
 
-    /** The recommendation for using the hash algorithm.
-     * @return Usage The Usage
+    /**
+     * The recommendation for using the hash algorithm.
+     *
+     * @return The recommended usage
      */
     Usage value();
 
diff --git a/src/main/java/fr/xephi/authme/security/crypts/description/SaltType.java b/src/main/java/fr/xephi/authme/security/crypts/description/SaltType.java
index 7d6b225c..40b923fa 100644
--- a/src/main/java/fr/xephi/authme/security/crypts/description/SaltType.java
+++ b/src/main/java/fr/xephi/authme/security/crypts/description/SaltType.java
@@ -8,7 +8,7 @@ public enum SaltType {
     /** Random, newly generated text. */
     TEXT,
 
-    /** Salt is based on the username, including variations and repetitions. */
+    /** Salt is based on the username, including variations and repetitions thereof. */
     USERNAME,
 
     /** No salt. */
diff --git a/src/main/java/fr/xephi/authme/security/crypts/description/Usage.java b/src/main/java/fr/xephi/authme/security/crypts/description/Usage.java
index ecf37a98..c11c335a 100644
--- a/src/main/java/fr/xephi/authme/security/crypts/description/Usage.java
+++ b/src/main/java/fr/xephi/authme/security/crypts/description/Usage.java
@@ -2,6 +2,12 @@ package fr.xephi.authme.security.crypts.description;
 
 /**
  * Usage recommendation that can be provided for a hash algorithm.
+ * <p>
+ * Use the following rules of thumb:
+ * <ul>
+ *     <li>Hashes using MD5 may be {@link #ACCEPTABLE} but never {@link #RECOMMENDED}.</li>
+ *     <li>Hashes using no salt or one based on the username should be {@link #DO_NOT_USE}.</li>
+ * </ul>
  */
 public enum Usage {
 
diff --git a/src/test/java/fr/xephi/authme/security/crypts/AbstractEncryptionMethodTest.java b/src/test/java/fr/xephi/authme/security/crypts/AbstractEncryptionMethodTest.java
index 9acc3c25..ef78c5fd 100644
--- a/src/test/java/fr/xephi/authme/security/crypts/AbstractEncryptionMethodTest.java
+++ b/src/test/java/fr/xephi/authme/security/crypts/AbstractEncryptionMethodTest.java
@@ -142,30 +142,44 @@ public abstract class AbstractEncryptionMethodTest {
         return method.comparePassword(password, hashes.get(password), USERNAME);
     }
 
-    // @org.junit.Test public void a() { AbstractEncryptionMethodTest.generateTest(); }
-    // TODO #364: Remove this method
+    /**
+     * Generates a test class for a given encryption method. Simply create a test class and run the following code,
+     * replacing {@code XXX} with the actual class:
+     * <p>
+     * <code>@org.junit.Test public void generate() { AbstractEncryptionMethodTest.generateTest(new XXX()); }</code>
+     * <p>
+     * The output is the entire test class.
+     *
+     * @param method The method to create a test class for
+     */
     static void generateTest(EncryptionMethod method) {
         String className = method.getClass().getSimpleName();
+        // Create javadoc and "public class extends" and the constructor call "super(new Class(),"
         System.out.println("/**\n * Test for {@link " + className + "}.\n */");
         System.out.println("public class " + className + "Test extends AbstractEncryptionMethodTest {");
         System.out.println("\n\tpublic " + className + "Test() {");
         System.out.println("\t\tsuper(new " + className + "(),");
 
+        // Iterate through the GIVEN_PASSWORDS and generate a hash so we can always check it later
         String delim = ",  ";
         for (String password : GIVEN_PASSWORDS) {
             if (password.equals(GIVEN_PASSWORDS[GIVEN_PASSWORDS.length - 1])) {
                 delim = "); ";
             }
 
+            // Encr. method uses separate salt, so we need to call the constructor that takes HashedPassword instances
             if (method.hasSeparateSalt()) {
                 HashedPassword hashedPassword = method.computeHash(password, USERNAME);
                 System.out.println(String.format("\t\tnew HashedPassword(\"%s\", \"%s\")%s// %s",
                     hashedPassword.getHash(), hashedPassword.getSalt(), delim, password));
             } else {
+                // Encryption method doesn't have separate salt, so simply pass the generated hash to the constructor
                 System.out.println("\t\t\"" + method.computeHash(password, USERNAME).getHash()
                     + "\"" + delim + "// " + password);
             }
         }
+
+        // Close the constructor and class declarations
         System.out.println("\t}");
         System.out.println("\n}");
     }