Improve javadoc documentation for core API methods

jetty-core/jetty-client/src/main/java/org/eclipse/jetty/client/AbstractAuthentication.java

@@ -15,11 +15,21 @@
 
 import java.net.URI;
 
+/**
+ * <p>Abstract base class for authentication implementations.
+ * Provides common functionality for URI and realm matching.</p>
+ */
 public abstract class AbstractAuthentication implements Authentication
 {
     private final URI uri;
     private final String realm;
 
+    /**
+     * Creates an authentication for the given URI and realm.
+     *
+     * @param uri the URI this authentication applies to
+     * @param realm the authentication realm
+     */
     public AbstractAuthentication(URI uri, String realm)
     {
         this.uri = uri;
@@ -28,11 +38,17 @@ public AbstractAuthentication(URI uri, String realm)
 
     public abstract String getType();
 
+    /**
+     * @return the URI this authentication applies to
+     */
     public URI getURI()
     {
         return uri;
     }
 
+    /**
+     * @return the authentication realm
+     */
     public String getRealm()
     {
         return realm;

jetty-core/jetty-client/src/main/java/org/eclipse/jetty/client/DuplexConnectionPool.java

@@ -16,9 +16,19 @@
 import org.eclipse.jetty.util.ConcurrentPool;
 import org.eclipse.jetty.util.annotation.ManagedObject;
 
+/**
+ * <p>A connection pool that provides connections for both directions of communication.
+ * This pool uses a concurrent pool with FIRST strategy to manage connections efficiently.</p>
+ */
 @ManagedObject
 public class DuplexConnectionPool extends AbstractConnectionPool
 {
+    /**
+     * Creates a duplex connection pool for the given destination.
+     *
+     * @param destination the destination for which this pool provides connections
+     * @param maxConnections the maximum number of connections in the pool
+     */
     public DuplexConnectionPool(Destination destination, int maxConnections)
     {
         super(destination, () -> new ConcurrentPool<>(ConcurrentPool.StrategyType.FIRST, maxConnections), 1);

jetty-core/jetty-client/src/main/java/org/eclipse/jetty/client/Origin.java

@@ -94,26 +94,41 @@ public Origin(String scheme, Address address, Object tag, Protocol protocol, Tra
         this.transport = transport;
     }
 
+    /**
+     * @return the URI scheme (http, https, etc.)
+     */
     public String getScheme()
     {
         return scheme;
     }
 
+    /**
+     * @return the network address (host and port)
+     */
     public Address getAddress()
     {
         return address;
     }
 
+    /**
+     * @return the tag object that distinguishes destinations with the same scheme, host, port and protocol
+     */
     public Object getTag()
     {
         return tag;
     }
 
+    /**
+     * @return the network protocol, or null if not specified
+     */
     public Protocol getProtocol()
     {
         return protocol;
     }
 
+    /**
+     * @return the transport mechanism (TCP/IP, Unix domain socket, etc.)
+     */
     public Transport getTransport()
     {
         return transport;
@@ -140,6 +155,9 @@ public boolean equals(Object obj)
                Objects.equals(transport, that.transport);
     }
 
+    /**
+     * @return a string representation of this origin as a URI
+     */
     public String asString()
     {
         return HttpURI.from(scheme, address.host, address.port, null).asString();
@@ -171,11 +189,17 @@ public Address(String host, int port)
             this.address = InetSocketAddress.createUnresolved(getHost(), getPort());
         }
 
+        /**
+         * @return the host name or IP address
+         */
         public String getHost()
         {
             return host;
         }
 
+        /**
+         * @return the port number
+         */
         public int getPort()
         {
             return port;
@@ -198,11 +222,17 @@ public int hashCode()
             return Objects.hash(host, port);
         }
 
+        /**
+         * @return a string representation of this address as host:port
+         */
         public String asString()
         {
             return String.format("%s:%d", host, port);
         }
 
+        /**
+         * @return the socket address for this host and port
+         */
         public SocketAddress getSocketAddress()
         {
             return address;
@@ -241,11 +271,17 @@ public Protocol(List<String> protocols, boolean negotiate)
             this.negotiate = negotiate;
         }
 
+        /**
+         * @return the list of protocol names associated with this protocol
+         */
         public List<String> getProtocols()
         {
             return protocols;
         }
 
+        /**
+         * @return true if this protocol should be negotiated, false otherwise
+         */
         public boolean isNegotiate()
         {
             return negotiate;
@@ -268,6 +304,9 @@ public int hashCode()
             return Objects.hash(protocols, negotiate);
         }
 
+        /**
+         * @return a string representation of this protocol
+         */
         public String asString()
         {
             return String.format("proto=%s,nego=%b", protocols, negotiate);

jetty-core/jetty-security/src/main/java/org/eclipse/jetty/security/HashLoginService.java

@@ -40,21 +40,38 @@ public class HashLoginService extends AbstractLoginService
     private UserStore _userStore;
     private boolean _userStoreAutoCreate = false;
 
+    /**
+     * Creates a hash login service with no name or configuration.
+     */
     public HashLoginService()
     {
     }
 
+    /**
+     * Creates a hash login service with the specified name.
+     *
+     * @param name the name of this login service
+     */
     public HashLoginService(String name)
     {
         setName(name);
     }
 
+    /**
+     * Creates a hash login service with the specified name and configuration.
+     *
+     * @param name the name of this login service
+     * @param config the resource containing user configuration
+     */
     public HashLoginService(String name, Resource config)
     {
         setName(name);
         setConfig(config);
     }
 
+    /**
+     * @return the configuration resource containing user data
+     */
     public Resource getConfig()
     {
         return _config;

jetty-core/jetty-security/src/main/java/org/eclipse/jetty/security/ServerAuthException.java

@@ -21,20 +21,39 @@
 public class ServerAuthException extends GeneralSecurityException
 {
 
+    /**
+     * Creates a server authentication exception with no message.
+     */
     public ServerAuthException()
     {
     }
 
+    /**
+     * Creates a server authentication exception with the given message.
+     *
+     * @param s the exception message
+     */
     public ServerAuthException(String s)
     {
         super(s);
     }
 
+    /**
+     * Creates a server authentication exception with the given message and cause.
+     *
+     * @param s the exception message
+     * @param throwable the underlying cause
+     */
     public ServerAuthException(String s, Throwable throwable)
     {
         super(s, throwable);
     }
 
+    /**
+     * Creates a server authentication exception with the given cause.
+     *
+     * @param throwable the underlying cause
+     */
     public ServerAuthException(Throwable throwable)
     {
         super(throwable);

jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/Attachable.java

@@ -25,9 +25,9 @@ public interface Attachable
     Object getAttachment();
 
     /**
-     * Attaches the given object to this stream for later retrieval.
+     * Attaches the given object for later retrieval.
      *
-     * @param attachment the object to attach to this instance
+     * @param attachment the object to attach
      */
     void setAttachment(Object attachment);
 }

jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/Fields.java

@@ -47,7 +47,7 @@ public Fields()
     }
 
     /**
-     * <p>Creates an empty, modifiable, case insensitive {@code Fields} instance.</p>**
+     * <p>Creates an empty, modifiable {@code Fields} instance.</p>
      *
      * @param caseSensitive whether this {@code Fields} instance must be case sensitive
      */
@@ -56,16 +56,31 @@ public Fields(boolean caseSensitive)
         this(caseSensitive ? new LinkedHashMap<>() : new TreeMap<>(String::compareToIgnoreCase));
     }
 
+    /**
+     * Creates a {@code Fields} instance from a MultiMap.
+     *
+     * @param params the multimap to convert to fields
+     */
     public Fields(MultiMap<String> params)
     {
         this(multiMapToMapOfFields(params));
     }
 
+    /**
+     * Creates a {@code Fields} instance from a map of fields.
+     *
+     * @param fields the map of fields to use
+     */
     public Fields(Map<String, Field> fields)
     {
         this.fields = fields;
     }
 
+    /**
+     * Creates a copy of the given {@code Fields} instance.
+     *
+     * @param fields the fields to copy
+     */
     public Fields(Fields fields)
     {
         if (fields.fields instanceof TreeMap<String, Field>)
@@ -87,6 +102,9 @@ else if (Collections.unmodifiableMap(fields.fields) == fields.fields)
         }
     }
 
+    /**
+     * @return an immutable view of this fields instance
+     */
     public Fields asImmutable()
     {
         Map<String, Field> unmodifiable = Collections.unmodifiableMap(fields);

jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/SocketAddressResolver.java

@@ -109,8 +109,8 @@ public static class Async implements SocketAddressResolver
         private final long timeout;
 
         /**
-         * Creates a new instance with the given executor (to perform DNS resolution in a separate thread),
-         * the given scheduler (to cancel the operation if it takes too long) and the given timeout, in milliseconds.
+         * Creates a new instance with the specified executor (to perform DNS resolution in a separate thread),
+         * scheduler (to cancel the operation if it takes too long) and timeout, in milliseconds.
          *
          * @param executor the thread pool to use to perform DNS resolution in pooled threads
          * @param scheduler the scheduler to schedule tasks to cancel DNS resolution if it takes too long
@@ -123,11 +123,17 @@ public Async(Executor executor, Scheduler scheduler, long timeout)
             this.timeout = timeout;
         }
 
+        /**
+         * @return the executor used for DNS resolution
+         */
         public Executor getExecutor()
         {
             return executor;
         }
 
+        /**
+         * @return the scheduler used for timeout operations
+         */
         public Scheduler getScheduler()
         {
             return scheduler;

jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/security/SecurityUtils.java

@@ -154,7 +154,7 @@ private static <T> T doPrivileged(MethodHandle doPrivileged, PrivilegedAction<T>
     }
 
     /**
-     * <p>Runs the given action as the given subject.</p>
+     * <p>Runs the action as the specified subject.</p>
      *
      * @param subject the subject this action runs as
      * @param action the action to run

jetty-ee10/jetty-ee10-servlet/src/test/java/org/eclipse/jetty/ee10/servlet/DefaultServletTest.java

@@ -1242,7 +1242,7 @@ public void testWelcomeMultipleDefaultServletsDifferentBases() throws Exception
         assertThat(response.toString(), response.getStatus(), is(HttpStatus.OK_200));
         assertThat(response.getContent(), containsString("<h1>Alt Index</h1>"));
 
-        // Let's try deleting the `index.html` and accesing the welcome file at `index.htm`
+        // Let's try deleting the `index.html` and accessing the welcome file at `index.htm`
         // We skip this section of the test if the OS or filesystem doesn't support instantaneous delete
         // such as what happens on Microsoft Windows.
         if (deleteFile(altIndex))

jetty-ee10/jetty-ee10-servlet/src/test/java/org/eclipse/jetty/ee10/servlet/DispatcherTest.java

@@ -173,7 +173,7 @@ public void testMultiPartForwardAttribute() throws Exception
     }
 
     @Test
-    public void testFowardThenForward() throws Exception
+    public void testForwardThenForward() throws Exception
     {
         _contextHandler.addServlet(ForwardServlet.class, "/ForwardServlet/*");
         _contextHandler.addServlet(AlwaysForwardServlet.class, "/AlwaysForwardServlet/*");

jetty-ee10/jetty-ee10-servlet/src/test/java/org/eclipse/jetty/ee10/servlet/ResourceServletTest.java

@@ -1306,7 +1306,7 @@ public void testWelcomeMultipleResourceServletsDifferentBases() throws Exception
         assertThat(response.toString(), response.getStatus(), is(HttpStatus.OK_200));
         assertThat(response.getContent(), containsString("<h1>Alt Index</h1>"));
 
-        // Let's try deleting the `index.html` and accesing the welcome file at `index.htm`
+        // Let's try deleting the `index.html` and accessing the welcome file at `index.htm`
         // We skip this section of the test if the OS or filesystem doesn't support instantaneous delete
         // such as what happens on Microsoft Windows.
         if (deleteFile(altIndex))

jetty-ee10/jetty-ee10-servlet/src/test/java/org/eclipse/jetty/ee10/servlet/ServletUpgradeTest.java

@@ -334,7 +334,7 @@ private static boolean compareString(String expected, String actual)
             }
 
             LOG.debug("[ServletTestUtil] Found search string: '" + search + "' at index '" + searchIdx + "' in the server's " + "response");
-            // the new searchIdx is the old index plus the lenght of the
+            // the new searchIdx is the old index plus the length of the
             // search string.
             startIdx = searchIdx + search.length();
         }