8253053: Javadoc clean up in Authenticator and BasicAuthenicator

Reviewed-by: dfuchs, rriggs, chegar, michaelm

Author: pconcannon

src/jdk.httpserver/share/classes/com/sun/net/httpserver/Authenticator.java

@@ -41,7 +41,7 @@ public abstract class Authenticator {
     protected Authenticator () { }
 
     /**
-     * Base class for return type from authenticate() method
+     * Base class for return type from {@link #authenticate(HttpExchange)} method.
      */
     public abstract static class Result {
 
@@ -51,8 +51,6 @@ public abstract static class Result {
         protected Result () {}
     }
 
-
-
     /**
      * Indicates an authentication failure. The authentication
      * attempt has completed.
@@ -64,17 +62,17 @@ public static class Failure extends Result {
         /**
          * Creates a {@code Failure} instance with given response code.
          *
-         * @param responseCode The response code to associate with this
+         * @param responseCode the response code to associate with this
          *                     {@code Failure} instance
          */
         public Failure (int responseCode) {
             this.responseCode = responseCode;
         }
 
         /**
-         * returns the response code to send to the client
+         * Returns the response code to send to the client.
          *
-         * @return The response code associated with this {@code Failure} instance
+         * @return the response code associated with this {@code Failure} instance
          */
         public int getResponseCode() {
             return responseCode;
@@ -83,24 +81,25 @@ public int getResponseCode() {
 
     /**
      * Indicates an authentication has succeeded and the
-     * authenticated user principal can be acquired by calling
-     * getPrincipal().
+     * authenticated user {@linkplain HttpPrincipal principal} can be acquired by calling
+     * {@link #getPrincipal()}.
      */
     public static class Success extends Result {
         private HttpPrincipal principal;
 
         /**
          * Creates a {@code Success} instance with given {@code Principal}.
          *
-         * @param p The authenticated user you wish to set as Principal
+         * @param p the authenticated user you wish to set as {@code Principal}
          */
         public Success (HttpPrincipal p) {
             principal = p;
         }
+
         /**
-         * returns the authenticated user Principal
+         * Returns the authenticated user {@code Principal}.
          *
-         * @return The {@code Principal} instance associated with the authenticated user
+         * @return the {@code Principal} instance associated with the authenticated user
          *
          */
         public HttpPrincipal getPrincipal() {
@@ -111,9 +110,9 @@ public HttpPrincipal getPrincipal() {
     /**
      * Indicates an authentication must be retried. The
      * response code to be sent back is as returned from
-     * getResponseCode(). The Authenticator must also have
-     * set any necessary response headers in the given HttpExchange
-     * before returning this Retry object.
+     * {@link #getResponseCode()}. The {@code Authenticator} must also have
+     * set any necessary response headers in the given {@link HttpExchange}
+     * before returning this {@code Retry} object.
      */
     public static class Retry extends Result {
 
@@ -122,41 +121,40 @@ public static class Retry extends Result {
         /**
          * Creates a {@code Retry} instance with given response code.
          *
-         * @param responseCode The response code to associate with this
+         * @param responseCode the response code to associate with this
          *                     {@code Retry} instance
          */
         public Retry (int responseCode) {
             this.responseCode = responseCode;
         }
 
         /**
-         * returns the response code to send to the client
+         * Returns the response code to send to the client.
          *
-         * @return The response code associated with this {@code Retry} instance
+         * @return the response code associated with this {@code Retry} instance
          */
         public int getResponseCode() {
             return responseCode;
         }
     }
 
     /**
-     * called to authenticate each incoming request. The implementation
-     * must return a Failure, Success or Retry object as appropriate :-
-     * <p>
-     * Failure means the authentication has completed, but has failed
-     * due to invalid credentials.
-     * <p>
-     * Sucess means that the authentication
-     * has succeeded, and a Principal object representing the user
-     * can be retrieved by calling Sucess.getPrincipal() .
-     * <p>
-     * Retry means that another HTTP exchange is required. Any response
-     * headers needing to be sent back to the client are set in the
-     * given HttpExchange. The response code to be returned must be provided
-     * in the Retry object. Retry may occur multiple times.
+     * Called to authenticate each incoming request. The implementation
+     * must return a {@link Failure}, {@link Success} or {@link Retry} object as appropriate:
+     * <ul>
+     *     <li> {@code Failure} means the authentication has completed, but has
+     *     failed due to invalid credentials.
+     *     <li> {@code Success} means that the authentication has succeeded,
+     *     and a {@code Principal} object representing the user can be retrieved
+     *     by calling {@link Success#getPrincipal()}.
+     *     <li> {@code Retry} means that another HTTP {@linkplain HttpExchange exchange}
+     *     is required. Any response headers needing to be sent back to the client are set
+     *     in the given {@code HttpExchange}. The response code to be returned must be
+     *     provided in the {@code Retry} object. {@code Retry} may occur multiple times.
+     * <ul/>
      *
-     * @param exch The HttpExchange upon which authenticate is called
-     * @return The result
+     * @param exch the {@code HttpExchange} upon which authenticate is called
+     * @return the result
      */
     public abstract Result authenticate (HttpExchange exch);
 }

src/jdk.httpserver/share/classes/com/sun/net/httpserver/BasicAuthenticator.java

@@ -45,11 +45,11 @@ public abstract class BasicAuthenticator extends Authenticator {
     private final boolean isUTF8;
 
     /**
-     * Creates a BasicAuthenticator for the given HTTP realm.
+     * Creates a {@code BasicAuthenticator} for the given HTTP realm.
      * The Basic authentication credentials (username and password) are decoded
      * using the platform's {@link Charset#defaultCharset() default character set}.
      *
-     * @param realm The HTTP Basic authentication realm
+     * @param realm the HTTP Basic authentication realm
      * @throws NullPointerException if realm is {@code null}
      * @throws IllegalArgumentException if realm is an empty string
      */
@@ -58,16 +58,16 @@ public BasicAuthenticator (String realm) {
     }
 
     /**
-     * Creates a BasicAuthenticator for the given HTTP realm and using the
+     * Creates a {@code BasicAuthenticator} for the given HTTP realm and using the
      * given {@link Charset} to decode the Basic authentication credentials
      * (username and password).
      *
      * @apiNote {@code UTF-8} is the recommended charset because its usage is
      * communicated to the client, and therefore more likely to be used also
      * by the client.
      *
-     * @param realm The HTTP Basic authentication realm
-     * @param charset The Charset to decode incoming credentials from the client
+     * @param realm the HTTP Basic authentication realm
+     * @param charset the {@code Charset} to decode incoming credentials from the client
      * @throws NullPointerException if realm or charset are {@code null}
      * @throws IllegalArgumentException if realm is an empty string
      */
@@ -81,8 +81,9 @@ public BasicAuthenticator (String realm, Charset charset) {
     }
 
     /**
-     * returns the realm this BasicAuthenticator was created with
-     * @return the authenticator's realm string.
+     * Returns the realm this {@code BasicAuthenticator} was created with.
+     *
+     * @return the authenticator's realm string
      */
     public String getRealm () {
         return realm;
@@ -130,14 +131,14 @@ private void setAuthHeader(HttpExchange t) {
     }
 
     /**
-     * called for each incoming request to verify the
+     * Called for each incoming request to verify the
      * given name and password in the context of this
-     * Authenticator's realm. Any caching of credentials
-     * must be done by the implementation of this method
+     * authenticator's realm. Any caching of credentials
+     * must be done by the implementation of this method.
+     *
      * @param username the username from the request
      * @param password the password from the request
-     * @return <code>true</code> if the credentials are valid,
-     *    <code>false</code> otherwise.
+     * @return {@code true} if the credentials are valid, {@code false} otherwise
      */
     public abstract boolean checkCredentials (String username, String password);
 }