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
This commit is contained in:
ljacqu 2015-12-31 13:32:41 +01:00
parent 5573e7449d
commit a0da423a7b
11 changed files with 67 additions and 34 deletions

View File

@ -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;

View File

@ -49,9 +49,10 @@ public class CommandHandler {
}
/**
* Execute the command for the given command sender.
*
* @param sender
* @param result
* @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();

View File

@ -54,10 +54,11 @@ public class CommandService {
}
/**
* Send a message to a player.
*
* @param sender CommandSender
* @param messageKey MessageKey
* @param replacements String...
* @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 the permissions manager.
*
* @return PermissionManager the PermissionManager
* @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 {
}
/**
* Retrieve a message by its message key.
*
* @param key MessageKey
* @return StringArray Array of String
* @param key The message to retrieve
* @return The message
*/
public String[] retrieveMessage(MessageKey key) {
return messages.retrieve(key);

View File

@ -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,

View File

@ -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
*/

View File

@ -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)

View File

@ -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;

View File

@ -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();

View File

@ -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. */

View File

@ -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 {

View File

@ -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}");
}