Fix Javadocs to pass Maven release standards

Author: Jesse Peirce

server/src/main/java/keywhiz/auth/UserAuthenticatorFactory.java

@@ -28,6 +28,8 @@
 public interface UserAuthenticatorFactory extends Discoverable {
   /**
    * Builds an authenticator from username/password credentials to a {@link User}.
+   * @param dslContext context for the credential storage
+   * @return an authenticator from credentials to a user
    */
   Authenticator<BasicCredentials, User> build(DSLContext dslContext);
 }

server/src/main/java/keywhiz/auth/bcrypt/BcryptAuthenticator.java

@@ -56,12 +56,21 @@ public BcryptAuthenticator(UserDAO userDAO) {
     return Optional.ofNullable(user);
   }
 
-  /** Hash a password in a way compatible with this authenticator */
+  /**
+   * Hash a password in a way compatible with this authenticator
+   * @param password a password to be checked
+   * @return the hash of this password
+   */
   public static String hashPassword(String password) {
     return BCrypt.hashpw(password, BCrypt.gensalt());
   }
 
-  /** Constant-time password check */
+  /**
+   * Constant-time password check
+   * @param password a password to be checked
+   * @param hash a hash which may match the output of hashPassword for this password
+   * @return whether the password matches the hash
+   */
   private static boolean checkPassword(String password, Optional<String> hash) {
     // We want to check the password in constant time, to avoid leaking information about whether
     // a user is present in the database. In order to do this we pass a fake bcrypt hash into the

server/src/main/java/keywhiz/auth/mutualssl/CertificatePrincipal.java

@@ -44,7 +44,7 @@ public Instant getCertificateExpiration() {
   }
 
   /**
-   * @return string which should be a valid {@link sun.security.x509.X500Name}.
+   * @return string which should be a valid sun.security.x509.X500Name.
    */
   @Override
   public String getName() {

server/src/main/java/keywhiz/service/config/KeyStoreConfig.java

@@ -53,6 +53,7 @@ public abstract class KeyStoreConfig {
    * If the path does not exist on the filesystem, it is resolved as a resource.
    *
    * @return InputStream to the keystore at the resolved path
+   * @throws IOException if the path cannot be opened
    */
   public InputStream openPath() throws IOException {
     Path filePath = Paths.get(path());

server/src/main/java/keywhiz/service/crypto/RowHmacGenerator.java

@@ -40,6 +40,8 @@ public String computeRowHmac(String table, List<Object> fields) {
    * The random long generated with random.nextLong only uses 48 bits of randomness,
    * meaning it will not return all possible long values. Instead we generate a long from 8
    * random bytes.
+   *
+   * @return a randomly generated long
    */
   public long getNextLongSecure() {
     byte[] generateIdBytes = new byte[8];

server/src/main/java/keywhiz/service/crypto/SecretTransformer.java

@@ -36,6 +36,8 @@ public class SecretTransformer {
 
   /**
    * Transform DB content to a Secret model.
+   * @param seriesAndContent a secret series and secret contents as stored in the database
+   * @return the same information restructured as a Secret
    */
   public Secret transform(SecretSeriesAndContent seriesAndContent) {
     checkNotNull(seriesAndContent);

server/src/main/java/keywhiz/service/daos/AclDAO.java

@@ -515,6 +515,7 @@ protected ImmutableSet<SecretSeries> getSecretSeriesFor(Configuration configurat
   }
 
   /**
+   * @param configuration database information
    * @param client client to access secrets
    * @param secretName name of SecretSeries
    * @return Optional.absent() when secret unauthorized or not found.

server/src/main/java/keywhiz/service/daos/DAOFactory.java

@@ -27,18 +27,19 @@
  */
 public interface DAOFactory<T> {
   /**
-   * Returns DAO using a read/write database connection.
+   * @return DAO using a read/write database connection.
    */
   T readwrite();
 
   /**
-   * Returns DAO using a read-only database connection.
+   * @return DAO using a read-only database connection.
    */
   T readonly();
 
   /**
-   * Returns DAO using a supplied jOOQ configuration. Useful for issuing queries on the same
-   * underlying transaction from a different DAO.
+   * Useful for issuing queries on the same underlying transaction from a different DAO.
+   * @param configuration a jOOQ configuration
+   * @return DAO using the supplied jOOQ configuration.
    */
   T using(Configuration configuration);
 }

server/src/main/java/keywhiz/service/daos/SecretContentDAO.java

@@ -109,6 +109,8 @@ public long createSecretContent(long secretId, String encryptedContent, String h
    * Prune old secret contents from the database, for the given secret id. Whenever a new secret
    * content entry is added for a secret series, we check the database for really old content
    * entries and clean them out to prevent the database from growing too large.
+   *
+   * @param secretId the ID whose old secret contents should be removed
    */
   @VisibleForTesting void pruneOldContents(long secretId) {
     // Fetch current version number
@@ -191,7 +193,7 @@ public Optional<ImmutableList<SecretContent>> getSecretVersionsBySecretId(long i
    *
    * @param ids IDs in the `secrets` table; `secrets_contents` records linked to these by
    * `secrets_content.secretid` will be PERMANENTLY REMOVED
-   * @returns the number of records which were removed
+   * @return the number of records which were removed
    */
   public long dangerPermanentlyRemoveRecordsForGivenSecretsIDs(List<Long> ids) {
     return dslContext.deleteFrom(SECRETS_CONTENT)

server/src/main/java/keywhiz/service/daos/SecretDAO.java

@@ -283,7 +283,16 @@ public Optional<SecretSeriesAndContent> getSecretByName(String name) {
     return Optional.empty();
   }
 
-  /** @return list of secrets. can limit/sort by expiry, and for group if given */
+  /**
+   * @param expireMaxTime the maximum expiration date for secrets to return (exclusive)
+   * @param group the group secrets returned must be assigned to
+   * @param expireMinTime the minimum expiration date for secrets to return (inclusive)
+   * @param minName the minimum name (alphabetically) that will be returned for secrets
+   *                expiring on expireMinTime (inclusive)
+   * @param limit the maximum number of secrets to return
+   *               which to start the list of returned secrets
+   * @return list of secrets. can limit/sort by expiry, and for group if given
+   */
   public ImmutableList<SecretSeriesAndContent> getSecrets(@Nullable Long expireMaxTime,
       @Nullable Group group, @Nullable Long expireMinTime, @Nullable String minName,
       @Nullable Integer limit) {
@@ -380,6 +389,7 @@ public Optional<ImmutableList<SanitizedSecret>> getSecretVersionsByName(String n
   /**
    * @param name of secret series for which to reset secret version
    * @param versionId The identifier for the desired current version
+   * @param updater the user to be linked to this update
    * @throws NotFoundException if secret not found
    */
   public void setCurrentSecretVersionByName(String name, long versionId, String updater) {
@@ -405,17 +415,16 @@ public void deleteSecretsByName(String name) {
   }
 
   /**
-   * Counts the total number of deleted secrets.
+   * @return the total number of deleted secrets.
    */
   public int countDeletedSecrets() {
     return secretSeriesDAOFactory.using(dslContext.configuration())
         .countDeletedSecretSeries();
   }
 
   /**
-   * Counts the number of secrets deleted before the specified cutoff.
-   *
    * @param deleteBefore the cutoff date; secrets deleted before this date will be counted
+   * @return the number of secrets deleted before the specified cutoff.
    */
   public int countSecretsDeletedBeforeDate(DateTime deleteBefore) {
     checkArgument(deleteBefore != null);
@@ -436,6 +445,7 @@ public int countSecretsDeletedBeforeDate(DateTime deleteBefore) {
    * @param deletedBefore the cutoff date; secrets deleted before this date will be removed from the
    * database
    * @param sleepMillis how many milliseconds to sleep between each batch of removals
+   * @throws InterruptedException if interrupted while sleeping between batches
    */
   public void dangerPermanentlyRemoveSecretsDeletedBeforeDate(DateTime deletedBefore,
       int sleepMillis) throws InterruptedException {