You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by re...@apache.org on 2026/05/11 09:16:34 UTC

(tomcat) branch 11.0.x updated: Fix Jakarta EE APIs javadoc issues

This is an automated email from the ASF dual-hosted git repository.

rmaucher pushed a commit to branch 11.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git


The following commit(s) were added to refs/heads/11.0.x by this push:
     new 9d8b4c99e9 Fix Jakarta EE APIs javadoc issues
9d8b4c99e9 is described below

commit 9d8b4c99e9075901a651fbb3152981a547e96121
Author: remm <re...@apache.org>
AuthorDate: Sat May 9 09:04:07 2026 +0200

    Fix Jakarta EE APIs javadoc issues
    
    Includes TODO fixes and a few cut and paste issues.
    Coauthored by OpenCode.
    One question is if the explicit default constructor will mess up with
    the signature validation from the TCK, in which case I will redo it
    without that (so I will not backport for now).
---
 java/jakarta/annotation/Generated.java             |  16 ++-
 java/jakarta/annotation/Priority.java              |   6 +-
 java/jakarta/annotation/Resource.java              |  35 +++++--
 java/jakarta/annotation/Resources.java             |   5 +-
 java/jakarta/annotation/security/DeclareRoles.java |  11 +-
 java/jakarta/annotation/security/DenyAll.java      |   6 ++
 java/jakarta/annotation/security/PermitAll.java    |   6 ++
 java/jakarta/annotation/security/RolesAllowed.java |  12 ++-
 java/jakarta/annotation/security/RunAs.java        |  10 +-
 .../annotation/sql/DataSourceDefinition.java       |  95 +++++++++++++----
 .../annotation/sql/DataSourceDefinitions.java      |   8 +-
 java/jakarta/ejb/EJB.java                          |  38 ++++++-
 java/jakarta/ejb/EJBs.java                         |  11 +-
 java/jakarta/el/BeanNameELResolver.java            |   8 ++
 java/jakarta/el/BeanNameResolver.java              |   9 +-
 java/jakarta/el/CompositeELResolver.java           |  15 +++
 java/jakarta/el/ELClass.java                       |  14 +++
 java/jakarta/el/ELContext.java                     |  50 +++++++++
 java/jakarta/el/ELContextEvent.java                |  13 +++
 java/jakarta/el/ELContextListener.java             |  13 +++
 java/jakarta/el/ELManager.java                     |  98 ++++++++++++++++++
 java/jakarta/el/ELProcessor.java                   |  86 +++++++++++++++-
 java/jakarta/el/ELResolver.java                    |  17 +++
 java/jakarta/el/EvaluationListener.java            |  10 ++
 java/jakarta/el/Expression.java                    |  21 +++-
 java/jakarta/el/ExpressionFactory.java             |  35 ++++++-
 java/jakarta/el/FunctionMapper.java                |  24 +++++
 java/jakarta/el/ImportHandler.java                 |  57 ++++++++++-
 java/jakarta/el/LambdaExpression.java              |  45 ++++++++
 java/jakarta/el/ListELResolver.java                |  18 ++++
 java/jakarta/el/MapELResolver.java                 |  18 ++++
 java/jakarta/el/MethodExpression.java              |  16 +++
 java/jakarta/el/MethodInfo.java                    |  29 ++++++
 java/jakarta/el/MethodNotFoundException.java       |  22 ++++
 java/jakarta/el/MethodReference.java               |  12 +++
 java/jakarta/el/OptionalELResolver.java            |   6 ++
 java/jakarta/el/PropertyNotFoundException.java     |  27 +++++
 java/jakarta/el/PropertyNotWritableException.java  |  27 +++++
 java/jakarta/el/RecordELResolver.java              |   7 ++
 java/jakarta/el/ResourceBundleELResolver.java      |  18 ++++
 java/jakarta/el/StandardELContext.java             |  29 ++++++
 java/jakarta/el/StaticFieldELResolver.java         |  11 ++
 java/jakarta/el/TypeConverter.java                 |  11 ++
 java/jakarta/el/ValueExpression.java               |  33 ++++++
 java/jakarta/el/ValueReference.java                |  23 +++++
 java/jakarta/el/VariableMapper.java                |  25 ++++-
 java/jakarta/mail/Authenticator.java               |  18 ++++
 java/jakarta/mail/PasswordAuthentication.java      |  12 +++
 java/jakarta/mail/Session.java                     |  22 ++++
 java/jakarta/mail/internet/InternetAddress.java    |  11 ++
 java/jakarta/mail/internet/MimeMessage.java        |  19 ++++
 java/jakarta/mail/internet/MimePart.java           |   4 +
 java/jakarta/mail/internet/MimePartDataSource.java |   9 ++
 java/jakarta/persistence/PersistenceContext.java   |  30 +++++-
 .../persistence/PersistenceContextType.java        |  16 ++-
 java/jakarta/persistence/PersistenceContexts.java  |   9 +-
 java/jakarta/persistence/PersistenceProperty.java  |  15 ++-
 java/jakarta/persistence/PersistenceUnit.java      |  16 ++-
 java/jakarta/persistence/PersistenceUnits.java     |   9 +-
 java/jakarta/persistence/SynchronizationType.java  |   9 ++
 .../security/auth/message/AuthException.java       |  12 +++
 java/jakarta/security/auth/message/AuthStatus.java |  23 +++++
 java/jakarta/security/auth/message/ClientAuth.java |   4 +
 .../jakarta/security/auth/message/MessageInfo.java |  38 +++++++
 .../security/auth/message/MessagePolicy.java       |  99 ++++++++++++++++++
 java/jakarta/security/auth/message/ServerAuth.java |   7 ++
 .../message/callback/CallerPrincipalCallback.java  |  34 +++++-
 .../auth/message/callback/CertStoreCallback.java   |  16 ++-
 .../message/callback/GroupPrincipalCallback.java   |  19 ++++
 .../callback/PasswordValidationCallback.java       |  49 ++++++++-
 .../auth/message/callback/PrivateKeyCallback.java  | 113 +++++++++++++++++++-
 .../auth/message/callback/SecretKeyCallback.java   |  37 +++++++
 .../auth/message/callback/TrustStoreCallback.java  |  16 +++
 .../security/auth/message/config/AuthConfig.java   |  31 ++++++
 .../auth/message/config/AuthConfigFactory.java     | 112 ++++++++++++++++++++
 .../auth/message/config/AuthConfigProvider.java    |  30 ++++++
 .../auth/message/config/ClientAuthConfig.java      |  15 +++
 .../auth/message/config/ClientAuthContext.java     |   5 +
 .../auth/message/config/RegistrationListener.java  |   9 ++
 .../auth/message/config/ServerAuthConfig.java      |  12 +++
 .../auth/message/config/ServerAuthContext.java     |   7 ++
 .../auth/message/module/ClientAuthModule.java      |  21 ++++
 .../auth/message/module/ServerAuthModule.java      |  25 +++++
 java/jakarta/servlet/AsyncContext.java             |  34 ++++--
 java/jakarta/servlet/GenericFilter.java            |  13 ++-
 java/jakarta/servlet/HttpConstraintElement.java    |  12 +--
 java/jakarta/servlet/ServletContext.java           |  84 ++++++++++-----
 java/jakarta/servlet/ServletRequest.java           |  53 ++++++----
 java/jakarta/servlet/ServletRequestWrapper.java    |   8 +-
 java/jakarta/servlet/ServletResponseWrapper.java   |   6 +-
 java/jakarta/servlet/annotation/HandlesTypes.java  |   8 +-
 .../servlet/annotation/MultipartConfig.java        |   9 ++
 java/jakarta/servlet/annotation/WebFilter.java     |  22 +++-
 java/jakarta/servlet/annotation/WebInitParam.java  |   6 ++
 java/jakarta/servlet/annotation/WebListener.java   |   2 +
 java/jakarta/servlet/annotation/WebServlet.java    |  86 ++++++++++------
 java/jakarta/servlet/http/HttpFilter.java          |   7 ++
 java/jakarta/servlet/http/HttpServletMapping.java  |  36 ++++---
 java/jakarta/servlet/http/PushBuilder.java         |   6 +-
 .../transaction/HeuristicCommitException.java      |  14 +++
 .../transaction/HeuristicMixedException.java       |  14 +++
 .../transaction/HeuristicRollbackException.java    |  14 +++
 .../transaction/InvalidTransactionException.java   |  13 +++
 .../jakarta/transaction/NotSupportedException.java |  11 ++
 java/jakarta/transaction/RollbackException.java    |  11 ++
 java/jakarta/transaction/Status.java               |  33 ++++++
 java/jakarta/transaction/Synchronization.java      |  17 +++
 java/jakarta/transaction/SystemException.java      |  21 ++++
 java/jakarta/transaction/Transaction.java          |  63 ++++++++++++
 java/jakarta/transaction/TransactionManager.java   |  68 ++++++++++++
 .../transaction/TransactionRequiredException.java  |  11 ++
 .../TransactionRolledbackException.java            |  11 ++
 .../TransactionSynchronizationRegistry.java        |  40 ++++++++
 java/jakarta/transaction/UserTransaction.java      |  47 +++++++++
 java/jakarta/websocket/ClientEndpoint.java         |  25 +++++
 java/jakarta/websocket/ClientEndpointConfig.java   |  82 +++++++++++++++
 java/jakarta/websocket/CloseReason.java            | 106 +++++++++++++++++++
 java/jakarta/websocket/ContainerProvider.java      |  11 ++
 java/jakarta/websocket/DecodeException.java        |  45 ++++++++
 java/jakarta/websocket/Decoder.java                |  68 ++++++++++++
 java/jakarta/websocket/DeploymentException.java    |  14 +++
 java/jakarta/websocket/EncodeException.java        |  24 +++++
 java/jakarta/websocket/Encoder.java                |  58 ++++++++++-
 java/jakarta/websocket/Endpoint.java               |  10 ++
 java/jakarta/websocket/EndpointConfig.java         |  19 ++++
 java/jakarta/websocket/Extension.java              |  28 +++++
 java/jakarta/websocket/HandshakeResponse.java      |   8 ++
 java/jakarta/websocket/MessageHandler.java         |  16 +++
 java/jakarta/websocket/OnClose.java                |   4 +
 java/jakarta/websocket/OnError.java                |   4 +
 java/jakarta/websocket/OnMessage.java              |  11 ++
 java/jakarta/websocket/OnOpen.java                 |   4 +
 java/jakarta/websocket/RemoteEndpoint.java         |  22 ++++
 java/jakarta/websocket/SendHandler.java            |   8 ++
 java/jakarta/websocket/SendResult.java             |  14 +++
 java/jakarta/websocket/Session.java                |  83 +++++++++++++++
 java/jakarta/websocket/SessionException.java       |  18 ++++
 java/jakarta/websocket/WebSocketContainer.java     |  22 ++++
 .../jakarta/websocket/server/HandshakeRequest.java |  44 ++++++++
 java/jakarta/websocket/server/PathParam.java       |   6 ++
 java/jakarta/websocket/server/ServerContainer.java |  13 +++
 java/jakarta/websocket/server/ServerEndpoint.java  |  25 +++++
 .../websocket/server/ServerEndpointConfig.java     | 114 +++++++++++++++++++++
 java/jakarta/xml/ws/WebServiceRef.java             |  31 +++++-
 java/jakarta/xml/ws/WebServiceRefs.java            |  11 +-
 145 files changed, 3585 insertions(+), 182 deletions(-)

diff --git a/java/jakarta/annotation/Generated.java b/java/jakarta/annotation/Generated.java
index 19cbed8bc6..8251be3970 100644
--- a/java/jakarta/annotation/Generated.java
+++ b/java/jakarta/annotation/Generated.java
@@ -33,18 +33,26 @@ import java.lang.annotation.Target;
 @Retention(RetentionPolicy.SOURCE)
 public @interface Generated {
     /**
-     * @return The name of the code generator. It is recommended that the fully qualified name of the code generator is
-     *             used.
+     * Specifies the name(s) of the tool(s) that generated the annotated element.
+     * It is recommended that the fully qualified name of the code generator is used.
+     *
+     * @return the array of code generator names
      */
     String[] value();
 
     /**
-     * @return The date the code was generated
+     * Specifies the date and time when the code was generated, typically in
+     * ISO 8601 format. An empty string indicates the date is not specified.
+     *
+     * @return the code generation date, or an empty string if not specified
      */
     String date() default "";
 
     /**
-     * @return Additional comments (if any) related to the code generation
+     * Provides additional comments or metadata related to the code generation
+     * process, such as version information or configuration details.
+     *
+     * @return additional comments about the code generation, or an empty string if none
      */
     String comments() default "";
 }
diff --git a/java/jakarta/annotation/Priority.java b/java/jakarta/annotation/Priority.java
index c44be40d7f..4809275165 100644
--- a/java/jakarta/annotation/Priority.java
+++ b/java/jakarta/annotation/Priority.java
@@ -31,7 +31,11 @@ import java.lang.annotation.RetentionPolicy;
 public @interface Priority {
 
     /**
-     * @return the int value
+     * Specifies the priority value used to determine the ordering of the annotated
+     * element. Lower values indicate higher priority. The annotated class or
+     * parameter defines how the priority value is interpreted and applied.
+     *
+     * @return the priority ordering value
      */
     int value();
 }
diff --git a/java/jakarta/annotation/Resource.java b/java/jakarta/annotation/Resource.java
index 692d13418e..a66f5fc621 100644
--- a/java/jakarta/annotation/Resource.java
+++ b/java/jakarta/annotation/Resource.java
@@ -48,7 +48,10 @@ public @interface Resource {
     }
 
     /**
-     * @return a String with the name of the resource
+     * Specifies the logical name of the resource. If not specified, the container
+     * derives the name from the field or method to which the annotation is applied.
+     *
+     * @return the logical name of the resource
      */
     String name() default "";
 
@@ -60,29 +63,49 @@ public @interface Resource {
     Class<?> type() default Object.class;
 
     /**
-     * @return the AuthenticationType of the resource default CONTAINER
+     * Specifies the authentication type for the resource. Container authentication
+     * means the container handles authentication, while application authentication
+     * means the application code is responsible for authentication.
+     *
+     * @return the authentication type, defaulting to {@link AuthenticationType#CONTAINER}
      */
     AuthenticationType authenticationType() default AuthenticationType.CONTAINER;
 
     /**
-     * @return true (default) if the resource is shareable, or false if not
+     * Indicates whether the resource can be shared among multiple injection points.
+     * When true, the same resource instance may be injected into multiple components.
+     * When false, each injection point receives a distinct resource instance.
+     *
+     * @return true if the resource is shareable across injection points, false otherwise
      */
     boolean shareable() default true;
 
     /**
-     * @return a string with the description for the resource
+     * Provides a human-readable description of the resource for documentation
+     * and administrative purposes.
+     *
+     * @return the resource description
      */
     String description() default "";
 
     /**
-     * @return a string with the mappedName of the resource
+     * Specifies a product-dependent name for the resource, allowing the container
+     * to map the logical resource name to a physical resource in a vendor-specific
+     * manner. This is typically used for environment-specific configuration.
+     *
+     * @return the product-specific mapped name for the resource
      */
     String mappedName() default "";
 
     /**
+     * Specifies the JNDI lookup name for the resource. This attribute allows
+     * explicit control over the JNDI name used to locate the resource, overriding
+     * the default name derivation. The lookup name is typically prefixed with
+     * "java:comp/env/" for component environment entries.
+     *
      * @since Common Annotations 1.1
      *
-     * @return The name of the entry, if any, to use for this resource
+     * @return the JNDI lookup name for the resource
      */
     String lookup() default "";
 }
diff --git a/java/jakarta/annotation/Resources.java b/java/jakarta/annotation/Resources.java
index 6ade76d6a6..bf668c6f1f 100644
--- a/java/jakarta/annotation/Resources.java
+++ b/java/jakarta/annotation/Resources.java
@@ -33,7 +33,10 @@ import java.lang.annotation.Target;
 public @interface Resources {
 
     /**
-     * @return a Resource[] with the value of this Resources
+     * Specifies the array of {@link Resource} annotations that define the resources
+     * required by the annotated component.
+     *
+     * @return the array of resource definitions
      */
     Resource[] value();
 }
diff --git a/java/jakarta/annotation/security/DeclareRoles.java b/java/jakarta/annotation/security/DeclareRoles.java
index 3762af6a94..434aea50fd 100644
--- a/java/jakarta/annotation/security/DeclareRoles.java
+++ b/java/jakarta/annotation/security/DeclareRoles.java
@@ -23,6 +23,11 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
+ * Declares that role names used in security constraints for the annotated
+ * enterprise bean should be treated as declared roles. When this annotation
+ * is present, the container must create any roles referenced in security
+ * constraints that are not explicitly defined in the deployment descriptor.
+ *
  * @since Common Annotations 1.0
  */
 @Documented
@@ -31,7 +36,11 @@ import java.lang.annotation.Target;
 public @interface DeclareRoles {
 
     /**
-     * @return a String[] with the roles
+     * Specifies the declared role names that should be recognized by the container.
+     * These roles may be referenced in security constraints without being explicitly
+     * defined in the deployment descriptor.
+     *
+     * @return the array of declared role names
      */
     String[] value();
 }
diff --git a/java/jakarta/annotation/security/DenyAll.java b/java/jakarta/annotation/security/DenyAll.java
index 9944210ce7..10db8d2a76 100644
--- a/java/jakarta/annotation/security/DenyAll.java
+++ b/java/jakarta/annotation/security/DenyAll.java
@@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
+ * Indicates that all access to the annotated enterprise bean or business method
+ * is denied. When applied at the class level, all security roles are prohibited
+ * from invoking any business method of the bean. When applied at the method level,
+ * the specified method is inaccessible to all roles. This annotation takes
+ * precedence over {@link PermitAll} and {@link RolesAllowed}.
+ *
  * @since Common Annotations 1.0
  */
 @Documented
diff --git a/java/jakarta/annotation/security/PermitAll.java b/java/jakarta/annotation/security/PermitAll.java
index 0e0c784c65..d129f8f2bc 100644
--- a/java/jakarta/annotation/security/PermitAll.java
+++ b/java/jakarta/annotation/security/PermitAll.java
@@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
+ * Indicates that all authenticated users are permitted to access the annotated
+ * enterprise bean or business method. When applied at the class level, any
+ * authenticated user may invoke any business method of the bean. When applied
+ * at the method level, the specified method is accessible to all authenticated
+ * users. This annotation takes precedence over {@link RolesAllowed}.
+ *
  * @since Common Annotations 1.0
  */
 @Documented
diff --git a/java/jakarta/annotation/security/RolesAllowed.java b/java/jakarta/annotation/security/RolesAllowed.java
index 7092d01ab3..48b003de31 100644
--- a/java/jakarta/annotation/security/RolesAllowed.java
+++ b/java/jakarta/annotation/security/RolesAllowed.java
@@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
+ * Specifies the security roles that are allowed to access the annotated enterprise
+ * bean or business method. When applied at the class level, only the listed roles
+ * may invoke any business method of the bean. When applied at the method level,
+ * only the listed roles may invoke the specified method. This annotation is
+ * mutually exclusive with {@link PermitAll} and {@link DenyAll}.
+ *
  * @since Common Annotations 1.0
  */
 @Documented
@@ -31,7 +37,11 @@ import java.lang.annotation.Target;
 public @interface RolesAllowed {
 
     /**
-     * @return a String[] of the allowed roles
+     * Specifies the security role names that are authorized to access the
+     * annotated component or method. Only callers assigned one of these roles
+     * will be permitted access.
+     *
+     * @return the array of authorized role names
      */
     String[] value();
 }
diff --git a/java/jakarta/annotation/security/RunAs.java b/java/jakarta/annotation/security/RunAs.java
index d5029b7ecc..8d935eb51c 100644
--- a/java/jakarta/annotation/security/RunAs.java
+++ b/java/jakarta/annotation/security/RunAs.java
@@ -23,6 +23,11 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
+ * Defines the run-as security role for an enterprise bean. The container assumes
+ * the specified role as the caller identity for all business method invocations
+ * made by the bean, regardless of the actual caller's identity. This allows the
+ * bean to access resources with a consistent security context.
+ *
  * @since Common Annotations 1.0
  */
 @Documented
@@ -31,7 +36,10 @@ import java.lang.annotation.Target;
 public @interface RunAs {
 
     /**
-     * @return a String with the value for RunAs
+     * Specifies the security role name that the container should assume as the
+     * caller identity when executing business methods on behalf of this component.
+     *
+     * @return the run-as role name
      */
     String value();
 }
diff --git a/java/jakarta/annotation/sql/DataSourceDefinition.java b/java/jakarta/annotation/sql/DataSourceDefinition.java
index 9e5c46d0f3..0bea20aa2b 100644
--- a/java/jakarta/annotation/sql/DataSourceDefinition.java
+++ b/java/jakarta/annotation/sql/DataSourceDefinition.java
@@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
+ * Defines a data source for dependency injection via the {@link jakarta.annotation.Resource}
+ * annotation. This annotation allows developers to declaratively specify the properties
+ * of a JDBC data source, including connection details, pool sizing, and transactional
+ * behavior. The container creates and manages the data source based on the specified
+ * configuration, making it available for injection into application components.
+ *
  * @since Common Annotations 1.1
  */
 @Target(ElementType.TYPE)
@@ -31,92 +37,145 @@ import java.lang.annotation.Target;
 public @interface DataSourceDefinition {
 
     /**
-     * @return the className
+     * Specifies the fully qualified class name of the JDBC driver or the Jakarta
+     * Connector connection factory class that implements this data source.
+     *
+     * @return the fully qualified class name of the data source implementation
      */
     String className();
 
     /**
-     * @return the name
+     * Specifies the JNDI name under which the data source will be registered.
+     * This is the lookup name used for dependency injection or explicit JNDI
+     * lookup of the data source.
+     *
+     * @return the JNDI name for the data source
      */
     String name();
 
     /**
-     * @return the description
+     * Provides a human-readable description of the data source for documentation
+     * and administrative purposes.
+     *
+     * @return the description of the data source
      */
     String description() default "";
 
     /**
-     * @return the url
+     * Specifies the JDBC connection URL for the database. This URL is used by
+     * the driver to establish connections to the database server.
+     *
+     * @return the JDBC connection URL
      */
     String url() default "";
 
     /**
-     * @return the user
+     * Specifies the database user name used to establish connections.
+     *
+     * @return the database user name
      */
     String user() default "";
 
     /**
-     * @return the password
+     * Specifies the password for the database user account used to establish connections.
+     *
+     * @return the database password
      */
     String password() default "";
 
     /**
-     * @return database name
+     * Specifies the name of the database to connect to. This is used in conjunction
+     * with the server name and port number to locate the target database.
+     *
+     * @return the database name
      */
     String databaseName() default "";
 
     /**
-     * @return the port number
+     * Specifies the network port number on which the database server is listening.
+     * A value of -1 indicates the default port for the database type.
+     *
+     * @return the database server port number, or -1 for the default
      */
     int portNumber() default -1;
 
     /**
-     * @return the server name
+     * Specifies the host name or IP address of the database server.
+     *
+     * @return the database server host name, defaulting to "localhost"
      */
     String serverName() default "localhost";
 
     /**
-     * @return the isolation level
+     * Specifies the transaction isolation level for connections from this data source,
+     * using the constants defined in {@link java.sql.Connection}. A value of -1
+     * indicates the database default isolation level should be used.
+     *
+     * @return the transaction isolation level, or -1 for the database default
      */
     int isolationLevel() default -1;
 
     /**
-     * @return true if the data source is transactional
+     * Indicates whether connections from this data source support container-managed
+     * transactions. When true, the data source participates in Jakarta Transactions.
+     *
+     * @return true if the data source participates in container-managed transactions
      */
     boolean transactional() default true;
 
     /**
-     * @return the initial pool size
+     * Specifies the number of connections to create when the connection pool is
+     * initialized. A value of -1 indicates the container default should be used.
+     *
+     * @return the initial number of connections in the pool, or -1 for default
      */
     int initialPoolSize() default -1;
 
     /**
-     * @return the max pool size
+     * Specifies the maximum number of connections that the pool may create.
+     * A value of -1 indicates the container default should be used.
+     *
+     * @return the maximum pool size, or -1 for the container default
      */
     int maxPoolSize() default -1;
 
     /**
-     * @return the min pool size
+     * Specifies the minimum number of connections that the pool must maintain.
+     * A value of -1 indicates the container default should be used.
+     *
+     * @return the minimum pool size, or -1 for the container default
      */
     int minPoolSize() default -1;
 
     /**
-     * @return the max idle time
+     * Specifies the maximum idle time in seconds before a connection is closed
+     * and removed from the pool. A value of -1 indicates no idle timeout.
+     *
+     * @return the maximum idle time in seconds, or -1 for no timeout
      */
     int maxIdleTime() default -1;
 
     /**
-     * @return the max statements
+     * Specifies the maximum number of prepared statements that may be cached
+     * per connection in the pool. A value of -1 indicates the container default.
+     *
+     * @return the maximum cached prepared statements per connection, or -1 for default
      */
     int maxStatements() default -1;
 
     /**
-     * @return a String[] with the properties
+     * Specifies additional connection properties in the form "name=value" strings.
+     * These properties are passed to the JDBC driver during connection establishment.
+     *
+     * @return the array of additional connection properties
      */
     String[] properties() default {};
 
     /**
-     * @return the login timeout
+     * Specifies the maximum time in seconds that the driver will wait when
+     * attempting to connect to the database. A value of 0 means no timeout.
+     *
+     * @return the login timeout in seconds, or 0 for no timeout
      */
     int loginTimeout() default 0;
 }
diff --git a/java/jakarta/annotation/sql/DataSourceDefinitions.java b/java/jakarta/annotation/sql/DataSourceDefinitions.java
index d40e357af5..ace5402e7a 100644
--- a/java/jakarta/annotation/sql/DataSourceDefinitions.java
+++ b/java/jakarta/annotation/sql/DataSourceDefinitions.java
@@ -22,6 +22,10 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
+ * Container annotation that holds multiple {@link DataSourceDefinition} annotations.
+ * This annotation is used to group several data source definitions when applied to
+ * the same type, following the standard Java annotation repetition pattern.
+ *
  * @since Common Annotations 1.1
  */
 @Target(ElementType.TYPE)
@@ -29,7 +33,9 @@ import java.lang.annotation.Target;
 public @interface DataSourceDefinitions {
 
     /**
-     * @return a DataSourceDefinition[]
+     * Specifies the array of data source definitions contained within this container annotation.
+     *
+     * @return the array of {@link DataSourceDefinition} annotations
      */
     DataSourceDefinition[] value();
 }
diff --git a/java/jakarta/ejb/EJB.java b/java/jakarta/ejb/EJB.java
index cd5b24720c..94fab54075 100644
--- a/java/jakarta/ejb/EJB.java
+++ b/java/jakarta/ejb/EJB.java
@@ -21,20 +21,56 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Declares a dependency on an enterprise bean. The EJB annotation can be applied to a field or method to inject
+ * a reference to an enterprise bean, or to a class to declare bean dependencies for the entire bean.
+ */
 @Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD })
 @Retention(RetentionPolicy.RUNTIME)
-
 public @interface EJB {
+
+    /**
+     * The name element for the annotation. The name of an enterprise bean is relative to the javax.np.Context of
+     * the bean. The name must be unique within the bean.
+     *
+     * @return the name of the enterprise bean
+     */
     String name() default "";
 
+    /**
+     * A description of the enterprise bean reference.
+     *
+     * @return the description
+     */
     String description() default "";
 
+    /**
+     * The interface of the enterprise bean.
+     *
+     * @return the bean interface class
+     */
     @SuppressWarnings("rawtypes") // Can't use Class<?> because API needs to match specification
     Class beanInterface() default Object.class;
 
+    /**
+     * The name of the enterprise bean. The beanName is relative to the javax.naming.Context of the bean that
+     * owns this reference.
+     *
+     * @return the name of the enterprise bean
+     */
     String beanName() default "";
 
+    /**
+     * A provider-specific name that this reference should be mapped to. The entire name is provider-specific.
+     *
+     * @return the provider-specific mapped name
+     */
     String mappedName() default "";
 
+    /**
+     * A JNDI name used to locate the enterprise bean. The lookup element overrides the default JNDI lookup name.
+     *
+     * @return the JNDI lookup string
+     */
     String lookup() default "";
 }
diff --git a/java/jakarta/ejb/EJBs.java b/java/jakarta/ejb/EJBs.java
index 5f2647cb17..2457371609 100644
--- a/java/jakarta/ejb/EJBs.java
+++ b/java/jakarta/ejb/EJBs.java
@@ -21,9 +21,18 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Groups multiple {@link EJB} annotations on a single declaration. Use this annotation when a class has dependencies
+ * on more than one enterprise bean.
+ */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
-
 public @interface EJBs {
+
+    /**
+     * The array of EJB annotations.
+     *
+     * @return the EJB annotations
+     */
     EJB[] value();
 }
diff --git a/java/jakarta/el/BeanNameELResolver.java b/java/jakarta/el/BeanNameELResolver.java
index 8331e310f4..248b08fe4f 100644
--- a/java/jakarta/el/BeanNameELResolver.java
+++ b/java/jakarta/el/BeanNameELResolver.java
@@ -19,12 +19,20 @@ package jakarta.el;
 import java.util.Objects;
 
 /**
+ * ELResolver that resolves bean names to bean instances using a {@link BeanNameResolver}. This resolver handles
+ * expressions where the base is {@code null} and the property is a {@link String} representing a bean name.
+ *
  * @since EL 3.0
  */
 public class BeanNameELResolver extends ELResolver {
 
     private final BeanNameResolver beanNameResolver;
 
+    /**
+     * Constructs a BeanNameELResolver with the specified BeanNameResolver.
+     *
+     * @param beanNameResolver the resolver used to look up beans by name
+     */
     public BeanNameELResolver(BeanNameResolver beanNameResolver) {
         this.beanNameResolver = beanNameResolver;
     }
diff --git a/java/jakarta/el/BeanNameResolver.java b/java/jakarta/el/BeanNameResolver.java
index 17754a1553..c8ab3a8661 100644
--- a/java/jakarta/el/BeanNameResolver.java
+++ b/java/jakarta/el/BeanNameResolver.java
@@ -18,12 +18,19 @@ package jakarta.el;
 
 /**
  * Base implementation that provides a minimal default implementation that is intended to be extended by application
- * developers.
+ * developers. Subclasses define the logic for resolving bean names to bean instances, checking read-only status,
+ * and determining whether new beans can be created.
  *
  * @since EL 3.0
  */
 public abstract class BeanNameResolver {
 
+    /**
+     * Default constructor for subclasses.
+     */
+    public BeanNameResolver() {
+    }
+
     /**
      * Can this resolver resolve the given bean name?
      *
diff --git a/java/jakarta/el/CompositeELResolver.java b/java/jakarta/el/CompositeELResolver.java
index 8c9c1fc335..4a73d13d72 100644
--- a/java/jakarta/el/CompositeELResolver.java
+++ b/java/jakarta/el/CompositeELResolver.java
@@ -20,6 +20,11 @@ import java.util.HashSet;
 import java.util.Objects;
 import java.util.Set;
 
+/**
+ * ELResolver that delegates to an ordered list of other ELResolvers. When a property operation is performed, each
+ * contained resolver is invoked in order until one resolves the property. This is the standard mechanism for
+ * building a resolver chain in an EL context.
+ */
 public class CompositeELResolver extends ELResolver {
 
     private static final Class<?> SCOPED_ATTRIBUTE_EL_RESOLVER;
@@ -62,6 +67,9 @@ public class CompositeELResolver extends ELResolver {
     private int typeConvertersSize;
     private ELResolver[] typeConverters;
 
+    /**
+     * Constructs an empty CompositeELResolver. Use {@link #add(ELResolver)} to add resolvers to the chain.
+     */
     public CompositeELResolver() {
         resolversSize = 0;
         resolvers = new ELResolver[8];
@@ -70,6 +78,13 @@ public class CompositeELResolver extends ELResolver {
         typeConverters = new ELResolver[0];
     }
 
+    /**
+     * Adds an ELResolver to the end of the resolver chain.
+     *
+     * @param elResolver the resolver to add
+     *
+     * @throws NullPointerException if elResolver is {@code null}
+     */
     public void add(ELResolver elResolver) {
         Objects.requireNonNull(elResolver);
 
diff --git a/java/jakarta/el/ELClass.java b/java/jakarta/el/ELClass.java
index 0d003029ec..d72fd9bf0e 100644
--- a/java/jakarta/el/ELClass.java
+++ b/java/jakarta/el/ELClass.java
@@ -17,16 +17,30 @@
 package jakarta.el;
 
 /**
+ * Wrapper for a {@link Class} object that enables access to static fields and methods from EL expressions. An
+ * ELClass instance is used as the base object when resolving static members, typically in conjunction with the
+ * {@link StaticFieldELResolver}.
+ *
  * @since EL 3.0
  */
 public class ELClass {
 
     private final Class<?> clazz;
 
+    /**
+     * Constructs an ELClass wrapping the specified Class.
+     *
+     * @param clazz the class to wrap
+     */
     public ELClass(Class<?> clazz) {
         this.clazz = clazz;
     }
 
+    /**
+     * Returns the wrapped Class.
+     *
+     * @return the wrapped Class
+     */
     public Class<?> getKlass() {
         return clazz;
     }
diff --git a/java/jakarta/el/ELContext.java b/java/jakarta/el/ELContext.java
index f99f82c0f7..d0f7e4adbe 100644
--- a/java/jakarta/el/ELContext.java
+++ b/java/jakarta/el/ELContext.java
@@ -28,6 +28,11 @@ import java.util.Locale;
 import java.util.Map;
 import java.util.Objects;
 
+/**
+ * Provides the context in which an EL expression is evaluated. An ELContext holds references to the
+ * {@link ELResolver}, {@link FunctionMapper}, {@link VariableMapper}, {@link ImportHandler}, locale, and other
+ * objects required for expression evaluation. Implementations include {@link StandardELContext}.
+ */
 public abstract class ELContext {
 
     private Locale locale;
@@ -42,6 +47,9 @@ public abstract class ELContext {
 
     private Deque<Map<String,Object>> lambdaArguments = null;
 
+    /**
+     * Constructs an ELContext with the resolved flag set to {@code false}.
+     */
     public ELContext() {
         this.resolved = false;
     }
@@ -53,6 +61,13 @@ public abstract class ELContext {
         return lambdaArguments;
     }
 
+    /**
+     * Sets the internal flag indicating whether a property has been resolved during the current
+     * evaluation step. This method is used by {@link ELResolver} implementations to signal that
+     * they have handled the current base/property combination.
+     *
+     * @param resolved {@code true} if a property has been resolved, {@code false} otherwise
+     */
     public void setPropertyResolved(boolean resolved) {
         this.resolved = resolved;
     }
@@ -70,6 +85,13 @@ public abstract class ELContext {
         notifyPropertyResolved(base, property);
     }
 
+    /**
+     * Returns whether a property has been resolved during the current evaluation step.
+     * ELResolver implementations call {@link #setPropertyResolved(boolean)} to indicate resolution,
+     * and the expression evaluator checks this flag to determine if resolution was successful.
+     *
+     * @return {@code true} if a property has been resolved, {@code false} otherwise
+     */
     public boolean isPropertyResolved() {
         return this.resolved;
     }
@@ -110,6 +132,11 @@ public abstract class ELContext {
         return this.map.get(key);
     }
 
+    /**
+     * Returns the ELResolver used to resolve properties and method invocations during expression evaluation.
+     *
+     * @return the ELResolver for this context
+     */
     public abstract ELResolver getELResolver();
 
     /**
@@ -126,16 +153,39 @@ public abstract class ELContext {
         return importHandler;
     }
 
+    /**
+     * Returns the FunctionMapper used to resolve EL function names to Java methods during expression evaluation.
+     *
+     * @return the FunctionMapper for this context
+     */
     public abstract FunctionMapper getFunctionMapper();
 
+    /**
+     * Returns the locale associated with this EL context. The locale is used for type conversion
+     * operations such as parsing numbers and dates during expression evaluation.
+     *
+     * @return the locale for this context, or {@code null} if not set
+     */
     public Locale getLocale() {
         return this.locale;
     }
 
+    /**
+     * Sets the locale for this EL context. The locale is used for type conversion operations
+     * such as parsing numbers and dates during expression evaluation.
+     *
+     * @param locale the locale to use for this context
+     */
     public void setLocale(Locale locale) {
         this.locale = locale;
     }
 
+    /**
+     * Returns the VariableMapper used to resolve EL variable names to {@link ValueExpression}
+     * instances during expression evaluation.
+     *
+     * @return the VariableMapper for this context
+     */
     public abstract VariableMapper getVariableMapper();
 
     /**
diff --git a/java/jakarta/el/ELContextEvent.java b/java/jakarta/el/ELContextEvent.java
index b5bfda0e68..713e668b5e 100644
--- a/java/jakarta/el/ELContextEvent.java
+++ b/java/jakarta/el/ELContextEvent.java
@@ -19,18 +19,31 @@ package jakarta.el;
 import java.io.Serial;
 import java.util.EventObject;
 
+/**
+ * Event object passed to {@link ELContextListener} instances when an EL context is created or
+ * released. The source of this event is the {@link ELContext} that was created or released.
+ *
+ * @since EL 2.1
+ */
 public class ELContextEvent extends EventObject {
 
     @Serial
     private static final long serialVersionUID = 1255131906285426769L;
 
     /**
+     * Constructs an ELContextEvent with the specified ELContext as its source.
+     *
      * @param source The EL context that was the source of this event
      */
     public ELContextEvent(ELContext source) {
         super(source);
     }
 
+    /**
+     * Returns the ELContext that is the source of this event.
+     *
+     * @return the ELContext associated with this event
+     */
     public ELContext getELContext() {
         return (ELContext) this.getSource();
     }
diff --git a/java/jakarta/el/ELContextListener.java b/java/jakarta/el/ELContextListener.java
index d161362da7..31fb003165 100644
--- a/java/jakarta/el/ELContextListener.java
+++ b/java/jakarta/el/ELContextListener.java
@@ -16,8 +16,21 @@
  */
 package jakarta.el;
 
+/**
+ * Listener interface for EL context lifecycle events. Implementations are notified when an
+ * {@link ELContext} is created or released, allowing them to perform initialization or
+ * cleanup operations on the context.
+ *
+ * @since EL 2.1
+ */
 public interface ELContextListener extends java.util.EventListener {
 
+    /**
+     * Notification that an EL context has been created. Implementations can use this callback
+     * to register resources, resolvers, or other objects with the newly created context.
+     *
+     * @param event the event containing the ELContext that was created
+     */
     void contextCreated(ELContextEvent event);
 
 }
diff --git a/java/jakarta/el/ELManager.java b/java/jakarta/el/ELManager.java
index 4f552942cf..ae16a33909 100644
--- a/java/jakarta/el/ELManager.java
+++ b/java/jakarta/el/ELManager.java
@@ -20,16 +20,38 @@ import java.lang.reflect.Method;
 import java.util.Map;
 
 /**
+ * Provides a simplified API for managing EL context, resolvers, functions, and variables. This class maintains a
+ * {@link StandardELContext} and provides convenience methods for adding resolvers, mapping functions, setting
+ * variables, and managing imports. It is used internally by {@link ELProcessor}.
+ *
  * @since EL 3.0
  */
 public class ELManager {
 
     private StandardELContext context = null;
 
+    /**
+     * Constructs an ELManager with a lazily initialized {@link StandardELContext}.
+     */
+    public ELManager() {
+    }
+
+    /**
+     * Returns the {@link ExpressionFactory} used to create and evaluate EL expressions.
+     * The factory is obtained through the standard service discovery mechanism.
+     *
+     * @return the ExpressionFactory instance
+     */
     public static ExpressionFactory getExpressionFactory() {
         return Util.getExpressionFactory();
     }
 
+    /**
+     * Returns the {@link StandardELContext} managed by this ELManager, creating it on first access
+     * if it does not already exist.
+     *
+     * @return the StandardELContext instance
+     */
     public StandardELContext getELContext() {
         if (context == null) {
             context = new StandardELContext(getExpressionFactory());
@@ -38,40 +60,110 @@ public class ELManager {
         return context;
     }
 
+    /**
+     * Replaces the current EL context with a new {@link StandardELContext} initialized from the
+     * given context. The new context copies the ELResolver chain, FunctionMapper, VariableMapper,
+     * and other settings from the provided context.
+     *
+     * @param context the ELContext from which to initialize the new context
+     *
+     * @return the previous StandardELContext, or {@code null} if none existed
+     */
     public ELContext setELContext(ELContext context) {
         StandardELContext oldContext = this.context;
         this.context = new StandardELContext(context);
         return oldContext;
     }
 
+    /**
+     * Adds a {@link BeanNameELResolver} to the resolver chain that uses the given
+     * {@link BeanNameResolver} to resolve top-level identifiers to managed beans.
+     *
+     * @param beanNameResolver the resolver for bean names
+     */
     public void addBeanNameResolver(BeanNameResolver beanNameResolver) {
         getELContext().addELResolver(new BeanNameELResolver(beanNameResolver));
     }
 
+    /**
+     * Adds an {@link ELResolver} to the front of the resolver chain in the managed EL context.
+     * Resolvers added first have higher priority during property resolution.
+     *
+     * @param resolver the ELResolver to add
+     */
     public void addELResolver(ELResolver resolver) {
         getELContext().addELResolver(resolver);
     }
 
+    /**
+     * Maps a static method to an EL function name with the given prefix and local name.
+     * The function can then be invoked in EL expressions as {@code prefix:function(args)}.
+     *
+     * @param prefix   the namespace prefix for the function
+     * @param function the local function name
+     * @param method   the static {@link java.lang.reflect.Method} to map
+     */
     public void mapFunction(String prefix, String function, Method method) {
         getELContext().getFunctionMapper().mapFunction(prefix, function, method);
     }
 
+    /**
+     * Registers a variable in the EL context's variable mapper. The variable can then be
+     * referenced by name in EL expressions. Passing a {@code null} expression removes
+     * the variable.
+     *
+     * @param variable   the variable name
+     * @param expression the ValueExpression associated with the variable, or {@code null} to remove
+     */
     public void setVariable(String variable, ValueExpression expression) {
         getELContext().getVariableMapper().setVariable(variable, expression);
     }
 
+    /**
+     * Imports a static field or method so it can be referenced by its simple name in EL
+     * expressions. The argument must be a fully qualified name in the form
+     * {@code className.staticMemberName}.
+     *
+     * @param staticMemberName the fully qualified name of the static member to import
+     *
+     * @throws ELException if the static member cannot be found or is ambiguous
+     */
     public void importStatic(String staticMemberName) throws ELException {
         getELContext().getImportHandler().importStatic(staticMemberName);
     }
 
+    /**
+     * Imports a class so it can be referenced by its simple name in EL expressions.
+     * The argument must be a fully qualified class name.
+     *
+     * @param className the fully qualified class name to import
+     *
+     * @throws ELException if the class name is invalid or conflicts with an existing import
+     */
     public void importClass(String className) throws ELException {
         getELContext().getImportHandler().importClass(className);
     }
 
+    /**
+     * Imports all classes from a package so they can be referenced by their simple names
+     * in EL expressions.
+     *
+     * @param packageName the package name to import
+     */
     public void importPackage(String packageName) {
         getELContext().getImportHandler().importPackage(packageName);
     }
 
+    /**
+     * Defines or removes a bean accessible by name in EL expressions. When a non-null bean
+     * is provided, it is stored under the given name. When {@code null} is provided, the
+     * bean with the given name is removed.
+     *
+     * @param name  the bean name
+     * @param bean  the bean object to define, or {@code null} to remove the bean
+     *
+     * @return the previous bean associated with the name, or {@code null} if there was none
+     */
     public Object defineBean(String name, Object bean) {
         Map<String,Object> localBeans = getELContext().getLocalBeans();
 
@@ -82,6 +174,12 @@ public class ELManager {
         }
     }
 
+    /**
+     * Registers an {@link EvaluationListener} with the managed EL context. The listener
+     * will be notified before and after expression evaluation, and when properties are resolved.
+     *
+     * @param listener the EvaluationListener to register
+     */
     public void addEvaluationListener(EvaluationListener listener) {
         getELContext().addEvaluationListener(listener);
     }
diff --git a/java/jakarta/el/ELProcessor.java b/java/jakarta/el/ELProcessor.java
index d3f10f17b9..0b3795116e 100644
--- a/java/jakarta/el/ELProcessor.java
+++ b/java/jakarta/el/ELProcessor.java
@@ -22,6 +22,10 @@ import java.util.HashSet;
 import java.util.Set;
 
 /**
+ * Provides a simple API for evaluating EL expressions in a standalone environment. This class wraps an
+ * {@link ELManager} and provides methods for evaluating expressions, defining beans and functions, and managing
+ * variables. It is the primary entry point for applications that use the EL API outside of a Jakarta EE container.
+ *
  * @since EL 3.0
  */
 public class ELProcessor {
@@ -44,31 +48,82 @@ public class ELProcessor {
     private final ELContext context = manager.getELContext();
     private final ExpressionFactory factory = ELManager.getExpressionFactory();
 
+    /**
+     * Constructs an ELProcessor with a default {@link ELManager} and {@link StandardELContext}.
+     * The processor is ready to evaluate expressions immediately after construction.
+     */
+    public ELProcessor() {
+    }
 
+    /**
+     * Returns the {@link ELManager} that manages the EL context, resolvers, functions, and
+     * variables for this processor.
+     *
+     * @return the ELManager instance
+     */
     public ELManager getELManager() {
         return manager;
     }
 
-
+    /**
+     * Evaluates the given EL expression and returns the result as the requested type.
+     * The expression is automatically wrapped in {@literal ${}} delimiters before evaluation.
+     *
+     * @param <T>        the expected result type
+     * @param expression the EL expression to evaluate
+     *
+     * @return the result of evaluating the expression, coerced to the requested type
+     *
+     * @throws ELException if the expression cannot be evaluated
+     */
     public <T> T eval(String expression) {
         @SuppressWarnings("unchecked")
         T result = (T) getValue(expression, Object.class);
         return result;
     }
 
-
+    /**
+     * Evaluates the given EL expression and returns the result coerced to the expected type.
+     * The expression is automatically wrapped in {@literal ${}} delimiters before evaluation.
+     *
+     * @param <T>            the expected result type
+     * @param expression     the EL expression to evaluate
+     * @param expectedType   the class of the expected result type
+     *
+     * @return the result of evaluating the expression, coerced to the expected type
+     *
+     * @throws ELException if the expression cannot be evaluated
+     */
     public <T> T getValue(String expression, Class<T> expectedType) {
         ValueExpression ve = factory.createValueExpression(context, bracket(expression), expectedType);
         return ve.getValue(context);
     }
 
-
+    /**
+     * Evaluates the given EL expression and sets the result to the specified value.
+     * This is used for EL assignment expressions. The expression is automatically wrapped
+     * in {@literal ${}} delimiters before evaluation.
+     *
+     * @param expression the EL expression to evaluate
+     * @param value      the value to assign
+     *
+     * @throws ELException if the expression cannot be evaluated or the target is not writable
+     */
     public void setValue(String expression, Object value) {
         ValueExpression ve = factory.createValueExpression(context, bracket(expression), Object.class);
         ve.setValue(context, value);
     }
 
-
+    /**
+     * Registers a variable in the EL context. The variable is associated with the result
+     * of evaluating the given expression. Passing a {@code null} expression removes the
+     * variable from the context.
+     *
+     * @param variable   the variable name
+     * @param expression the EL expression to associate with the variable, or {@code null} to remove
+     *
+     * @throws ELException if the expression cannot be evaluated
+     */
     public void setVariable(String variable, String expression) {
         if (expression == null) {
             manager.setVariable(variable, null);
@@ -78,7 +133,20 @@ public class ELProcessor {
         }
     }
 
-
+    /**
+     * Registers a function in the EL context by looking up the static method in the given class.
+     * The method name may include a return type and parameter signature in the format
+     * {@code returnType methodName(paramTypes)}. The function is then callable in EL expressions
+     * as {@code prefix:function(args)}.
+     *
+     * @param prefix     the namespace prefix for the function
+     * @param function   the local function name, or empty to use the method name
+     * @param className  the fully qualified name of the class containing the static method
+     * @param methodName the method name, optionally with return type and parameter signature
+     *
+     * @throws ClassNotFoundException  if the class cannot be found or is not public
+     * @throws NoSuchMethodException   if the method cannot be found or is not a public static method
+     */
     public void defineFunction(String prefix, String function, String className, String methodName)
             throws ClassNotFoundException, NoSuchMethodException {
 
@@ -188,6 +256,14 @@ public class ELProcessor {
     }
 
 
+    /**
+     * Defines or removes a bean accessible by name in EL expressions. When a non-null bean
+     * is provided, it is stored under the given name. When {@code null} is provided, the
+     * bean with the given name is removed.
+     *
+     * @param name the bean name
+     * @param bean the bean object to define, or {@code null} to remove the bean
+     */
     public void defineBean(String name, Object bean) {
         manager.defineBean(name, bean);
     }
diff --git a/java/jakarta/el/ELResolver.java b/java/jakarta/el/ELResolver.java
index e7dad5afcd..deaef98f2a 100644
--- a/java/jakarta/el/ELResolver.java
+++ b/java/jakarta/el/ELResolver.java
@@ -16,8 +16,25 @@
  */
 package jakarta.el;
 
+/**
+ * Base class for resolvers that resolve property references during EL expression evaluation.
+ * An ELResolver is responsible for resolving a property on a base object, determining its type,
+ * setting its value, and reporting whether it is read-only. Resolvers are chained together in
+ * an {@link ELContext}, and each resolver in the chain attempts to resolve the property until
+ * one succeeds. Implementations include {@link ListELResolver}, {@link MapELResolver}, and
+ * custom resolvers for application-specific object models.
+ *
+ * @since EL 2.1
+ */
 public abstract class ELResolver {
 
+    /**
+     * Constructs an ELResolver. Subclasses should invoke this constructor to initialize
+     * the base resolver state.
+     */
+    public ELResolver() {
+    }
+
     /**
      * Obtain the value of the given property on the given object using the given context.
      *
diff --git a/java/jakarta/el/EvaluationListener.java b/java/jakarta/el/EvaluationListener.java
index 68c30985e0..836fac9e75 100644
--- a/java/jakarta/el/EvaluationListener.java
+++ b/java/jakarta/el/EvaluationListener.java
@@ -17,10 +17,20 @@
 package jakarta.el;
 
 /**
+ * Listener interface for monitoring EL expression evaluation events. Implementations can track when expressions are
+ * evaluated and when properties are resolved during evaluation. Register an instance with an {@link ELContext} using
+ * {@link ELContext#addEvaluationListener(EvaluationListener)}.
+ *
  * @since EL 3.0
  */
 public abstract class EvaluationListener {
 
+    /**
+     * Constructs an EvaluationListener.
+     */
+    public EvaluationListener() {
+    }
+
     /**
      * Fired before the evaluation of the expression.
      *
diff --git a/java/jakarta/el/Expression.java b/java/jakarta/el/Expression.java
index 9c833768d4..b241e37415 100644
--- a/java/jakarta/el/Expression.java
+++ b/java/jakarta/el/Expression.java
@@ -20,13 +20,26 @@ import java.io.Serial;
 import java.io.Serializable;
 
 /**
- *
+ * Base class for EL expression objects. An Expression represents a compiled EL expression that can be evaluated.
+ * Subclasses include {@link ValueExpression} and {@link MethodExpression}.
  */
 public abstract class Expression implements Serializable {
 
     @Serial
     private static final long serialVersionUID = -6663767980471823812L;
 
+    /**
+     * Constructs an Expression. Subclasses should invoke this constructor to initialize
+     * the base expression state.
+     */
+    public Expression() {
+    }
+
+    /**
+     * Returns the original string representation of this EL expression as it was parsed.
+     *
+     * @return the string representation of this expression
+     */
     public abstract String getExpressionString();
 
     @Override
@@ -35,6 +48,12 @@ public abstract class Expression implements Serializable {
     @Override
     public abstract int hashCode();
 
+    /**
+     * Returns whether this expression is a literal text expression, meaning it does not
+     * contain any variables, functions, or operators and evaluates to a constant value.
+     *
+     * @return {@code true} if this expression is a literal text, {@code false} otherwise
+     */
     public abstract boolean isLiteralText();
 
 }
diff --git a/java/jakarta/el/ExpressionFactory.java b/java/jakarta/el/ExpressionFactory.java
index bda510cea1..e327f7338b 100644
--- a/java/jakarta/el/ExpressionFactory.java
+++ b/java/jakarta/el/ExpressionFactory.java
@@ -35,10 +35,21 @@ import java.util.concurrent.locks.ReadWriteLock;
 import java.util.concurrent.locks.ReentrantReadWriteLock;
 
 /**
- * @since 2.1
+ * Factory for creating {@link ValueExpression} and {@link MethodExpression} instances, and for coercing objects to
+ * specific types. Implementations parse and compile EL expressions. Use {@link #newInstance()} to obtain an instance
+ * using the standard discovery mechanism.
+ *
+ * @since EL 2.1
  */
 public abstract class ExpressionFactory {
 
+    /**
+     * Constructs an ExpressionFactory. Subclasses should invoke this constructor to initialize
+     * the base factory state.
+     */
+    public ExpressionFactory() {
+    }
+
     private static final String PROPERTY_NAME = "jakarta.el.ExpressionFactory";
 
     private static final String PROPERTY_FILE =
@@ -170,6 +181,16 @@ public abstract class ExpressionFactory {
      */
     public abstract ValueExpression createValueExpression(ELContext context, String expression, Class<?> expectedType);
 
+    /**
+     * Creates a {@link ValueExpression} that, when evaluated, returns the given instance
+     * of the specified type. This is a convenience method for creating a constant value
+     * expression without requiring an {@link ELContext}.
+     *
+     * @param instance     the constant value to wrap
+     * @param expectedType the expected type of the value
+     *
+     * @return a ValueExpression that returns the given instance when evaluated
+     */
     public abstract ValueExpression createValueExpression(Object instance, Class<?> expectedType);
 
     /**
@@ -202,7 +223,11 @@ public abstract class ExpressionFactory {
     public abstract <T> T coerceToType(Object obj, Class<T> expectedType);
 
     /**
-     * @return This default implementation returns null
+     * Returns an {@link ELResolver} capable of resolving properties on {@link java.io.InputStream}
+     * objects, enabling EL expressions to operate on stream types. This allows expressions to
+     * read data from input streams using standard property navigation syntax.
+     *
+     * @return the StreamELResolver, or {@code null} if not supported by this implementation
      *
      * @since EL 3.0
      */
@@ -211,7 +236,11 @@ public abstract class ExpressionFactory {
     }
 
     /**
-     * @return This default implementation returns null
+     * Returns a map of function names to {@link java.lang.reflect.Method} objects representing
+     * the standard EL functions that are available by default without explicit registration.
+     * Implementations can override this method to provide a set of built-in functions.
+     *
+     * @return a map of function names to methods, or {@code null} if no default functions are provided
      *
      * @since EL 3.0
      */
diff --git a/java/jakarta/el/FunctionMapper.java b/java/jakarta/el/FunctionMapper.java
index 036f12b7d2..fc3fc7c92a 100644
--- a/java/jakarta/el/FunctionMapper.java
+++ b/java/jakarta/el/FunctionMapper.java
@@ -18,8 +18,32 @@ package jakarta.el;
 
 import java.lang.reflect.Method;
 
+/**
+ * Abstract base class for mapping EL function names to Java {@link java.lang.reflect.Method}
+ * objects. During expression evaluation, the EL implementation uses the FunctionMapper to
+ * resolve function references of the form {@code prefix:functionName} to the corresponding
+ * static Java methods. Implementations maintain a registry of function prefixes and names
+ * mapped to their underlying methods.
+ *
+ * @since EL 2.1
+ */
 public abstract class FunctionMapper {
 
+    /**
+     * Constructs a FunctionMapper. Subclasses should invoke this constructor to initialize
+     * the base mapper state.
+     */
+    public FunctionMapper() {
+    }
+
+    /**
+     * Resolves a function reference to its corresponding static {@link java.lang.reflect.Method}.
+     *
+     * @param prefix    the namespace prefix of the function
+     * @param localName the local name of the function
+     *
+     * @return the {@link Method} object for the resolved function, or {@code null} if not found
+     */
     public abstract Method resolveFunction(String prefix, String localName);
 
     /**
diff --git a/java/jakarta/el/ImportHandler.java b/java/jakarta/el/ImportHandler.java
index 2b0725b71e..5885f25730 100644
--- a/java/jakarta/el/ImportHandler.java
+++ b/java/jakarta/el/ImportHandler.java
@@ -28,6 +28,10 @@ import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
+ * Manages class and package imports for EL expressions, similar to Java import statements. The ImportHandler resolves
+ * unqualified class names to their fully qualified counterparts, supports static imports, and maintains a set of
+ * standard packages that are automatically available in EL expressions.
+ *
  * @since EL 3.0
  */
 public class ImportHandler {
@@ -289,11 +293,24 @@ public class ImportHandler {
     private final Map<String,Class<?>> statics = new ConcurrentHashMap<>();
 
 
+    /**
+     * Constructs an ImportHandler with the {@code java.lang} package pre-imported.
+     * The {@code java.lang} package is automatically available in all EL expressions.
+     */
     public ImportHandler() {
         importPackage("java.lang");
     }
 
-
+    /**
+     * Imports a static field or method so it can be referenced by its simple name in EL
+     * expressions. The argument must be a fully qualified name in the form
+     * {@code className.staticMemberName}. The static member must be public.
+     *
+     * @param name the fully qualified name of the static member to import
+     *
+     * @throws ELException if the name is invalid, the class cannot be found, the static
+     *                       member does not exist, or the import would be ambiguous
+     */
     public void importStatic(String name) throws ELException {
         int lastPeriod = name.lastIndexOf('.');
 
@@ -349,6 +366,15 @@ public class ImportHandler {
     }
 
 
+    /**
+     * Imports a class so it can be referenced by its simple name in EL expressions.
+     * The argument must be a fully qualified class name. If the simple name conflicts
+     * with a previously imported class, an exception is thrown.
+     *
+     * @param name the fully qualified class name to import
+     *
+     * @throws ELException if the class name is invalid or conflicts with an existing import
+     */
     public void importClass(String name) throws ELException {
         int lastPeriodIndex = name.lastIndexOf('.');
 
@@ -366,6 +392,14 @@ public class ImportHandler {
     }
 
 
+    /**
+     * Imports all classes from a package so they can be referenced by their simple names
+     * in EL expressions. Classes from the imported package are resolved during expression
+     * evaluation. If a simple name is ambiguous across multiple imported packages, an
+     * {@link ELException} is thrown at resolution time.
+     *
+     * @param name the package name to import
+     */
     public void importPackage(String name) {
         // Import ambiguity is handled at resolution, not at import
         // Whether the package exists is not checked,
@@ -377,6 +411,18 @@ public class ImportHandler {
     }
 
 
+    /**
+     * Resolves an unqualified class name to a {@link Class} object by searching the
+     * registered class imports and package imports. The name must not contain a dot.
+     * Results are cached for performance. If the name is ambiguous across multiple
+     * packages, an {@link ELException} is thrown.
+     *
+     * @param name the unqualified class name to resolve
+     *
+     * @return the resolved {@link Class}, or {@code null} if the class cannot be found
+     *
+     * @throws ELException if the class name is ambiguous across imported packages
+     */
     public Class<?> resolveClass(String name) {
         if (name == null || name.contains(".")) {
             return null;
@@ -445,6 +491,15 @@ public class ImportHandler {
     }
 
 
+    /**
+     * Resolves a statically imported member name to the {@link Class} that declares it.
+     * The name is the simple name of the static field or method as registered by
+     * {@link #importStatic(String)}.
+     *
+     * @param name the simple name of the static member
+     *
+     * @return the declaring {@link Class}, or {@code null} if not found
+     */
     public Class<?> resolveStatic(String name) {
         return statics.get(name);
     }
diff --git a/java/jakarta/el/LambdaExpression.java b/java/jakarta/el/LambdaExpression.java
index fe7d9ca233..757a47cf24 100644
--- a/java/jakarta/el/LambdaExpression.java
+++ b/java/jakarta/el/LambdaExpression.java
@@ -21,6 +21,14 @@ import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 
+/**
+ * Represents a lambda expression in EL. A lambda expression has a list of formal parameters
+ * and a body expression. When invoked, the lambda binds the actual arguments to its formal
+ * parameters and evaluates the body expression within a scoped {@link ELContext}. Lambda
+ * expressions support nesting, with inner lambdas having access to outer lambda arguments.
+ *
+ * @since EL 3.0
+ */
 public class LambdaExpression {
 
     private final List<String> formalParameters;
@@ -28,16 +36,42 @@ public class LambdaExpression {
     private final Map<String,Object> nestedArguments = new HashMap<>();
     private ELContext context = null;
 
+    /**
+     * Constructs a LambdaExpression with the given formal parameters and body expression.
+     *
+     * @param formalParameters the list of formal parameter names for the lambda
+     * @param expression       the body expression to evaluate when the lambda is invoked
+     */
     public LambdaExpression(List<String> formalParameters, ValueExpression expression) {
         this.formalParameters = formalParameters;
         this.expression = expression;
 
     }
 
+    /**
+     * Sets the {@link ELContext} to be used when this lambda is invoked without an explicit
+     * context argument. This is called automatically when the lambda is coerced to a
+     * functional interface type.
+     *
+     * @param context the ELContext to use for evaluation
+     */
     public void setELContext(ELContext context) {
         this.context = context;
     }
 
+    /**
+     * Invokes the lambda expression with the given arguments in the specified EL context.
+     * The formal parameters are bound to the corresponding arguments, and the body
+     * expression is evaluated within a lambda scope. If the result is another lambda,
+     * the current arguments are made available to the nested lambda.
+     *
+     * @param context the ELContext in which to evaluate the lambda
+     * @param args    the actual arguments to bind to the formal parameters
+     *
+     * @return the result of evaluating the lambda body expression
+     *
+     * @throws ELException if the number of arguments is less than the number of formal parameters
+     */
     @SuppressWarnings("null") // args[i] can't be null due to earlier checks
     public Object invoke(ELContext context, Object... args) throws ELException {
 
@@ -81,6 +115,17 @@ public class LambdaExpression {
         }
     }
 
+    /**
+     * Invokes the lambda expression with the given arguments using the EL context set by
+     * {@link #setELContext(ELContext)}. This is a convenience method for use when the
+     * lambda has been assigned to a functional interface variable.
+     *
+     * @param args the actual arguments to bind to the formal parameters
+     *
+     * @return the result of evaluating the lambda body expression
+     *
+     * @throws ELException if the number of arguments is less than the number of formal parameters
+     */
     public Object invoke(Object... args) {
         return invoke(context, args);
     }
diff --git a/java/jakarta/el/ListELResolver.java b/java/jakarta/el/ListELResolver.java
index 13c73e16f6..34b0b15267 100644
--- a/java/jakarta/el/ListELResolver.java
+++ b/java/jakarta/el/ListELResolver.java
@@ -21,6 +21,14 @@ import java.util.Collections;
 import java.util.List;
 import java.util.Objects;
 
+/**
+ * An {@link ELResolver} that resolves properties on {@link java.util.List} objects using
+ * integer indices. When the base object is a {@code List}, the property is coerced to an
+ * integer and used as the list index. This resolver supports read and write operations,
+ * and can be configured as read-only to prevent modification of list elements.
+ *
+ * @since EL 2.1
+ */
 public class ListELResolver extends ELResolver {
 
     private final boolean readOnly;
@@ -29,10 +37,20 @@ public class ListELResolver extends ELResolver {
     // classes. Java 9 + so a back-port would require JreCompat.
     private static final Class<?> UNMODIFIABLE = Collections.unmodifiableList(new ArrayList<>()).getClass();
 
+    /**
+     * Constructs a ListELResolver that allows both read and write operations on lists.
+     */
     public ListELResolver() {
         this.readOnly = false;
     }
 
+    /**
+     * Constructs a ListELResolver with the specified read-only setting. When read-only
+     * is {@code true}, attempts to set values on list elements will throw a
+     * {@link PropertyNotWritableException}.
+     *
+     * @param readOnly {@code true} if this resolver should be read-only, {@code false} otherwise
+     */
     public ListELResolver(boolean readOnly) {
         this.readOnly = readOnly;
     }
diff --git a/java/jakarta/el/MapELResolver.java b/java/jakarta/el/MapELResolver.java
index 973d2ee35d..32272a8916 100644
--- a/java/jakarta/el/MapELResolver.java
+++ b/java/jakarta/el/MapELResolver.java
@@ -21,16 +21,34 @@ import java.util.HashMap;
 import java.util.Map;
 import java.util.Objects;
 
+/**
+ * An {@link ELResolver} that resolves properties on {@link java.util.Map} objects using
+ * the property as a map key. When the base object is a {@code Map}, the property is used
+ * directly as the key to look up or set values. This resolver supports read and write
+ * operations, and can be configured as read-only to prevent modification of map entries.
+ *
+ * @since EL 2.1
+ */
 public class MapELResolver extends ELResolver {
 
     private static final Class<?> UNMODIFIABLE = Collections.unmodifiableMap(new HashMap<>()).getClass();
 
     private final boolean readOnly;
 
+    /**
+     * Constructs a MapELResolver that allows both read and write operations on maps.
+     */
     public MapELResolver() {
         this.readOnly = false;
     }
 
+    /**
+     * Constructs a MapELResolver with the specified read-only setting. When read-only
+     * is {@code true}, attempts to set values on map entries will throw a
+     * {@link PropertyNotWritableException}.
+     *
+     * @param readOnly {@code true} if this resolver should be read-only, {@code false} otherwise
+     */
     public MapELResolver(boolean readOnly) {
         this.readOnly = readOnly;
     }
diff --git a/java/jakarta/el/MethodExpression.java b/java/jakarta/el/MethodExpression.java
index 715cf43bb9..876619b07f 100644
--- a/java/jakarta/el/MethodExpression.java
+++ b/java/jakarta/el/MethodExpression.java
@@ -18,12 +18,24 @@ package jakarta.el;
 
 import java.io.Serial;
 
+/**
+ * Represents a compiled EL method expression. A MethodExpression is the result of compiling an EL expression
+ * that resolves to a method, and can be invoked at a later time with a given set of parameters.
+ */
 public abstract class MethodExpression extends Expression {
 
     @Serial
     private static final long serialVersionUID = 8163925562047324656L;
 
     /**
+     * Constructs a MethodExpression.
+     */
+    public MethodExpression() {
+    }
+
+    /**
+     * Returns information about the method that this expression resolves to.
+     *
      * @param context The EL context for this evaluation
      *
      * @return Information about the method that this expression resolves to
@@ -37,6 +49,8 @@ public abstract class MethodExpression extends Expression {
     public abstract MethodInfo getMethodInfo(ELContext context);
 
     /**
+     * Invokes the method that this expression resolves to with the given parameters.
+     *
      * @param context The EL context for this evaluation
      * @param params  The parameters with which to invoke this method expression
      *
@@ -52,6 +66,8 @@ public abstract class MethodExpression extends Expression {
     public abstract Object invoke(ELContext context, Object[] params);
 
     /**
+     * Returns whether the parameters for the method invocation are provided by the expression or by the container.
+     *
      * @return This default implementation always returns <code>false</code>
      *
      * @since EL 3.0
diff --git a/java/jakarta/el/MethodInfo.java b/java/jakarta/el/MethodInfo.java
index 3dbcfe75a1..034433d303 100644
--- a/java/jakarta/el/MethodInfo.java
+++ b/java/jakarta/el/MethodInfo.java
@@ -18,28 +18,57 @@ package jakarta.el;
 
 import java.util.Arrays;
 
+/**
+ * Holds metadata about a method that an EL method expression resolves to, including the method name,
+ * return type, and parameter types.
+ */
 public class MethodInfo {
 
+    /** The name of the method. */
     private final String name;
 
+    /** The parameter types of the method. */
     private final Class<?>[] paramTypes;
 
+    /** The return type of the method. */
     private final Class<?> returnType;
 
+    /**
+     * Constructs a MethodInfo with the given name, return type, and parameter types.
+     *
+     * @param name       The name of the method
+     * @param returnType The return type of the method
+     * @param paramTypes The parameter types of the method
+     */
     public MethodInfo(String name, Class<?> returnType, Class<?>[] paramTypes) {
         this.name = name;
         this.returnType = returnType;
         this.paramTypes = paramTypes;
     }
 
+    /**
+     * Returns the name of the method.
+     *
+     * @return the method name
+     */
     public String getName() {
         return this.name;
     }
 
+    /**
+     * Returns the return type of the method.
+     *
+     * @return the return type
+     */
     public Class<?> getReturnType() {
         return this.returnType;
     }
 
+    /**
+     * Returns the parameter types of the method.
+     *
+     * @return the parameter types
+     */
     public Class<?>[] getParamTypes() {
         return this.paramTypes;
     }
diff --git a/java/jakarta/el/MethodNotFoundException.java b/java/jakarta/el/MethodNotFoundException.java
index 8a92baf0f3..7232656c97 100644
--- a/java/jakarta/el/MethodNotFoundException.java
+++ b/java/jakarta/el/MethodNotFoundException.java
@@ -18,23 +18,45 @@ package jakarta.el;
 
 import java.io.Serial;
 
+/**
+ * Thrown when a method referenced in an EL expression cannot be found on the target object.
+ */
 public class MethodNotFoundException extends ELException {
 
     @Serial
     private static final long serialVersionUID = -3631968116081480328L;
 
+    /**
+     * Constructs a MethodNotFoundException with no detail message.
+     */
     public MethodNotFoundException() {
         super();
     }
 
+    /**
+     * Constructs a MethodNotFoundException with the specified detail message.
+     *
+     * @param message the detail message
+     */
     public MethodNotFoundException(String message) {
         super(message);
     }
 
+    /**
+     * Constructs a MethodNotFoundException with the specified cause.
+     *
+     * @param cause the cause of this exception
+     */
     public MethodNotFoundException(Throwable cause) {
         super(cause);
     }
 
+    /**
+     * Constructs a MethodNotFoundException with the specified detail message and cause.
+     *
+     * @param message the detail message
+     * @param cause   the cause of this exception
+     */
     public MethodNotFoundException(String message, Throwable cause) {
         super(message, cause);
     }
diff --git a/java/jakarta/el/MethodReference.java b/java/jakarta/el/MethodReference.java
index 6f86ffcbea..86b008faac 100644
--- a/java/jakarta/el/MethodReference.java
+++ b/java/jakarta/el/MethodReference.java
@@ -26,12 +26,24 @@ import java.util.Arrays;
  */
 public class MethodReference {
 
+    /** The base object on which the method will be invoked. */
     private final Object base;
+    /** The method information. */
     private final MethodInfo methodInfo;
+    /** The annotations on the method. */
     private final Annotation[] annotations;
+    /** The evaluated parameter values for the method invocation. */
     private final Object[] evaluatedParameters;
 
 
+    /**
+     * Constructs a MethodReference with the given base object, method info, annotations, and evaluated parameters.
+     *
+     * @param base                 The base object on which the method will be invoked
+     * @param methodInfo           Information about the method
+     * @param annotations          The annotations on the method
+     * @param evaluatedParameters  The evaluated parameter values for the method invocation
+     */
     public MethodReference(Object base, MethodInfo methodInfo, Annotation[] annotations, Object[] evaluatedParameters) {
         this.base = base;
         this.methodInfo = methodInfo;
diff --git a/java/jakarta/el/OptionalELResolver.java b/java/jakarta/el/OptionalELResolver.java
index 9600e1abca..4b59e62d37 100644
--- a/java/jakarta/el/OptionalELResolver.java
+++ b/java/jakarta/el/OptionalELResolver.java
@@ -30,6 +30,12 @@ import java.util.Optional;
  */
 public class OptionalELResolver extends ELResolver {
 
+    /**
+     * Constructs an OptionalELResolver.
+     */
+    public OptionalELResolver() {
+    }
+
     /**
      * {@inheritDoc}
      *
diff --git a/java/jakarta/el/PropertyNotFoundException.java b/java/jakarta/el/PropertyNotFoundException.java
index 45aff2e48b..7f8aa90598 100644
--- a/java/jakarta/el/PropertyNotFoundException.java
+++ b/java/jakarta/el/PropertyNotFoundException.java
@@ -18,23 +18,50 @@ package jakarta.el;
 
 import java.io.Serial;
 
+/**
+ * Exception thrown when a property is not found during EL evaluation.
+ * <p>
+ * This exception is raised when an expression attempts to access a property
+ * that does not exist on the target object.
+ *
+ * @since EL 2.1
+ */
 public class PropertyNotFoundException extends ELException {
 
     @Serial
     private static final long serialVersionUID = -3799200961303506745L;
 
+    /**
+     * Constructs a new instance with no detail message or cause.
+     */
     public PropertyNotFoundException() {
         super();
     }
 
+    /**
+     * Constructs a new instance with the specified detail message and no cause.
+     *
+     * @param message the detail message
+     */
     public PropertyNotFoundException(String message) {
         super(message);
     }
 
+    /**
+     * Constructs a new instance with the specified cause and no detail message.
+     *
+     * @param cause the underlying cause
+     */
     public PropertyNotFoundException(Throwable cause) {
         super(cause);
     }
 
+    /**
+     * Constructs a new instance with the specified detail message and cause.
+     *
+     * @param message the detail message
+     * @param cause   the underlying cause
+     */
     public PropertyNotFoundException(String message, Throwable cause) {
         super(message, cause);
     }
diff --git a/java/jakarta/el/PropertyNotWritableException.java b/java/jakarta/el/PropertyNotWritableException.java
index 58f28e9c34..14b53ba4ca 100644
--- a/java/jakarta/el/PropertyNotWritableException.java
+++ b/java/jakarta/el/PropertyNotWritableException.java
@@ -18,23 +18,50 @@ package jakarta.el;
 
 import java.io.Serial;
 
+/**
+ * Exception thrown when an EL expression attempts to write to a read-only property.
+ * <p>
+ * This exception is raised during setValue operations when the target property
+ * exists but cannot be modified.
+ *
+ * @since EL 2.1
+ */
 public class PropertyNotWritableException extends ELException {
 
     @Serial
     private static final long serialVersionUID = 827987155471214717L;
 
+    /**
+     * Constructs a new instance with no detail message or cause.
+     */
     public PropertyNotWritableException() {
         super();
     }
 
+    /**
+     * Constructs a new instance with the specified detail message and no cause.
+     *
+     * @param message the detail message
+     */
     public PropertyNotWritableException(String message) {
         super(message);
     }
 
+    /**
+     * Constructs a new instance with the specified cause and no detail message.
+     *
+     * @param cause the underlying cause
+     */
     public PropertyNotWritableException(Throwable cause) {
         super(cause);
     }
 
+    /**
+     * Constructs a new instance with the specified detail message and cause.
+     *
+     * @param message the detail message
+     * @param cause   the underlying cause
+     */
     public PropertyNotWritableException(String message, Throwable cause) {
         super(message, cause);
     }
diff --git a/java/jakarta/el/RecordELResolver.java b/java/jakarta/el/RecordELResolver.java
index 37c0cc64a3..01b4dc6792 100644
--- a/java/jakarta/el/RecordELResolver.java
+++ b/java/jakarta/el/RecordELResolver.java
@@ -35,6 +35,13 @@ import java.util.Objects;
  */
 public class RecordELResolver extends ELResolver {
 
+    /**
+     * Constructs a new instance of the resolver.
+     */
+    public RecordELResolver() {
+        super();
+    }
+
     /**
      * If the base object is an instance of {@link Record}, returns the value of the given field of this {@link Record}.
      * <p>
diff --git a/java/jakarta/el/ResourceBundleELResolver.java b/java/jakarta/el/ResourceBundleELResolver.java
index 62e9fd6729..2ae2ae054e 100644
--- a/java/jakarta/el/ResourceBundleELResolver.java
+++ b/java/jakarta/el/ResourceBundleELResolver.java
@@ -20,8 +20,26 @@ import java.util.MissingResourceException;
 import java.util.Objects;
 import java.util.ResourceBundle;
 
+/**
+ * EL resolver for resource bundle properties.
+ * <p>
+ * This resolver handles base objects of type {@link ResourceBundle}. It accepts
+ * any non-null object as a property, coerces it to a String, and uses it to
+ * look up the corresponding message in the resource bundle. If the key is not
+ * found, the resolver returns a placeholder string of the form {@code ???key???}.
+ * Resource bundles are always read-only.
+ * <p>
+ * {@code ELResolver}s are combined using {@link CompositeELResolver}s to define
+ * rich semantics for evaluating an expression. See the javadocs for
+ * {@link ELResolver} for details.
+ *
+ * @since EL 2.1
+ */
 public class ResourceBundleELResolver extends ELResolver {
 
+    /**
+     * Constructs a new instance of the resolver.
+     */
     public ResourceBundleELResolver() {
         super();
     }
diff --git a/java/jakarta/el/StandardELContext.java b/java/jakarta/el/StandardELContext.java
index 17c5f44b3d..ce2ed86605 100644
--- a/java/jakarta/el/StandardELContext.java
+++ b/java/jakarta/el/StandardELContext.java
@@ -21,6 +21,10 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
+ * Standard implementation of {@link ELContext} that provides a complete EL resolution environment. It maintains a
+ * composite resolver chain, variable mapper, function mapper, and supports custom resolvers and local beans. This is
+ * the default context implementation used by {@link ELProcessor}.
+ *
  * @since EL 3.0
  */
 public class StandardELContext extends ELContext {
@@ -33,6 +37,14 @@ public class StandardELContext extends ELContext {
     private final Map<String,Object> localBeans = new HashMap<>();
 
 
+    /**
+     * Constructs a new instance backed by the given expression factory.
+     * <p>
+     * Initializes the standard resolver chain with built-in resolvers and
+     * a function mapper populated from the factory's initial function map.
+     *
+     * @param factory the expression factory providing the initial resolver and function configuration
+     */
     public StandardELContext(ExpressionFactory factory) {
         wrappedContext = null;
         variableMapper = new StandardVariableMapper();
@@ -57,6 +69,14 @@ public class StandardELContext extends ELContext {
         standardResolver.add(new BeanELResolver());
     }
 
+    /**
+     * Constructs a new instance that wraps the given context.
+     * <p>
+     * The variable mapper, function mapper, and EL resolver from the wrapped
+     * context are used, with additional standard resolvers prepended.
+     *
+     * @param context the context to wrap
+     */
     public StandardELContext(ELContext context) {
         wrappedContext = context;
         variableMapper = context.getVariableMapper();
@@ -94,6 +114,15 @@ public class StandardELContext extends ELContext {
         return standardResolver;
     }
 
+    /**
+     * Adds a custom EL resolver to the resolver chain.
+     * <p>
+     * Custom resolvers are inserted after the bean name resolver and before
+     * the standard resolvers, allowing them to intercept resolution before
+     * the built-in resolvers are consulted.
+     *
+     * @param resolver the resolver to add
+     */
     public void addELResolver(ELResolver resolver) {
         customResolvers.add(resolver);
     }
diff --git a/java/jakarta/el/StaticFieldELResolver.java b/java/jakarta/el/StaticFieldELResolver.java
index c69e306005..d77e0c733a 100644
--- a/java/jakarta/el/StaticFieldELResolver.java
+++ b/java/jakarta/el/StaticFieldELResolver.java
@@ -24,10 +24,21 @@ import java.lang.reflect.Modifier;
 import java.util.Objects;
 
 /**
+ * ELResolver that resolves static fields and invokes static methods on classes. This resolver handles expressions
+ * where the base is an {@link ELClass} and the property is a {@link String} representing a field or method name.
+ * Static fields are read-only.
+ *
  * @since EL 3.0
  */
 public class StaticFieldELResolver extends ELResolver {
 
+    /**
+     * Constructs a new instance of the resolver.
+     */
+    public StaticFieldELResolver() {
+        super();
+    }
+
     @Override
     public Object getValue(ELContext context, Object base, Object property) {
         Objects.requireNonNull(context);
diff --git a/java/jakarta/el/TypeConverter.java b/java/jakarta/el/TypeConverter.java
index 532543d3da..acc2acf370 100644
--- a/java/jakarta/el/TypeConverter.java
+++ b/java/jakarta/el/TypeConverter.java
@@ -17,10 +17,21 @@
 package jakarta.el;
 
 /**
+ * Base class for ELResolvers that perform type conversion. A TypeConverter is an ELResolver that specializes in
+ * converting objects from one type to another via the {@link #convertToType} method. Standard property resolution
+ * methods return {@code null} or no-op, as this resolver is focused solely on type conversion.
+ *
  * @since EL 3.0
  */
 public abstract class TypeConverter extends ELResolver {
 
+    /**
+     * Constructs a new instance of the type converter.
+     */
+    public TypeConverter() {
+        super();
+    }
+
     @Override
     public Object getValue(ELContext context, Object base, Object property) {
         return null;
diff --git a/java/jakarta/el/ValueExpression.java b/java/jakarta/el/ValueExpression.java
index 892c96128c..2db42cdbca 100644
--- a/java/jakarta/el/ValueExpression.java
+++ b/java/jakarta/el/ValueExpression.java
@@ -18,12 +18,29 @@ package jakarta.el;
 
 import java.io.Serial;
 
+/**
+ * Represents a parsed EL expression that can be evaluated to produce a value.
+ * <p>
+ * A value expression is created by parsing an EL expression string and can be
+ * evaluated multiple times in different contexts. It supports reading values,
+ * writing values, and introspecting the expression's type and mutability.
+ *
+ * @since EL 2.1
+ */
 public abstract class ValueExpression extends Expression {
 
     @Serial
     private static final long serialVersionUID = 8577809572381654673L;
 
     /**
+     * Constructs a new value expression.
+     */
+    public ValueExpression() {
+    }
+
+    /**
+     * Evaluates this expression and returns the result.
+     *
      * @param <T>     The expected type for the result of evaluating this value expression
      * @param context The EL context for this evaluation
      *
@@ -37,6 +54,8 @@ public abstract class ValueExpression extends Expression {
     public abstract <T> T getValue(ELContext context);
 
     /**
+     * Sets the value of the property referenced by this expression.
+     *
      * @param context The EL context for this evaluation
      * @param value   The value to set the property to which this value expression refers
      *
@@ -49,6 +68,8 @@ public abstract class ValueExpression extends Expression {
     public abstract void setValue(ELContext context, Object value);
 
     /**
+     * Determines whether the property referenced by this expression is read-only.
+     *
      * @param context The EL context for this evaluation
      *
      * @return <code>true</code> if this expression is read only otherwise <code>false</code>
@@ -61,6 +82,8 @@ public abstract class ValueExpression extends Expression {
     public abstract boolean isReadOnly(ELContext context);
 
     /**
+     * Returns the type of the result produced by evaluating this expression.
+     *
      * @param context The EL context for this evaluation
      *
      * @return The type of the result of this value expression
@@ -72,9 +95,19 @@ public abstract class ValueExpression extends Expression {
      */
     public abstract Class<?> getType(ELContext context);
 
+    /**
+     * Returns the expected type of the result of this expression.
+     *
+     * @return The expected result type, or {@code Object.class} if no specific type is expected
+     */
     public abstract Class<?> getExpectedType();
 
     /**
+     * Returns a reference to the resolved property for this expression.
+     * <p>
+     * This default implementation always returns {@code null}. Subclasses should
+     * override this method to provide the resolved base object and property.
+     *
      * @param context The EL context for this evaluation
      *
      * @return This default implementation always returns <code>null</code>
diff --git a/java/jakarta/el/ValueReference.java b/java/jakarta/el/ValueReference.java
index b7b2cee9ed..53090d7288 100644
--- a/java/jakarta/el/ValueReference.java
+++ b/java/jakarta/el/ValueReference.java
@@ -20,6 +20,10 @@ import java.io.Serial;
 import java.io.Serializable;
 
 /**
+ * Holds a reference to a resolved property, consisting of a base object and a property identifier. This class is
+ * used to capture the result of property resolution during EL evaluation, allowing the caller to perform additional
+ * operations on the resolved property.
+ *
  * @since EL 2.2
  */
 public class ValueReference implements Serializable {
@@ -27,18 +31,37 @@ public class ValueReference implements Serializable {
     @Serial
     private static final long serialVersionUID = 1L;
 
+    /** The base object on which the property was resolved. */
     private final Object base;
+
+    /** The property identifier. */
     private final Object property;
 
+    /**
+     * Constructs a new value reference with the given base object and property.
+     *
+     * @param base     The base object on which the property was resolved
+     * @param property The property identifier
+     */
     public ValueReference(Object base, Object property) {
         this.base = base;
         this.property = property;
     }
 
+    /**
+     * Returns the base object on which the property was resolved.
+     *
+     * @return The base object
+     */
     public Object getBase() {
         return base;
     }
 
+    /**
+     * Returns the property identifier.
+     *
+     * @return The property identifier
+     */
     public Object getProperty() {
         return property;
     }
diff --git a/java/jakarta/el/VariableMapper.java b/java/jakarta/el/VariableMapper.java
index 79018e0f0d..8d41c6b7e5 100644
--- a/java/jakarta/el/VariableMapper.java
+++ b/java/jakarta/el/VariableMapper.java
@@ -17,11 +17,34 @@
 package jakarta.el;
 
 /**
- *
+ * Manages the mapping between variable names and their corresponding {@link ValueExpression} instances within an
+ * {@link ELContext}. Variable mappings allow EL expressions to reference named variables that resolve to computed
+ * values.
  */
 public abstract class VariableMapper {
 
+    /**
+     * Default constructor for subclasses.
+     */
+    public VariableMapper() {
+    }
+
+    /**
+     * Resolves a variable name to its corresponding ValueExpression.
+     *
+     * @param variable the name of the variable to resolve
+     *
+     * @return the ValueExpression for the variable, or {@code null} if not found
+     */
     public abstract ValueExpression resolveVariable(String variable);
 
+    /**
+     * Sets or removes a variable mapping.
+     *
+     * @param variable   the name of the variable
+     * @param expression the ValueExpression to associate with the variable, or {@code null} to remove the mapping
+     *
+     * @return the previous ValueExpression for the variable, or {@code null} if there was no mapping
+     */
     public abstract ValueExpression setVariable(String variable, ValueExpression expression);
 }
diff --git a/java/jakarta/mail/Authenticator.java b/java/jakarta/mail/Authenticator.java
index 65866750ef..3896516877 100644
--- a/java/jakarta/mail/Authenticator.java
+++ b/java/jakarta/mail/Authenticator.java
@@ -16,7 +16,25 @@
  */
 package jakarta.mail;
 
+/**
+ * Abstract base class for providing user authentication when establishing network connections. Subclasses override
+ * {@link #getPasswordAuthentication} to return the appropriate credentials. This class is part of the Jakarta Mail
+ * API and follows the pattern defined by {@link java.net.Authenticator}.
+ */
 public class Authenticator {
+
+    /**
+     * Default constructor for subclasses.
+     */
+    public Authenticator() {
+    }
+
+    /**
+     * Returns the password authentication information for the current request. The default implementation returns
+     * {@code null}. Subclasses should override this method to provide actual credentials.
+     *
+     * @return the PasswordAuthentication object, or {@code null} if no authentication is available
+     */
     protected PasswordAuthentication getPasswordAuthentication() {
         return null;
     }
diff --git a/java/jakarta/mail/PasswordAuthentication.java b/java/jakarta/mail/PasswordAuthentication.java
index 7be7b29e85..a76f8b7909 100644
--- a/java/jakarta/mail/PasswordAuthentication.java
+++ b/java/jakarta/mail/PasswordAuthentication.java
@@ -16,8 +16,20 @@
  */
 package jakarta.mail;
 
+/**
+ * Stores username and password credentials for mail authentication. This class follows the pattern defined by
+ * {@link java.net.PasswordAuthentication} and is used with {@link Authenticator} to provide credentials when
+ * establishing mail connections.
+ */
 @SuppressWarnings("unused") // Dummy implementation
 public class PasswordAuthentication {
+
+    /**
+     * Constructs a PasswordAuthentication with the given user and password.
+     *
+     * @param user     the username
+     * @param password the password
+     */
     public PasswordAuthentication(String user, String password) {
         // Dummy implementation
     }
diff --git a/java/jakarta/mail/Session.java b/java/jakarta/mail/Session.java
index 87ff869d3b..35f221afff 100644
--- a/java/jakarta/mail/Session.java
+++ b/java/jakarta/mail/Session.java
@@ -18,12 +18,34 @@ package jakarta.mail;
 
 import java.util.Properties;
 
+/**
+ * Represents a mail session configuration.
+ */
 @SuppressWarnings("unused") // Dummy implementation
 public class Session {
+    /**
+     * Default constructor.
+     */
+    public Session() {
+    }
+
+    /**
+     * Returns a Session object with the given properties and authenticator.
+     *
+     * @param props the session properties
+     * @param auth the authenticator
+     * @return the mail session
+     */
     public static Session getInstance(Properties props, Authenticator auth) {
         return null;
     }
 
+    /**
+     * Returns a Session object with the given properties.
+     *
+     * @param props the session properties
+     * @return the mail session
+     */
     public static Session getInstance(Properties props) {
         return null;
     }
diff --git a/java/jakarta/mail/internet/InternetAddress.java b/java/jakarta/mail/internet/InternetAddress.java
index aa1ce3859e..5d766f5e4d 100644
--- a/java/jakarta/mail/internet/InternetAddress.java
+++ b/java/jakarta/mail/internet/InternetAddress.java
@@ -16,8 +16,19 @@
  */
 package jakarta.mail.internet;
 
+/**
+ * Represents an Internet email address as defined by RFC 822.
+ * An Internet address consists of an optional personal name and
+ * an address string in the form of local-part@domain.
+ */
 @SuppressWarnings("unused") // Dummy implementation
 public class InternetAddress {
+    /**
+     * Constructs an InternetAddress from the specified address string.
+     * The address string may optionally include a personal name portion.
+     *
+     * @param from the email address string to parse
+     */
     public InternetAddress(String from) {
         // Dummy implementation
     }
diff --git a/java/jakarta/mail/internet/MimeMessage.java b/java/jakarta/mail/internet/MimeMessage.java
index 39644f0509..3fae2b288c 100644
--- a/java/jakarta/mail/internet/MimeMessage.java
+++ b/java/jakarta/mail/internet/MimeMessage.java
@@ -18,16 +18,35 @@ package jakarta.mail.internet;
 
 import jakarta.mail.Session;
 
+/**
+ * Represents a MIME message in the Jakarta Mail API.
+ * Provides methods for setting message headers such as sender and subject.
+ */
 @SuppressWarnings("unused") // Dummy implementation
 public class MimeMessage implements MimePart {
+    /**
+     * Constructs a MimeMessage with the given Session.
+     *
+     * @param session the mail session used to create this message
+     */
     public MimeMessage(Session session) {
         // Dummy implementation
     }
 
+    /**
+     * Sets the InternetAddress of the message sender.
+     *
+     * @param from the InternetAddress of the sender
+     */
     public void setFrom(InternetAddress from) {
         // Dummy implementation
     }
 
+    /**
+     * Sets the subject of the message.
+     *
+     * @param subject the subject string
+     */
     public void setSubject(String subject) {
         // Dummy implementation
     }
diff --git a/java/jakarta/mail/internet/MimePart.java b/java/jakarta/mail/internet/MimePart.java
index 7591634fae..0be69d33e6 100644
--- a/java/jakarta/mail/internet/MimePart.java
+++ b/java/jakarta/mail/internet/MimePart.java
@@ -16,6 +16,10 @@
  */
 package jakarta.mail.internet;
 
+/**
+ * Represents a part of a MIME message in the Jakarta Mail API.
+ * A MimePart can contain content and headers for a single MIME entity.
+ */
 public interface MimePart {
     // Dummy implementation
 }
diff --git a/java/jakarta/mail/internet/MimePartDataSource.java b/java/jakarta/mail/internet/MimePartDataSource.java
index a86bae55ea..17b946b53a 100644
--- a/java/jakarta/mail/internet/MimePartDataSource.java
+++ b/java/jakarta/mail/internet/MimePartDataSource.java
@@ -16,8 +16,17 @@
  */
 package jakarta.mail.internet;
 
+/**
+ * Provides a DataSource representation for a MimePart.
+ * Wraps a MimePart so it can be used where a DataSource is required.
+ */
 @SuppressWarnings("unused") // Dummy implementation
 public class MimePartDataSource {
+    /**
+     * Constructs a MimePartDataSource wrapping the given MimePart.
+     *
+     * @param part the MimePart to wrap
+     */
     public MimePartDataSource(MimePart part) {
         // Dummy implementation
     }
diff --git a/java/jakarta/persistence/PersistenceContext.java b/java/jakarta/persistence/PersistenceContext.java
index 78ece9e615..c0963ab44c 100644
--- a/java/jakarta/persistence/PersistenceContext.java
+++ b/java/jakarta/persistence/PersistenceContext.java
@@ -21,17 +21,45 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Specifies the entity manager for use with an entity bean or other managed class.
+ * Used to inject a persistence context into a Jakarta EE managed component.
+ */
 @Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD })
 @Retention(RetentionPolicy.RUNTIME)
-
 public @interface PersistenceContext {
+    /**
+     * The name used to look up the persistence context.
+     *
+     * @return the persistence context name
+     */
     String name() default "";
 
+    /**
+     * The unit name of the persistence unit to associate with the persistence context.
+     *
+     * @return the persistence unit name
+     */
     String unitName() default "";
 
+    /**
+     * The type of the persistence context.
+     *
+     * @return the persistence context type
+     */
     PersistenceContextType type() default PersistenceContextType.TRANSACTION;
 
+    /**
+     * Properties used to configure the persistence context.
+     *
+     * @return the configuration properties
+     */
     PersistenceProperty[] properties() default {};
 
+    /**
+     * The synchronization type of the persistence context with the transaction.
+     *
+     * @return the synchronization type
+     */
     SynchronizationType synchronization() default SynchronizationType.SYNCHRONIZED;
 }
diff --git a/java/jakarta/persistence/PersistenceContextType.java b/java/jakarta/persistence/PersistenceContextType.java
index 0e54e3c1ad..9f4af89442 100644
--- a/java/jakarta/persistence/PersistenceContextType.java
+++ b/java/jakarta/persistence/PersistenceContextType.java
@@ -16,7 +16,21 @@
  */
 package jakarta.persistence;
 
+/**
+ * Defines the type of persistence context.
+ */
 public enum PersistenceContextType {
+    /**
+     * The default persistence context type.
+     * The entity manager is tied to the current transaction and is automatically
+     * closed when the transaction completes.
+     */
     TRANSACTION,
+
+    /**
+     * An extended persistence context type.
+     * The entity manager spans multiple transactions and remains open
+     * until explicitly closed by the application.
+     */
     EXTENDED
-}
\ No newline at end of file
+}
diff --git a/java/jakarta/persistence/PersistenceContexts.java b/java/jakarta/persistence/PersistenceContexts.java
index 671d117c7c..ab3f2d49ce 100644
--- a/java/jakarta/persistence/PersistenceContexts.java
+++ b/java/jakarta/persistence/PersistenceContexts.java
@@ -21,9 +21,16 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Groups multiple PersistenceContext annotations for injection into a single component.
+ */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
-
 public @interface PersistenceContexts {
+    /**
+     * The array of PersistenceContext annotations.
+     *
+     * @return the persistence contexts
+     */
     PersistenceContext[] value();
 }
diff --git a/java/jakarta/persistence/PersistenceProperty.java b/java/jakarta/persistence/PersistenceProperty.java
index 3ed05e1982..8c39f8a41b 100644
--- a/java/jakarta/persistence/PersistenceProperty.java
+++ b/java/jakarta/persistence/PersistenceProperty.java
@@ -20,11 +20,24 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Specifies a property for configuring a persistence context or persistence unit.
+ * Used within the properties element of PersistenceContext or PersistenceUnit annotations.
+ */
 @Target({})
 @Retention(RetentionPolicy.RUNTIME)
-
 public @interface PersistenceProperty {
+    /**
+     * The name of the property.
+     *
+     * @return the property name
+     */
     String name();
 
+    /**
+     * The value of the property.
+     *
+     * @return the property value
+     */
     String value();
 }
diff --git a/java/jakarta/persistence/PersistenceUnit.java b/java/jakarta/persistence/PersistenceUnit.java
index 0580f11112..5d72ed565a 100644
--- a/java/jakarta/persistence/PersistenceUnit.java
+++ b/java/jakarta/persistence/PersistenceUnit.java
@@ -21,11 +21,25 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Specifies a persistence unit for use with an entity bean or other managed class. Used to inject an
+ * EntityManagerFactory into a Jakarta EE managed component.
+ */
 @Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD })
 @Retention(RetentionPolicy.RUNTIME)
-
 public @interface PersistenceUnit {
+
+    /**
+     * The name used to look up the EntityManagerFactory.
+     *
+     * @return the lookup name
+     */
     String name() default "";
 
+    /**
+     * The unit name of the persistence unit.
+     *
+     * @return the persistence unit name
+     */
     String unitName() default "";
 }
diff --git a/java/jakarta/persistence/PersistenceUnits.java b/java/jakarta/persistence/PersistenceUnits.java
index 3da4da578e..d1260eb30a 100644
--- a/java/jakarta/persistence/PersistenceUnits.java
+++ b/java/jakarta/persistence/PersistenceUnits.java
@@ -21,9 +21,16 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Groups multiple PersistenceUnit annotations for injection into a single component.
+ */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
-
 public @interface PersistenceUnits {
+    /**
+     * The array of PersistenceUnit annotations.
+     *
+     * @return the persistence units
+     */
     PersistenceUnit[] value();
 }
diff --git a/java/jakarta/persistence/SynchronizationType.java b/java/jakarta/persistence/SynchronizationType.java
index b1d5c1acc5..40ad6bf5ac 100644
--- a/java/jakarta/persistence/SynchronizationType.java
+++ b/java/jakarta/persistence/SynchronizationType.java
@@ -16,7 +16,16 @@
  */
 package jakarta.persistence;
 
+/**
+ * Specifies the synchronization type of an entity manager with JTA transactions.
+ */
 public enum SynchronizationType {
+    /**
+     * The entity manager participates in the current JTA transaction.
+     */
     SYNCHRONIZED,
+    /**
+     * The entity manager does not participate in the current JTA transaction.
+     */
     UNSYNCHRONIZED
 }
diff --git a/java/jakarta/security/auth/message/AuthException.java b/java/jakarta/security/auth/message/AuthException.java
index f5a71e44fc..40cd5a47cd 100644
--- a/java/jakarta/security/auth/message/AuthException.java
+++ b/java/jakarta/security/auth/message/AuthException.java
@@ -20,13 +20,25 @@ import java.io.Serial;
 
 import javax.security.auth.login.LoginException;
 
+/**
+ * Exception thrown when a JASPIC authentication operation fails. This exception is used by authentication modules
+ * and contexts to signal errors during the authentication process.
+ */
 public class AuthException extends LoginException {
     @Serial
     private static final long serialVersionUID = -1156951780670243758L;
 
+    /**
+     * Constructs an AuthException with no detail message.
+     */
     public AuthException() {
     }
 
+    /**
+     * Constructs an AuthException with the specified detail message.
+     *
+     * @param msg the detail message
+     */
     public AuthException(String msg) {
         super(msg);
     }
diff --git a/java/jakarta/security/auth/message/AuthStatus.java b/java/jakarta/security/auth/message/AuthStatus.java
index ec009c80b4..c927296493 100644
--- a/java/jakarta/security/auth/message/AuthStatus.java
+++ b/java/jakarta/security/auth/message/AuthStatus.java
@@ -16,12 +16,35 @@
  */
 package jakarta.security.auth.message;
 
+/**
+ * Represents the status returned by JASPIC authentication operations. The authentication status indicates whether
+ * authentication succeeded, failed, or requires further message exchange.
+ */
 public class AuthStatus {
 
+    /**
+     * Authentication succeeded and no further message exchange is required.
+     */
     public static final AuthStatus SUCCESS = new AuthStatus("SUCCESS");
+
+    /**
+     * Authentication failed and no further message exchange will change the outcome.
+     */
     public static final AuthStatus FAILURE = new AuthStatus("FAILURE");
+
+    /**
+     * Authentication succeeded and the response should be sent to the peer.
+     */
     public static final AuthStatus SEND_SUCCESS = new AuthStatus("SEND_SUCCESS");
+
+    /**
+     * Authentication failed and the failure response should be sent to the peer.
+     */
     public static final AuthStatus SEND_FAILURE = new AuthStatus("SEND_FAILURE");
+
+    /**
+     * Authentication is in progress and further message exchange is required.
+     */
     public static final AuthStatus SEND_CONTINUE = new AuthStatus("SEND_CONTINUE");
 
     private final String name;
diff --git a/java/jakarta/security/auth/message/ClientAuth.java b/java/jakarta/security/auth/message/ClientAuth.java
index 79bda35aff..a4937e06fb 100644
--- a/java/jakarta/security/auth/message/ClientAuth.java
+++ b/java/jakarta/security/auth/message/ClientAuth.java
@@ -18,6 +18,10 @@ package jakarta.security.auth.message;
 
 import javax.security.auth.Subject;
 
+/**
+ * Defines the contract for client-side authentication in JASPIC. A ClientAuth implementation authenticates outbound
+ * requests and validates inbound responses in a client-to-server communication pattern.
+ */
 public interface ClientAuth {
 
     /**
diff --git a/java/jakarta/security/auth/message/MessageInfo.java b/java/jakarta/security/auth/message/MessageInfo.java
index 4fd1e18f21..cb9c760132 100644
--- a/java/jakarta/security/auth/message/MessageInfo.java
+++ b/java/jakarta/security/auth/message/MessageInfo.java
@@ -18,15 +18,53 @@ package jakarta.security.auth.message;
 
 import java.util.Map;
 
+/**
+ * Represents the request and response messages associated with a
+ * message-based authentication exchange.  The {@code MessageInfo} object
+ * provides access to the request and response message objects, as well
+ * as a map of additional context information.  The types of the request
+ * and response message objects are protocol-specific.
+ */
 public interface MessageInfo {
 
+    /**
+     * Returns the request message object associated with this
+     * authentication exchange.  The type of the returned object is
+     * protocol-specific.
+     *
+     * @return the request message object, or {@code null} if not available
+     */
     Object getRequestMessage();
 
+    /**
+     * Returns the response message object associated with this
+     * authentication exchange.  The type of the returned object is
+     * protocol-specific.
+     *
+     * @return the response message object, or {@code null} if not available
+     */
     Object getResponseMessage();
 
+    /**
+     * Sets the request message object for this authentication exchange.
+     *
+     * @param request the request message object
+     */
     void setRequestMessage(Object request);
 
+    /**
+     * Sets the response message object for this authentication exchange.
+     *
+     * @param response the response message object
+     */
     void setResponseMessage(Object response);
 
+    /**
+     * Returns a map of additional context information associated with
+     * this authentication exchange.  The map may contain protocol-specific
+     * attributes such as message headers.
+     *
+     * @return a {@code Map} of context information, or {@code null} if not available
+     */
     Map<String,Object> getMap();
 }
diff --git a/java/jakarta/security/auth/message/MessagePolicy.java b/java/jakarta/security/auth/message/MessagePolicy.java
index 3237ab42d6..7f0f3b2d12 100644
--- a/java/jakarta/security/auth/message/MessagePolicy.java
+++ b/java/jakarta/security/auth/message/MessagePolicy.java
@@ -16,11 +16,28 @@
  */
 package jakarta.security.auth.message;
 
+/**
+ * Defines the security policy requirements for a message-based
+ * authentication module.  A {@code MessagePolicy} specifies the target
+ * policies that determine which messages require authentication and the
+ * level of protection required.
+ */
 public class MessagePolicy {
 
     private final TargetPolicy[] targetPolicies;
     private final boolean mandatory;
 
+    /**
+     * Creates a new {@code MessagePolicy} with the specified target
+     * policies and mandatory flag.
+     *
+     * @param targetPolicies the array of {@code TargetPolicy} objects
+     *        defining the policy requirements; must not be {@code null}
+     * @param mandatory {@code true} if the policy is mandatory and
+     *        authentication must succeed; {@code false} if the policy
+     *        is optional
+     * @throws IllegalArgumentException if {@code targetPolicies} is {@code null}
+     */
     public MessagePolicy(TargetPolicy[] targetPolicies, boolean mandatory) {
         if (targetPolicies == null) {
             throw new IllegalArgumentException("targetPolicies is null");
@@ -29,10 +46,23 @@ public class MessagePolicy {
         this.mandatory = mandatory;
     }
 
+    /**
+     * Indicates whether this policy is mandatory.  If mandatory, the
+     * authentication module must enforce the policy and authentication
+     * will fail if the policy cannot be satisfied.
+     *
+     * @return {@code true} if the policy is mandatory, {@code false} otherwise
+     */
     public boolean isMandatory() {
         return mandatory;
     }
 
+    /**
+     * Returns the target policies associated with this message policy.
+     *
+     * @return an array of {@code TargetPolicy} objects, or {@code null}
+     *         if no target policies are defined
+     */
     public TargetPolicy[] getTargetPolicies() {
         if (targetPolicies.length == 0) {
             return null;
@@ -40,29 +70,87 @@ public class MessagePolicy {
         return targetPolicies;
     }
 
+    /**
+     * Defines the level of protection to be applied to a message.
+     * A protection policy specifies whether the sender, content,
+     * or recipient of a message must be authenticated.
+     */
     public interface ProtectionPolicy {
 
+        /**
+         * Identifier for a policy that requires authentication of the sender.
+         */
         String AUTHENTICATE_SENDER = "#authenticateSender";
+
+        /**
+         * Identifier for a policy that requires authentication of the message content.
+         */
         String AUTHENTICATE_CONTENT = "#authenticateContent";
+
+        /**
+         * Identifier for a policy that requires authentication of the recipient.
+         */
         String AUTHENTICATE_RECIPIENT = "#authenticateRecipient";
 
+        /**
+         * Returns the unique identifier for this protection policy.
+         *
+         * @return the string identifier for this policy
+         */
         String getID();
     }
 
+    /**
+     * Defines how to extract target information from a message for
+     * policy evaluation.  A target determines which messages are
+     * subject to a particular {@code TargetPolicy}.
+     */
     public interface Target {
 
+        /**
+         * Retrieves the target value from the given message.
+         *
+         * @param messageInfo the message containing the target information
+         * @return the target value extracted from the message
+         */
         Object get(MessageInfo messageInfo);
 
+        /**
+         * Removes the target value from the given message.
+         *
+         * @param messageInfo the message from which to remove the target
+         */
         void remove(MessageInfo messageInfo);
 
+        /**
+         * Stores the target value in the given message.
+         *
+         * @param messageInfo the message in which to store the target
+         * @param data the target value to store
+         */
         void put(MessageInfo messageInfo, Object data);
     }
 
+    /**
+     * Associates a set of targets with a protection policy.  A
+     * {@code TargetPolicy} defines the protection requirements for
+     * messages that match the specified targets.
+     */
     public static class TargetPolicy {
 
         private final Target[] targets;
         private final ProtectionPolicy protectionPolicy;
 
+        /**
+         * Creates a new {@code TargetPolicy} with the specified targets
+         * and protection policy.
+         *
+         * @param targets the array of {@code Target} objects, or {@code null}
+         *        if not applicable
+         * @param protectionPolicy the {@code ProtectionPolicy} to apply;
+         *        must not be {@code null}
+         * @throws IllegalArgumentException if {@code protectionPolicy} is {@code null}
+         */
         public TargetPolicy(Target[] targets, ProtectionPolicy protectionPolicy) {
             if (protectionPolicy == null) {
                 throw new IllegalArgumentException("protectionPolicy is null");
@@ -71,6 +159,12 @@ public class MessagePolicy {
             this.protectionPolicy = protectionPolicy;
         }
 
+        /**
+         * Returns the targets associated with this target policy.
+         *
+         * @return an array of {@code Target} objects, or {@code null}
+         *         if no targets are defined
+         */
         public Target[] getTargets() {
             if (targets == null || targets.length == 0) {
                 return null;
@@ -78,6 +172,11 @@ public class MessagePolicy {
             return targets;
         }
 
+        /**
+         * Returns the protection policy associated with this target policy.
+         *
+         * @return the {@code ProtectionPolicy} for this target policy
+         */
         public ProtectionPolicy getProtectionPolicy() {
             return protectionPolicy;
         }
diff --git a/java/jakarta/security/auth/message/ServerAuth.java b/java/jakarta/security/auth/message/ServerAuth.java
index 8df08f055a..1508051b9d 100644
--- a/java/jakarta/security/auth/message/ServerAuth.java
+++ b/java/jakarta/security/auth/message/ServerAuth.java
@@ -18,6 +18,13 @@ package jakarta.security.auth.message;
 
 import javax.security.auth.Subject;
 
+/**
+ * Provides server-side authentication of requests and response signing.
+ * <p>
+ * This interface defines the contract for authenticating incoming requests
+ * and optionally securing outgoing responses in a server-side context.
+ * Implementations are typically obtained through a {@link jakarta.security.auth.message.config.ServerAuthContext}.
+ */
 public interface ServerAuth {
 
     /**
diff --git a/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java b/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java
index c29fca9002..11aaf37c9e 100644
--- a/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java
+++ b/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java
@@ -22,8 +22,9 @@ import javax.security.auth.Subject;
 import javax.security.auth.callback.Callback;
 
 /**
- * Callback that enables an authentication module to inform the runtime of the call principal or name of the caller
- * principal.
+ * Callback that enables an authentication module to inform the runtime of the caller principal or name of the
+ * caller principal. The callback handler populates the given Subject with the authenticated principal, or returns
+ * the principal/name that was provided.
  */
 public class CallerPrincipalCallback implements Callback {
 
@@ -31,26 +32,55 @@ public class CallerPrincipalCallback implements Callback {
     private final Principal principal;
     private final String name;
 
+    /**
+     * Constructs a callback with a Subject and a Principal. The callback handler will add the principal to the
+     * subject.
+     *
+     * @param subject   the subject to which the principal will be added
+     * @param principal the principal representing the caller
+     */
     public CallerPrincipalCallback(Subject subject, Principal principal) {
         this.subject = subject;
         this.principal = principal;
         this.name = null;
     }
 
+    /**
+     * Constructs a callback with a Subject and a caller name. The callback handler will create a principal from
+     * the name and add it to the subject.
+     *
+     * @param subject the subject to which the principal will be added
+     * @param name    the name of the caller
+     */
     public CallerPrincipalCallback(Subject subject, String name) {
         this.subject = subject;
         this.principal = null;
         this.name = name;
     }
 
+    /**
+     * Returns the Subject associated with this callback.
+     *
+     * @return the Subject
+     */
     public Subject getSubject() {
         return subject;
     }
 
+    /**
+     * Returns the Principal associated with this callback, or {@code null} if a name was provided instead.
+     *
+     * @return the Principal, or {@code null}
+     */
     public Principal getPrincipal() {
         return principal;
     }
 
+    /**
+     * Returns the name associated with this callback, or {@code null} if a Principal was provided instead.
+     *
+     * @return the name, or {@code null}
+     */
     public String getName() {
         return name;
     }
diff --git a/java/jakarta/security/auth/message/callback/CertStoreCallback.java b/java/jakarta/security/auth/message/callback/CertStoreCallback.java
index d8aef96cb2..f30a9dbf95 100644
--- a/java/jakarta/security/auth/message/callback/CertStoreCallback.java
+++ b/java/jakarta/security/auth/message/callback/CertStoreCallback.java
@@ -21,19 +21,33 @@ import java.security.cert.CertStore;
 import javax.security.auth.callback.Callback;
 
 /**
- * Callback that enables a runtime to inform authentication modules of the CertStore to use.
+ * Callback that enables a runtime to inform authentication modules of the {@link CertStore} to use for certificate
+ * validation. The runtime populates the CertStore, and the authentication module retrieves it.
  */
 public class CertStoreCallback implements Callback {
 
     private CertStore certStore;
 
+    /**
+     * Constructs an empty CertStoreCallback. The runtime will populate the CertStore via {@link #setCertStore}.
+     */
     public CertStoreCallback() {
     }
 
+    /**
+     * Sets the CertStore to be used for certificate validation.
+     *
+     * @param certStore the CertStore
+     */
     public void setCertStore(CertStore certStore) {
         this.certStore = certStore;
     }
 
+    /**
+     * Returns the CertStore set by the runtime.
+     *
+     * @return the CertStore, or {@code null} if not yet set
+     */
     public CertStore getCertStore() {
         return certStore;
     }
diff --git a/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java b/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java
index f5b2e55ffe..4f053e22f0 100644
--- a/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java
+++ b/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java
@@ -21,21 +21,40 @@ import javax.security.auth.callback.Callback;
 
 /**
  * Callback that enables an authentication module to inform the runtime of the groups a user is in.
+ * The callback handler populates the given Subject with the group principals, or returns the
+ * group names that were provided.
  */
 public class GroupPrincipalCallback implements Callback {
 
     private final Subject subject;
     private final String[] groups;
 
+    /**
+     * Constructs a callback with a Subject and an array of group names. The callback handler
+     * will create principals for the group names and add them to the subject.
+     *
+     * @param subject the subject to which the group principals will be added
+     * @param groups  the group names associated with the caller
+     */
     public GroupPrincipalCallback(Subject subject, String[] groups) {
         this.subject = subject;
         this.groups = groups;
     }
 
+    /**
+     * Returns the Subject associated with this callback.
+     *
+     * @return the Subject
+     */
     public Subject getSubject() {
         return subject;
     }
 
+    /**
+     * Returns the group names associated with this callback.
+     *
+     * @return the group names
+     */
     public String[] getGroups() {
         return groups;
     }
diff --git a/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java b/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java
index ae9f6bdecc..d552255736 100644
--- a/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java
+++ b/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java
@@ -22,8 +22,10 @@ import javax.security.auth.Subject;
 import javax.security.auth.callback.Callback;
 
 /**
- * Callback that enables an authentication module to supply a username and password (to a runtime?) and determine if the
- * result of validation.
+ * A callback that enables an authentication module to supply a username
+ * and password to the runtime and obtain the result of password validation.
+ * The runtime validates the credentials and updates the {@code Subject}
+ * if authentication succeeds.
  */
 public class PasswordValidationCallback implements Callback {
 
@@ -32,33 +34,76 @@ public class PasswordValidationCallback implements Callback {
     private char[] password;
     private boolean result;
 
+    /**
+     * Creates a new {@code PasswordValidationCallback} with the specified
+     * subject, username, and password.
+     *
+     * @param subject the {@code Subject} to be populated upon successful
+     *        authentication
+     * @param username the username to validate
+     * @param password the password to validate
+     */
     public PasswordValidationCallback(Subject subject, String username, char[] password) {
         this.subject = subject;
         this.username = username;
         this.password = password;
     }
 
+    /**
+     * Returns the {@code Subject} associated with this callback.  The
+     * runtime populates this subject with authentication information
+     * upon successful validation.
+     *
+     * @return the {@code Subject} for this callback
+     */
     public Subject getSubject() {
         return subject;
     }
 
+    /**
+     * Returns the username to be validated.
+     *
+     * @return the username
+     */
     public String getUsername() {
         return username;
     }
 
+    /**
+     * Returns the password to be validated.
+     *
+     * @return the password character array
+     */
     public char[] getPassword() {
         return password;
     }
 
+    /**
+     * Clears the password from memory for security purposes.  After
+     * calling this method, {@link #getPassword()} will return an empty
+     * character array.
+     */
     public void clearPassword() {
         Arrays.fill(password, (char) 0);
         password = new char[0];
     }
 
+    /**
+     * Sets the result of the password validation performed by the runtime.
+     *
+     * @param result {@code true} if the password validation succeeded,
+     *        {@code false} otherwise
+     */
     public void setResult(boolean result) {
         this.result = result;
     }
 
+    /**
+     * Returns the result of the password validation.
+     *
+     * @return {@code true} if the password was validated successfully,
+     *         {@code false} otherwise
+     */
     public boolean getResult() {
         return result;
     }
diff --git a/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java b/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java
index 853ca02600..c3aab997d6 100644
--- a/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java
+++ b/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java
@@ -24,9 +24,11 @@ import javax.security.auth.callback.Callback;
 import javax.security.auth.x500.X500Principal;
 
 /**
- * Callback that enables an authentication module to request a certificate chain and private key from the runtime. The
- * information specifying the chain and key may be an alias, a digest, a subject key, or an issuer ID. Other request
- * types may be supported.
+ * A callback that enables an authentication module to request a
+ * certificate chain and private key from the runtime.  The request
+ * identifies the desired key material using one of several {@link Request}
+ * subtypes, such as keystore alias, certificate digest, subject key
+ * identifier, or issuer and serial number.
  */
 public class PrivateKeyCallback implements Callback {
 
@@ -34,87 +36,192 @@ public class PrivateKeyCallback implements Callback {
     private Certificate[] chain;
     private PrivateKey key;
 
+    /**
+     * Creates a new {@code PrivateKeyCallback} with the specified request.
+     *
+     * @param request the {@code Request} object identifying the desired
+     *        certificate chain and private key
+     */
     public PrivateKeyCallback(Request request) {
         this.request = request;
     }
 
+    /**
+     * Returns the request associated with this callback.
+     *
+     * @return the {@code Request} object
+     */
     public Request getRequest() {
         return request;
     }
 
+    /**
+     * Sets the private key and certificate chain resolved by the runtime
+     * in response to the request.
+     *
+     * @param key the resolved {@code PrivateKey}
+     * @param chain the corresponding certificate chain
+     */
     public void setKey(PrivateKey key, Certificate[] chain) {
         this.key = key;
         this.chain = chain;
     }
 
+    /**
+     * Returns the private key resolved by the runtime.
+     *
+     * @return the {@code PrivateKey}, or {@code null} if not yet resolved
+     */
     public PrivateKey getKey() {
         return key;
     }
 
+    /**
+     * Returns the certificate chain resolved by the runtime.
+     *
+     * @return the certificate chain, or {@code null} if not yet resolved
+     */
     public Certificate[] getChain() {
         return chain;
     }
 
+    /**
+     * Base interface for private key requests.  Implementations specify
+     * the criteria by which the runtime should locate the desired
+     * certificate chain and private key.
+     */
     public interface Request {
     }
 
+    /**
+     * A request to retrieve a certificate chain and private key by
+     * keystore alias.
+     */
     public static class AliasRequest implements Request {
 
         private final String alias;
 
+        /**
+         * Creates a new {@code AliasRequest} with the specified keystore alias.
+         *
+         * @param alias the keystore alias identifying the desired key entry
+         */
         public AliasRequest(String alias) {
             this.alias = alias;
         }
 
+        /**
+         * Returns the keystore alias for this request.
+         *
+         * @return the keystore alias
+         */
         public String getAlias() {
             return alias;
         }
     }
 
+    /**
+     * A request to retrieve a certificate chain and private key by
+     * certificate digest value.
+     */
     public static class DigestRequest implements Request {
         private final byte[] digest;
         private final String algorithm;
 
+        /**
+         * Creates a new {@code DigestRequest} with the specified digest
+         * value and digest algorithm.
+         *
+         * @param digest the digest value of the desired certificate
+         * @param algorithm the digest algorithm used to produce the digest
+         */
         public DigestRequest(byte[] digest, String algorithm) {
             this.digest = digest;
             this.algorithm = algorithm;
         }
 
+        /**
+         * Returns the digest value for this request.
+         *
+         * @return the digest byte array
+         */
         public byte[] getDigest() {
             return digest;
         }
 
+        /**
+         * Returns the digest algorithm used for this request.
+         *
+         * @return the algorithm name
+         */
         public String getAlgorithm() {
             return algorithm;
         }
     }
 
+    /**
+     * A request to retrieve a certificate chain and private key by
+     * the Subject Key Identifier extension value.
+     */
     public static class SubjectKeyIDRequest implements Request {
 
         private final byte[] subjectKeyID;
 
+        /**
+         * Creates a new {@code SubjectKeyIDRequest} with the specified
+         * subject key identifier.
+         *
+         * @param subjectKeyID the Subject Key Identifier extension value
+         *        from the desired certificate
+         */
         public SubjectKeyIDRequest(byte[] subjectKeyID) {
             this.subjectKeyID = subjectKeyID;
         }
 
+        /**
+         * Returns the subject key identifier for this request.
+         *
+         * @return the Subject Key Identifier byte array
+         */
         public byte[] getSubjectKeyID() {
             return subjectKeyID;
         }
     }
 
+    /**
+     * A request to retrieve a certificate chain and private key by
+     * the issuer distinguished name and certificate serial number.
+     */
     public static class IssuerSerialNumRequest implements Request {
         private final X500Principal issuer;
         private final BigInteger serialNum;
 
+        /**
+         * Creates a new {@code IssuerSerialNumRequest} with the specified
+         * issuer and serial number.
+         *
+         * @param issuer the issuer distinguished name of the desired certificate
+         * @param serialNum the serial number of the desired certificate
+         */
         public IssuerSerialNumRequest(X500Principal issuer, BigInteger serialNum) {
             this.issuer = issuer;
             this.serialNum = serialNum;
         }
 
+        /**
+         * Returns the issuer distinguished name for this request.
+         *
+         * @return the {@code X500Principal} representing the issuer
+         */
         public X500Principal getIssuer() {
             return issuer;
         }
 
+        /**
+         * Returns the certificate serial number for this request.
+         *
+         * @return the serial number as a {@code BigInteger}
+         */
         public BigInteger getSerialNum() {
             return serialNum;
         }
diff --git a/java/jakarta/security/auth/message/callback/SecretKeyCallback.java b/java/jakarta/security/auth/message/callback/SecretKeyCallback.java
index b3a02ad938..7cf47cdec8 100644
--- a/java/jakarta/security/auth/message/callback/SecretKeyCallback.java
+++ b/java/jakarta/security/auth/message/callback/SecretKeyCallback.java
@@ -28,33 +28,70 @@ public class SecretKeyCallback implements Callback {
     private final Request request;
     private SecretKey key;
 
+    /**
+     * Constructs a SecretKeyCallback with the specified request.
+     *
+     * @param request The request describing the secret key to obtain
+     */
     public SecretKeyCallback(Request request) {
         this.request = request;
     }
 
+    /**
+     * Returns the request associated with this callback.
+     *
+     * @return The request describing the secret key to obtain
+     */
     public Request getRequest() {
         return request;
     }
 
+    /**
+     * Sets the secret key obtained by the runtime.
+     *
+     * @param key The secret key
+     */
     public void setKey(SecretKey key) {
         this.key = key;
     }
 
+    /**
+     * Returns the secret key.
+     *
+     * @return The secret key, or {@code null} if not set
+     */
     public SecretKey getKey() {
         return key;
     }
 
+    /**
+     * Represents a request for a secret key.
+     * Implementations specify the criteria for locating the desired key.
+     */
     public interface Request {
     }
 
+    /**
+     * A request for a secret key identified by its alias.
+     */
     public static class AliasRequest implements Request {
 
         private final String alias;
 
+        /**
+         * Constructs an AliasRequest with the specified alias.
+         *
+         * @param alias The alias of the secret key to obtain
+         */
         public AliasRequest(String alias) {
             this.alias = alias;
         }
 
+        /**
+         * Returns the alias of the requested secret key.
+         *
+         * @return The alias string
+         */
         public String getAlias() {
             return alias;
         }
diff --git a/java/jakarta/security/auth/message/callback/TrustStoreCallback.java b/java/jakarta/security/auth/message/callback/TrustStoreCallback.java
index 9bafa9a26b..a6a367ba19 100644
--- a/java/jakarta/security/auth/message/callback/TrustStoreCallback.java
+++ b/java/jakarta/security/auth/message/callback/TrustStoreCallback.java
@@ -27,10 +27,26 @@ public class TrustStoreCallback implements Callback {
 
     private KeyStore trustStore;
 
+    /**
+     * Constructs a new TrustStoreCallback.
+     */
+    public TrustStoreCallback() {
+    }
+
+    /**
+     * Sets the trust store to be used for certificate validation.
+     *
+     * @param trustStore The trust store containing trusted certificates
+     */
     public void setTrustStore(KeyStore trustStore) {
         this.trustStore = trustStore;
     }
 
+    /**
+     * Returns the trust store.
+     *
+     * @return The trust store, or {@code null} if not set
+     */
     public KeyStore getTrustStore() {
         return trustStore;
     }
diff --git a/java/jakarta/security/auth/message/config/AuthConfig.java b/java/jakarta/security/auth/message/config/AuthConfig.java
index 099cccee8d..7e3e5e0572 100644
--- a/java/jakarta/security/auth/message/config/AuthConfig.java
+++ b/java/jakarta/security/auth/message/config/AuthConfig.java
@@ -18,15 +18,46 @@ package jakarta.security.auth.message.config;
 
 import jakarta.security.auth.message.MessageInfo;
 
+/**
+ * Provides configuration information for a JASPIC authentication mechanism. An AuthConfig defines the message layer,
+ * application context, and authentication context ID for a given message, and indicates whether the mechanism is
+ * protected.
+ */
 public interface AuthConfig {
 
+    /**
+     * Returns the message layer for which this configuration applies.
+     *
+     * @return the message layer
+     */
     String getMessageLayer();
 
+    /**
+     * Returns the application context for which this configuration applies.
+     *
+     * @return the application context
+     */
     String getAppContext();
 
+    /**
+     * Determines the authentication context ID for the given message.
+     *
+     * @param messageInfo the message information used to determine the context ID
+     *
+     * @return the authentication context ID, or {@code null} if no context applies
+     */
     String getAuthContextID(MessageInfo messageInfo);
 
+    /**
+     * Refreshes the configuration, reloading any changed settings.
+     */
     void refresh();
 
+    /**
+     * Indicates whether the authentication mechanism is protected, meaning that the configuration data is stored
+     * securely.
+     *
+     * @return {@code true} if the mechanism is protected, {@code false} otherwise
+     */
     boolean isProtected();
 }
diff --git a/java/jakarta/security/auth/message/config/AuthConfigFactory.java b/java/jakarta/security/auth/message/config/AuthConfigFactory.java
index e8f4938ad6..7d56046cf3 100644
--- a/java/jakarta/security/auth/message/config/AuthConfigFactory.java
+++ b/java/jakarta/security/auth/message/config/AuthConfigFactory.java
@@ -21,8 +21,17 @@ import java.util.Map;
 
 import jakarta.security.auth.message.module.ServerAuthModule;
 
+/**
+ * Factory for obtaining and managing {@link AuthConfigProvider} instances. The AuthConfigFactory is responsible for
+ * discovering, registering, and providing configuration providers for JASPIC authentication modules. Use
+ * {@link #getFactory()} to obtain the singleton instance.
+ */
 public abstract class AuthConfigFactory {
 
+    /**
+     * The name of the {@link java.security.Security} property used to specify the AuthConfigFactory implementation
+     * class.
+     */
     public static final String DEFAULT_FACTORY_SECURITY_PROPERTY = "authconfigprovider.factory";
 
     private static final String DEFAULT_JASPI_AUTHCONFIGFACTORYIMPL =
@@ -30,9 +39,19 @@ public abstract class AuthConfigFactory {
 
     private static volatile AuthConfigFactory factory;
 
+    /**
+     * Protected constructor for subclasses.
+     */
     public AuthConfigFactory() {
     }
 
+    /**
+     * Returns the singleton AuthConfigFactory instance. If no instance has been set via {@link #setFactory}, the
+     * factory class is discovered from the {@link java.security.Security} property
+     * {@value #DEFAULT_FACTORY_SECURITY_PROPERTY}, or falls back to a default implementation.
+     *
+     * @return the AuthConfigFactory instance
+     */
     public static AuthConfigFactory getFactory() {
         if (factory != null) {
             return factory;
@@ -61,27 +80,97 @@ public abstract class AuthConfigFactory {
         return factory;
     }
 
+    /**
+     * Programmatically sets the AuthConfigFactory instance. This method is typically used by containers to provide
+     * their own implementation.
+     *
+     * @param factory the AuthConfigFactory instance to set
+     */
     public static synchronized void setFactory(AuthConfigFactory factory) {
         AuthConfigFactory.factory = factory;
     }
 
+    /**
+     * Returns the {@link AuthConfigProvider} for the specified message layer and application context.
+     *
+     * @param layer      the message layer
+     * @param appContext the application context
+     * @param listener   the registration listener to attach
+     *
+     * @return the AuthConfigProvider, or {@code null} if none is available
+     */
     public abstract AuthConfigProvider getConfigProvider(String layer, String appContext,
             RegistrationListener listener);
 
+    /**
+     * Registers an AuthConfigProvider by class name with the given properties.
+     *
+     * @param className  the fully qualified class name of the AuthConfigProvider
+     * @param properties the configuration properties
+     * @param layer      the message layer
+     * @param appContext the application context
+     * @param description a description of the registration
+     *
+     * @return a unique registration ID
+     */
     public abstract String registerConfigProvider(String className, Map<String,String> properties, String layer,
             String appContext, String description);
 
+    /**
+     * Registers an AuthConfigProvider instance.
+     *
+     * @param provider   the AuthConfigProvider to register
+     * @param layer      the message layer
+     * @param appContext the application context
+     * @param description a description of the registration
+     *
+     * @return a unique registration ID
+     */
     public abstract String registerConfigProvider(AuthConfigProvider provider, String layer, String appContext,
             String description);
 
+    /**
+     * Removes a registration by its ID.
+     *
+     * @param registrationID the registration ID to remove
+     *
+     * @return {@code true} if the registration was removed, {@code false} if it did not exist
+     */
     public abstract boolean removeRegistration(String registrationID);
 
+    /**
+     * Detaches a listener from all registrations matching the given layer and application context, returning the
+     * affected registration IDs.
+     *
+     * @param listener   the listener to detach
+     * @param layer      the message layer
+     * @param appContext the application context
+     *
+     * @return an array of registration IDs from which the listener was detached
+     */
     public abstract String[] detachListener(RegistrationListener listener, String layer, String appContext);
 
+    /**
+     * Returns the registration IDs associated with the given AuthConfigProvider.
+     *
+     * @param provider the AuthConfigProvider
+     *
+     * @return an array of registration IDs
+     */
     public abstract String[] getRegistrationIDs(AuthConfigProvider provider);
 
+    /**
+     * Returns the {@link RegistrationContext} for the given registration ID.
+     *
+     * @param registrationID the registration ID
+     *
+     * @return the RegistrationContext, or {@code null} if the ID is not found
+     */
     public abstract RegistrationContext getRegistrationContext(String registrationID);
 
+    /**
+     * Refreshes all registered AuthConfigProviders, causing them to reload their configuration.
+     */
     public abstract void refresh();
 
     /**
@@ -118,14 +207,37 @@ public abstract class AuthConfigFactory {
         return DEFAULT_JASPI_AUTHCONFIGFACTORYIMPL;
     }
 
+    /**
+     * Provides information about a registered {@link AuthConfigProvider}.
+     */
     public interface RegistrationContext {
 
+        /**
+         * Returns the message layer for this registration.
+         *
+         * @return the message layer
+         */
         String getMessageLayer();
 
+        /**
+         * Returns the application context for this registration.
+         *
+         * @return the application context
+         */
         String getAppContext();
 
+        /**
+         * Returns the description of this registration.
+         *
+         * @return the description
+         */
         String getDescription();
 
+        /**
+         * Indicates whether this registration persists beyond the current container lifecycle.
+         *
+         * @return {@code true} if the registration is persistent, {@code false} otherwise
+         */
         boolean isPersistent();
     }
 }
diff --git a/java/jakarta/security/auth/message/config/AuthConfigProvider.java b/java/jakarta/security/auth/message/config/AuthConfigProvider.java
index 66410a7e13..9f42dafd06 100644
--- a/java/jakarta/security/auth/message/config/AuthConfigProvider.java
+++ b/java/jakarta/security/auth/message/config/AuthConfigProvider.java
@@ -20,11 +20,41 @@ import javax.security.auth.callback.CallbackHandler;
 
 import jakarta.security.auth.message.AuthException;
 
+/**
+ * Provides {@link ClientAuthConfig} and {@link ServerAuthConfig} instances to JASPIC authentication modules. An
+ * AuthConfigProvider is responsible for loading authentication configuration from a source (e.g., a configuration
+ * file, database, or service) and making it available to the authentication modules.
+ */
 public interface AuthConfigProvider {
 
+    /**
+     * Returns the client-side authentication configuration for the specified layer and application context.
+     *
+     * @param layer      the message layer
+     * @param appContext the application context
+     * @param handler    the callback handler for obtaining sensitive configuration data
+     *
+     * @return the ClientAuthConfig, or {@code null} if no configuration is available
+     *
+     * @throws AuthException if an error occurs while retrieving the configuration
+     */
     ClientAuthConfig getClientAuthConfig(String layer, String appContext, CallbackHandler handler) throws AuthException;
 
+    /**
+     * Returns the server-side authentication configuration for the specified layer and application context.
+     *
+     * @param layer      the message layer
+     * @param appContext the application context
+     * @param handler    the callback handler for obtaining sensitive configuration data
+     *
+     * @return the ServerAuthConfig, or {@code null} if no configuration is available
+     *
+     * @throws AuthException if an error occurs while retrieving the configuration
+     */
     ServerAuthConfig getServerAuthConfig(String layer, String appContext, CallbackHandler handler) throws AuthException;
 
+    /**
+     * Refreshes the configuration, reloading any changed settings from the underlying source.
+     */
     void refresh();
 }
diff --git a/java/jakarta/security/auth/message/config/ClientAuthConfig.java b/java/jakarta/security/auth/message/config/ClientAuthConfig.java
index f332f0fea6..8c588bda46 100644
--- a/java/jakarta/security/auth/message/config/ClientAuthConfig.java
+++ b/java/jakarta/security/auth/message/config/ClientAuthConfig.java
@@ -22,8 +22,23 @@ import javax.security.auth.Subject;
 
 import jakarta.security.auth.message.AuthException;
 
+/**
+ * Client-side authentication configuration obtained from an {@link AuthConfigProvider}. A ClientAuthConfig provides
+ * the configuration needed to create a {@link ClientAuthContext} for authenticating outbound requests.
+ */
 public interface ClientAuthConfig extends AuthConfig {
 
+    /**
+     * Creates a {@link ClientAuthContext} for the specified authentication context ID.
+     *
+     * @param authContextID the authentication context ID
+     * @param clientSubject the subject representing the client, to be populated upon successful authentication
+     * @param properties    additional configuration properties
+     *
+     * @return the ClientAuthContext, or {@code null} if the authContextID is not recognized
+     *
+     * @throws AuthException if an error occurs while creating the context
+     */
     ClientAuthContext getAuthContext(String authContextID, Subject clientSubject, Map<String,Object> properties)
             throws AuthException;
 }
diff --git a/java/jakarta/security/auth/message/config/ClientAuthContext.java b/java/jakarta/security/auth/message/config/ClientAuthContext.java
index 53280c7822..1c7f95c53b 100644
--- a/java/jakarta/security/auth/message/config/ClientAuthContext.java
+++ b/java/jakarta/security/auth/message/config/ClientAuthContext.java
@@ -18,5 +18,10 @@ package jakarta.security.auth.message.config;
 
 import jakarta.security.auth.message.ClientAuth;
 
+/**
+ * Runtime context for client-side JASPIC authentication. A ClientAuthContext is created by a
+ * {@link ClientAuthConfig} and performs the actual authentication of outbound requests and validation of inbound
+ * responses.
+ */
 public interface ClientAuthContext extends ClientAuth {
 }
diff --git a/java/jakarta/security/auth/message/config/RegistrationListener.java b/java/jakarta/security/auth/message/config/RegistrationListener.java
index 05bec1c163..9c3053660b 100644
--- a/java/jakarta/security/auth/message/config/RegistrationListener.java
+++ b/java/jakarta/security/auth/message/config/RegistrationListener.java
@@ -16,7 +16,16 @@
  */
 package jakarta.security.auth.message.config;
 
+/**
+ * Listener interface for JASPIC registration events.
+ */
 public interface RegistrationListener {
 
+    /**
+     * Notifies the listener of a registration event.
+     *
+     * @param layer the authentication layer
+     * @param appContext the application context
+     */
     void notify(String layer, String appContext);
 }
diff --git a/java/jakarta/security/auth/message/config/ServerAuthConfig.java b/java/jakarta/security/auth/message/config/ServerAuthConfig.java
index a8bc9c728c..f970ea5466 100644
--- a/java/jakarta/security/auth/message/config/ServerAuthConfig.java
+++ b/java/jakarta/security/auth/message/config/ServerAuthConfig.java
@@ -22,8 +22,20 @@ import javax.security.auth.Subject;
 
 import jakarta.security.auth.message.AuthException;
 
+/**
+ * Server-side authentication configuration obtained from an {@link AuthConfigProvider}.
+ */
 public interface ServerAuthConfig extends AuthConfig {
 
+    /**
+     * Returns the {@link ServerAuthContext} for the given authentication context ID.
+     *
+     * @param authContextID the authentication context identifier
+     * @param serviceSubject the service subject
+     * @param properties the configuration properties
+     * @return the server authentication context
+     * @throws AuthException if an error occurs during authentication context creation
+     */
     ServerAuthContext getAuthContext(String authContextID, Subject serviceSubject, Map<String,Object> properties)
             throws AuthException;
 }
diff --git a/java/jakarta/security/auth/message/config/ServerAuthContext.java b/java/jakarta/security/auth/message/config/ServerAuthContext.java
index bbff396988..4c668f7ba5 100644
--- a/java/jakarta/security/auth/message/config/ServerAuthContext.java
+++ b/java/jakarta/security/auth/message/config/ServerAuthContext.java
@@ -18,5 +18,12 @@ package jakarta.security.auth.message.config;
 
 import jakarta.security.auth.message.ServerAuth;
 
+/**
+ * Provides server-side authentication of requests and response signing.
+ * <p>
+ * This interface extends {@link ServerAuth} and is obtained from a
+ * {@link ServerAuthConfig}. It is used by the container to authenticate
+ * incoming requests and secure outgoing responses.
+ */
 public interface ServerAuthContext extends ServerAuth {
 }
diff --git a/java/jakarta/security/auth/message/module/ClientAuthModule.java b/java/jakarta/security/auth/message/module/ClientAuthModule.java
index b0569a462c..ef0d8be7a4 100644
--- a/java/jakarta/security/auth/message/module/ClientAuthModule.java
+++ b/java/jakarta/security/auth/message/module/ClientAuthModule.java
@@ -24,10 +24,31 @@ import jakarta.security.auth.message.AuthException;
 import jakarta.security.auth.message.ClientAuth;
 import jakarta.security.auth.message.MessagePolicy;
 
+/**
+ * A pluggable client-side authentication module in JASPIC. A ClientAuthModule implements the authentication logic
+ * for client-side operations and is initialized with message policies, a callback handler, and configuration
+ * options.
+ */
 public interface ClientAuthModule extends ClientAuth {
 
+    /**
+     * Initializes the authentication module with the given policies, callback handler, and options. This method is
+     * called once when the module is created.
+     *
+     * @param requestPolicy  the message policy for requests
+     * @param responsePolicy the message policy for responses
+     * @param handler        the callback handler for obtaining sensitive data
+     * @param options        configuration options for the module
+     *
+     * @throws AuthException if initialization fails
+     */
     void initialize(MessagePolicy requestPolicy, MessagePolicy responsePolicy, CallbackHandler handler,
             Map<String,Object> options) throws AuthException;
 
+    /**
+     * Returns the array of MessageInfo implementation classes supported by this module.
+     *
+     * @return an array of supported MessageInfo classes
+     */
     Class<?>[] getSupportedMessageTypes();
 }
diff --git a/java/jakarta/security/auth/message/module/ServerAuthModule.java b/java/jakarta/security/auth/message/module/ServerAuthModule.java
index 3518bea61d..66e7297fbb 100644
--- a/java/jakarta/security/auth/message/module/ServerAuthModule.java
+++ b/java/jakarta/security/auth/message/module/ServerAuthModule.java
@@ -24,10 +24,35 @@ import jakarta.security.auth.message.AuthException;
 import jakarta.security.auth.message.MessagePolicy;
 import jakarta.security.auth.message.ServerAuth;
 
+/**
+ * Provides server-side authentication of requests and response signing.
+ * <p>
+ * This interface extends {@link ServerAuth} and is implemented by authentication
+ * module providers. It is initialized by the container and provides the actual
+ * authentication logic for server-side message authentication.
+ */
 public interface ServerAuthModule extends ServerAuth {
 
+    /**
+     * Initialize the authentication module.
+     * <p>
+     * This method is called by the container to initialize the module with the
+     * request and response policies, a callback handler, and a set of options.
+     *
+     * @param requestPolicy  The policy for the request message
+     * @param responsePolicy The policy for the response message
+     * @param handler        The callback handler used to obtain credentials
+     * @param options        The options provided to the module
+     *
+     * @throws AuthException If an error occurs during initialization
+     */
     void initialize(MessagePolicy requestPolicy, MessagePolicy responsePolicy, CallbackHandler handler,
             Map<String,Object> options) throws AuthException;
 
+    /**
+     * Returns the array of message types supported by the module.
+     *
+     * @return The array of supported message type classes
+     */
     Class<?>[] getSupportedMessageTypes();
 }
diff --git a/java/jakarta/servlet/AsyncContext.java b/java/jakarta/servlet/AsyncContext.java
index 7b952e6394..5ba0e7eb53 100644
--- a/java/jakarta/servlet/AsyncContext.java
+++ b/java/jakarta/servlet/AsyncContext.java
@@ -54,21 +54,32 @@ public interface AsyncContext {
     String ASYNC_QUERY_STRING = "jakarta.servlet.async.query_string";
 
     /**
-     * @return a reference to the ServletRequest object
+     * Returns the {@link ServletRequest} associated with this asynchronous operation.
+     *
+     * @return the ServletRequest object
      */
     ServletRequest getRequest();
 
     /**
-     * @return a reference to the ServletResponse object
+     * Returns the {@link ServletResponse} associated with this asynchronous operation.
+     *
+     * @return the ServletResponse object
      */
     ServletResponse getResponse();
 
     /**
-     * @return true if the Request and Response are the original ones
+     * Determines whether the request and response objects are the original ones passed to
+     * {@link jakarta.servlet.http.HttpServletRequest#startAsync()}, or if they are new objects created by the
+     * container.
+     *
+     * @return {@code true} if the request and response are the original objects, {@code false} otherwise
      */
     boolean hasOriginalRequestAndResponse();
 
     /**
+     * Dispatches the request to the resource at the original request URI, as specified in the original request. After
+     * the dispatch, the async request processing is complete and the response is committed.
+     *
      * @throws IllegalStateException if this method is called when the request is not in asynchronous mode. The request
      *                                   is in asynchronous mode after
      *                                   {@link jakarta.servlet.http.HttpServletRequest#startAsync()} or
@@ -79,8 +90,12 @@ public interface AsyncContext {
     void dispatch();
 
     /**
-     * @param path The path to which the request/response should be dispatched relative to the {@link ServletContext}
-     *                 from which this async request was started.
+     * Dispatches the request to the resource at the specified path relative to the {@link ServletContext} from which
+     * this async request was started. After the dispatch, the async request processing is complete and the response
+     * is committed.
+     *
+     * @param path the path to which the request/response should be dispatched relative to the {@link ServletContext}
+     *                 from which this async request was started
      *
      * @throws IllegalStateException if this method is called when the request is not in asynchronous mode. The request
      *                                   is in asynchronous mode after
@@ -92,9 +107,12 @@ public interface AsyncContext {
     void dispatch(String path);
 
     /**
-     * @param path    The path to which the request/response should be dispatched relative to the specified
-     *                    {@link ServletContext}.
-     * @param context The {@link ServletContext} to which the request/response should be dispatched.
+     * Dispatches the request to the resource at the specified path relative to the given {@link ServletContext}.
+     * After the dispatch, the async request processing is complete and the response is committed.
+     *
+     * @param path    the path to which the request/response should be dispatched relative to the specified
+     *                    {@link ServletContext}
+     * @param context the {@link ServletContext} to which the request/response should be dispatched
      *
      * @throws IllegalStateException if this method is called when the request is not in asynchronous mode. The request
      *                                   is in asynchronous mode after
diff --git a/java/jakarta/servlet/GenericFilter.java b/java/jakarta/servlet/GenericFilter.java
index 67b7962d79..ef6b8fb901 100644
--- a/java/jakarta/servlet/GenericFilter.java
+++ b/java/jakarta/servlet/GenericFilter.java
@@ -34,11 +34,18 @@ public abstract class GenericFilter implements Filter, FilterConfig, Serializabl
     @Serial
     private static final long serialVersionUID = 1L;
 
-    /**
-     * The filter configuration.
-     */
+   /**
+      * The filter configuration.
+      */
     private volatile FilterConfig filterConfig;
 
+    /**
+      * Constructs a new GenericFilter.
+      */
+    public GenericFilter() {
+        // NO-OP
+    }
+
 
     @Override
     public String getInitParameter(String name) {
diff --git a/java/jakarta/servlet/HttpConstraintElement.java b/java/jakarta/servlet/HttpConstraintElement.java
index 90e310295c..51b3c41a50 100644
--- a/java/jakarta/servlet/HttpConstraintElement.java
+++ b/java/jakarta/servlet/HttpConstraintElement.java
@@ -89,27 +89,27 @@ public class HttpConstraintElement {
     }
 
     /**
-     * TODO
+     * Returns the empty role semantic for this constraint.
      *
-     * @return TODO
+     * @return The empty role semantic for this constraint
      */
     public EmptyRoleSemantic getEmptyRoleSemantic() {
         return emptyRoleSemantic;
     }
 
     /**
-     * TODO
+     * Returns the transport guarantee for this constraint.
      *
-     * @return TODO
+     * @return The transport guarantee for this constraint
      */
     public TransportGuarantee getTransportGuarantee() {
         return transportGuarantee;
     }
 
     /**
-     * TODO
+     * Returns the roles allowed for this constraint.
      *
-     * @return TODO
+     * @return The roles allowed for this constraint
      */
     public String[] getRolesAllowed() {
         return rolesAllowed;
diff --git a/java/jakarta/servlet/ServletContext.java b/java/jakarta/servlet/ServletContext.java
index 15eba5a3a5..adf8ececdf 100644
--- a/java/jakarta/servlet/ServletContext.java
+++ b/java/jakarta/servlet/ServletContext.java
@@ -551,7 +551,7 @@ public interface ServletContext {
      *
      * @since Servlet 3.0
      */
-    Map<String,? extends ServletRegistration> getServletRegistrations();
+    Map<String, ? extends ServletRegistration> getServletRegistrations();
 
     /**
      * Add filter to context.
@@ -644,11 +644,11 @@ public interface ServletContext {
     <T extends Filter> T createFilter(Class<T> c) throws ServletException;
 
     /**
-     * TODO SERVLET3 - Add comments
+     * Returns the {@link FilterRegistration} for the given filter, or <code>null</code> if no such filter exists.
      *
-     * @param filterName TODO
+     * @param filterName The name of the filter for which to return the registration
      *
-     * @return TODO
+     * @return The {@link FilterRegistration} for the given filter, or <code>null</code> if no such filter exists
      *
      * @throws UnsupportedOperationException If called from a
      *                                           {@link ServletContextListener#contextInitialized(ServletContextEvent)}
@@ -663,7 +663,10 @@ public interface ServletContext {
     FilterRegistration getFilterRegistration(String filterName);
 
     /**
-     * @return TODO
+     * Returns an immutable Map of all the filter registrations for this web application, where the key is the filter
+     * name and the value is the {@link FilterRegistration} object.
+     *
+     * @return An immutable Map of all the filter registrations for this web application
      *
      * @throws UnsupportedOperationException If called from a
      *                                           {@link ServletContextListener#contextInitialized(ServletContextEvent)}
@@ -673,12 +676,15 @@ public interface ServletContext {
      *                                           {@link ServletContextListener} defined in a TLD would not be able to
      *                                           use this method.
      *
-     * @since Servlet 3.0 TODO SERVLET3 - Add comments
+     * @since Servlet 3.0
      */
-    Map<String,? extends FilterRegistration> getFilterRegistrations();
+    Map<String, ? extends FilterRegistration> getFilterRegistrations();
 
     /**
-     * @return TODO
+     * Returns the {@link SessionCookieConfig} object for this web application, which can be used to configure the
+     * session tracking cookie.
+     *
+     * @return The {@link SessionCookieConfig} object for this web application
      *
      * @throws UnsupportedOperationException If called from a
      *                                           {@link ServletContextListener#contextInitialized(ServletContextEvent)}
@@ -688,7 +694,7 @@ public interface ServletContext {
      *                                           {@link ServletContextListener} defined in a TLD would not be able to
      *                                           use this method.
      *
-     * @since Servlet 3.0 TODO SERVLET3 - Add comments
+     * @since Servlet 3.0
      */
     SessionCookieConfig getSessionCookieConfig();
 
@@ -735,10 +741,20 @@ public interface ServletContext {
     Set<SessionTrackingMode> getEffectiveSessionTrackingModes();
 
     /**
-     * TODO SERVLET3 - Add comments
+     * Adds a listener to this web application. The listener instance will be created by the container using the
+     * no-argument constructor of the given class.
      *
-     * @param className TODO
+     * @param className The fully qualified class name of the listener to add
      *
+     * @throws ClassCastException            If the class name does not implement {@link EventListener} or a
+     *                                           subinterface recognized by the servlet container, or if a non-standard
+     *                                           listener type is not packaged in a JAR file with a
+     *                                           <code>listener</code> element in the <code>META-INF/services</code>
+     *                                           directory
+     * @throws IllegalArgumentException      If the lifecycle of a listener prohibits addition at runtime, or if the
+     *                                           class has a {@link jakarta.servlet.annotation.WebListener} annotation
+     *                                           that conflicts with the programmatic addition
+     * @throws IllegalStateException         If the context has already been initialised
      * @throws UnsupportedOperationException If called from a
      *                                           {@link ServletContextListener#contextInitialized(ServletContextEvent)}
      *                                           method of a {@link ServletContextListener} that was not defined in a
@@ -752,11 +768,20 @@ public interface ServletContext {
     void addListener(String className);
 
     /**
-     * TODO SERVLET3 - Add comments
+     * Adds the given listener instance to this web application.
      *
-     * @param <T> TODO
-     * @param t   TODO
+     * @param <T> The type of listener being added
+     * @param t   The listener instance to add
      *
+     * @throws ClassCastException            If the class of the listener instance does not implement
+     *                                           {@link EventListener} or a subinterface recognized by the servlet
+     *                                           container, or if a non-standard listener type is not packaged in a JAR
+     *                                           file with a <code>listener</code> element in the
+     *                                           <code>META-INF/services</code> directory
+     * @throws IllegalArgumentException      If the lifecycle of a listener prohibits addition at runtime, or if the
+     *                                           class has a {@link jakarta.servlet.annotation.WebListener} annotation
+     *                                           that conflicts with the programmatic addition
+     * @throws IllegalStateException         If the context has already been initialised
      * @throws UnsupportedOperationException If called from a
      *                                           {@link ServletContextListener#contextInitialized(ServletContextEvent)}
      *                                           method of a {@link ServletContextListener} that was not defined in a
@@ -770,10 +795,19 @@ public interface ServletContext {
     <T extends EventListener> void addListener(T t);
 
     /**
-     * TODO SERVLET3 - Add comments
+     * Adds a listener to this web application. The listener instance will be created by the container using the
+     * no-argument constructor of the given class.
      *
-     * @param listenerClass TODO
+     * @param listenerClass The class of the listener to add
      *
+     * @throws ClassCastException            If the class does not implement {@link EventListener} or a subinterface
+     *                                           recognized by the servlet container, or if a non-standard listener type
+     *                                           is not packaged in a JAR file with a <code>listener</code> element in
+     *                                           the <code>META-INF/services</code> directory
+     * @throws IllegalArgumentException      If the lifecycle of a listener prohibits addition at runtime, or if the
+     *                                           class has a {@link jakarta.servlet.annotation.WebListener} annotation
+     *                                           that conflicts with the programmatic addition
+     * @throws IllegalStateException         If the context has already been initialised
      * @throws UnsupportedOperationException If called from a
      *                                           {@link ServletContextListener#contextInitialized(ServletContextEvent)}
      *                                           method of a {@link ServletContextListener} that was not defined in a
@@ -787,14 +821,15 @@ public interface ServletContext {
     void addListener(Class<? extends EventListener> listenerClass);
 
     /**
-     * TODO SERVLET3 - Add comments
+     * Creates a new instance of the given listener class, using the web application class loader.
      *
-     * @param <T> TODO
-     * @param c   TODO
+     * @param <T> The type of listener being created
+     * @param c   The class of the listener to create
      *
-     * @return TODO
+     * @return The new listener instance
      *
-     * @throws ServletException              TODO
+     * @throws ServletException              If the listener cannot be instantiated, e.g., if the class does not have a
+     *                                           no-argument constructor, or if instantiation fails for any other reason
      * @throws UnsupportedOperationException If called from a
      *                                           {@link ServletContextListener#contextInitialized(ServletContextEvent)}
      *                                           method of a {@link ServletContextListener} that was not defined in a
@@ -808,9 +843,12 @@ public interface ServletContext {
     <T extends EventListener> T createListener(Class<T> c) throws ServletException;
 
     /**
-     * @return TODO
+     * Returns the {@link JspConfigDescriptor} for this web application, which provides access to the JSP configuration
+     * elements such as taglib and jsp-property-group declarations.
      *
-     * @since Servlet 3.0 TODO SERVLET3 - Add comments
+     * @return The {@link JspConfigDescriptor} for this web application
+     *
+     * @since Servlet 3.0
      */
     JspConfigDescriptor getJspConfigDescriptor();
 
diff --git a/java/jakarta/servlet/ServletRequest.java b/java/jakarta/servlet/ServletRequest.java
index 749a9fc567..dea5715bd0 100644
--- a/java/jakarta/servlet/ServletRequest.java
+++ b/java/jakarta/servlet/ServletRequest.java
@@ -441,54 +441,66 @@ public interface ServletRequest {
     int getLocalPort();
 
     /**
-     * @return TODO
+     * Returns the {@link ServletContext} to which this servlet belongs.
      *
-     * @since Servlet 3.0 TODO SERVLET3 - Add comments
+     * @return the ServletContext associated with this request
+     *
+     * @since Servlet 3.0
      */
     ServletContext getServletContext();
 
     /**
-     * @return TODO
+     * Initiates asynchronous processing for this request. The asynchronous processing is performed using the current
+     * request and response objects.
+     *
+     * @return an {@link AsyncContext} instance for managing the asynchronous processing
      *
-     * @throws IllegalStateException If async is not supported for this request
+     * @throws IllegalStateException if async is not supported for this request
      *
-     * @since Servlet 3.0 TODO SERVLET3 - Add comments
+     * @since Servlet 3.0
      */
     AsyncContext startAsync() throws IllegalStateException;
 
     /**
-     * @param servletRequest  The ServletRequest with which to initialise the asynchronous context
-     * @param servletResponse The ServletResponse with which to initialise the asynchronous context
+     * Initiates asynchronous processing for this request using the specified request and response objects.
+     *
+     * @param servletRequest  the ServletRequest with which to initialise the asynchronous context
+     * @param servletResponse the ServletResponse with which to initialise the asynchronous context
      *
-     * @return TODO
+     * @return an {@link AsyncContext} instance for managing the asynchronous processing
      *
-     * @throws IllegalStateException If async is not supported for this request
+     * @throws IllegalStateException if async is not supported for this request
      *
-     * @since Servlet 3.0 TODO SERVLET3 - Add comments
+     * @since Servlet 3.0
      */
     AsyncContext startAsync(ServletRequest servletRequest, ServletResponse servletResponse)
             throws IllegalStateException;
 
     /**
-     * @return TODO
+     * Returns whether asynchronous processing has been started for this request.
      *
-     * @since Servlet 3.0 TODO SERVLET3 - Add comments
+     * @return {@code true} if asynchronous processing has been started, {@code false} otherwise
+     *
+     * @since Servlet 3.0
      */
     boolean isAsyncStarted();
 
     /**
-     * @return TODO
+     * Returns whether asynchronous processing is supported for this request and has not already been started.
+     *
+     * @return {@code true} if asynchronous processing is supported and has not yet been started, {@code false}
+     *             otherwise
      *
-     * @since Servlet 3.0 TODO SERVLET3 - Add comments
+     * @since Servlet 3.0
      */
     boolean isAsyncSupported();
 
     /**
-     * Get the current AsyncContext.
+     * Returns the current {@link AsyncContext} associated with this request.
      *
-     * @return The current AsyncContext
+     * @return the current AsyncContext
      *
-     * @throws IllegalStateException if the request is not in asynchronous mode (i.e. @link #isAsyncStarted() is
+     * @throws IllegalStateException if the request is not in asynchronous mode (i.e. {@link #isAsyncStarted()} is
      *                                   {@code false})
      *
      * @since Servlet 3.0
@@ -496,9 +508,12 @@ public interface ServletRequest {
     AsyncContext getAsyncContext();
 
     /**
-     * @return TODO
+     * Returns the {@link DispatcherType} that represents the type of dispatch (REQUEST, FORWARD, INCLUDE, ERROR, or
+     * ASYNC) through which this request was initiated.
+     *
+     * @return the DispatcherType for this request
      *
-     * @since Servlet 3.0 TODO SERVLET3 - Add comments
+     * @since Servlet 3.0
      */
     DispatcherType getDispatcherType();
 
diff --git a/java/jakarta/servlet/ServletRequestWrapper.java b/java/jakarta/servlet/ServletRequestWrapper.java
index af003a0cc7..769aa13e3e 100644
--- a/java/jakarta/servlet/ServletRequestWrapper.java
+++ b/java/jakarta/servlet/ServletRequestWrapper.java
@@ -164,7 +164,7 @@ public class ServletRequestWrapper implements ServletRequest {
      * The default behavior of this method is to return getParameterMap() on the wrapped request object.
      */
     @Override
-    public Map<String,String[]> getParameterMap() {
+    public Map<String, String[]> getParameterMap() {
         return this.request.getParameterMap();
     }
 
@@ -400,7 +400,8 @@ public class ServletRequestWrapper implements ServletRequest {
     }
 
     /**
-     * TODO SERVLET3 - Add comments
+     * If the request wrapped by this wrapper, or a wrapper used in the construction of this wrapper, instances the
+     * given request, then return <code>true</code>. Otherwise return <code>false</code>.
      *
      * @param wrapped The request to compare to the wrapped request
      *
@@ -420,7 +421,8 @@ public class ServletRequestWrapper implements ServletRequest {
     }
 
     /**
-     * TODO SERVLET3 - Add comments
+     * If the request wrapped by this wrapper, or a wrapper used in the construction of this wrapper, is an instance of
+     * the type given, then return <code>true</code>. Otherwise return <code>false</code>.
      *
      * @param wrappedType The class to compare to the class of the wrapped request
      *
diff --git a/java/jakarta/servlet/ServletResponseWrapper.java b/java/jakarta/servlet/ServletResponseWrapper.java
index 94c4e5ac01..4f9b2b5c4f 100644
--- a/java/jakarta/servlet/ServletResponseWrapper.java
+++ b/java/jakarta/servlet/ServletResponseWrapper.java
@@ -221,7 +221,8 @@ public class ServletResponseWrapper implements ServletResponse {
     }
 
     /**
-     * TODO SERVLET3 - Add comments
+     * If the response wrapped by this wrapper, or a wrapper used in the construction of this wrapper, instances the
+     * given response, then return <code>true</code>. Otherwise return <code>false</code>.
      *
      * @param wrapped The response to compare to the wrapped response
      *
@@ -241,7 +242,8 @@ public class ServletResponseWrapper implements ServletResponse {
     }
 
     /**
-     * TODO SERVLET3 - Add comments
+     * If the response wrapped by this wrapper, or a wrapper used in the construction of this wrapper, is an instance of
+     * the type given, then return <code>true</code>. Otherwise return <code>false</code>.
      *
      * @param wrappedType The class to compare to the class of the wrapped response
      *
diff --git a/java/jakarta/servlet/annotation/HandlesTypes.java b/java/jakarta/servlet/annotation/HandlesTypes.java
index 7dd52b165c..203340c8b9 100644
--- a/java/jakarta/servlet/annotation/HandlesTypes.java
+++ b/java/jakarta/servlet/annotation/HandlesTypes.java
@@ -31,9 +31,11 @@ import java.lang.annotation.Target;
 @Retention(RetentionPolicy.RUNTIME)
 public @interface HandlesTypes {
 
-    /**
-     * @return array of classes
-     */
+   /**
+      * Declares the classes handled by the {@link jakarta.servlet.ServletContainerInitializer}.
+      *
+      * @return array of classes
+      */
     Class<?>[] value();
 
 }
diff --git a/java/jakarta/servlet/annotation/MultipartConfig.java b/java/jakarta/servlet/annotation/MultipartConfig.java
index 0558b7dfd4..d0538bf954 100644
--- a/java/jakarta/servlet/annotation/MultipartConfig.java
+++ b/java/jakarta/servlet/annotation/MultipartConfig.java
@@ -41,22 +41,31 @@ import java.lang.annotation.Target;
 public @interface MultipartConfig {
 
     /**
+     * Specifies the location in which the Container stores temporary files.
+     *
      * @return location in which the Container stores temporary files
      */
     String location() default "";
 
     /**
+     * Specifies the maximum size allowed for uploaded files.
+     *
      * @return the maximum size allowed for uploaded files (in bytes)
      */
     long maxFileSize() default -1L;
 
     /**
+     * Specifies the maximum size of the request allowed for {@code
+     * multipart/form-data}.
+     *
      * @return the maximum size of the request allowed for {@code
      *         multipart/form-data}
      */
     long maxRequestSize() default -1L;
 
     /**
+     * Specifies the size threshold in bytes after which the file will be written to disk.
+     *
      * @return the size threshold at which the file will be written to the disk
      */
     int fileSizeThreshold() default 0;
diff --git a/java/jakarta/servlet/annotation/WebFilter.java b/java/jakarta/servlet/annotation/WebFilter.java
index a277d43788..d23d9f2b0e 100644
--- a/java/jakarta/servlet/annotation/WebFilter.java
+++ b/java/jakarta/servlet/annotation/WebFilter.java
@@ -50,36 +50,50 @@ import jakarta.servlet.DispatcherType;
 public @interface WebFilter {
 
     /**
+     * Provides a description of the Filter.
+     *
      * @return description of the Filter, if present
      */
     String description() default "";
 
     /**
+     * Provides a display name for the Filter.
+     *
      * @return display name of the Filter, if present
      */
     String displayName() default "";
 
     /**
+     * Declares initialization parameters for the Filter.
+     *
      * @return array of initialization params for this Filter
      */
     WebInitParam[] initParams() default {};
 
     /**
+     * Declares the name of the Filter.
+     *
      * @return name of the Filter, if present
      */
     String filterName() default "";
 
     /**
+     * Provides a small icon for the Filter.
+     *
      * @return small icon for this Filter, if present
      */
     String smallIcon() default "";
 
     /**
+     * Provides a large icon for the Filter.
+     *
      * @return the large icon for this Filter, if present
      */
     String largeIcon() default "";
 
     /**
+     * Declares the servlet names to which this Filter applies.
+     *
      * @return array of Servlet names to which this Filter applies
      */
     String[] servletNames() default {};
@@ -94,17 +108,23 @@ public @interface WebFilter {
     String[] value() default {};
 
     /**
+     * Declares the URL patterns to which this Filter applies.
+     *
      * @return array of URL patterns to which this Filter applies
      */
     String[] urlPatterns() default {};
 
     /**
+     * Declares the dispatcher types to which this Filter applies.
+     *
      * @return array of DispatcherTypes to which this filter applies
      */
     DispatcherType[] dispatcherTypes() default { DispatcherType.REQUEST };
 
     /**
-     * @return asynchronous operation supported by this Filter
+     * Declares whether asynchronous operation is supported by this Filter.
+     *
+     * @return {@code true} if asynchronous operation is supported, {@code false} otherwise
      */
     boolean asyncSupported() default false;
 }
diff --git a/java/jakarta/servlet/annotation/WebInitParam.java b/java/jakarta/servlet/annotation/WebInitParam.java
index feb4bf901b..d541fa7cff 100644
--- a/java/jakarta/servlet/annotation/WebInitParam.java
+++ b/java/jakarta/servlet/annotation/WebInitParam.java
@@ -39,16 +39,22 @@ import java.lang.annotation.Target;
 public @interface WebInitParam {
 
     /**
+     * The name of the initialization parameter.
+     *
      * @return name of the initialization parameter
      */
     String name();
 
     /**
+     * The value of the initialization parameter.
+     *
      * @return value of the initialization parameter
      */
     String value();
 
     /**
+     * A description of the initialization parameter.
+     *
      * @return description of the initialization parameter
      */
     String description() default "";
diff --git a/java/jakarta/servlet/annotation/WebListener.java b/java/jakarta/servlet/annotation/WebListener.java
index aee671b4fa..d01a2d658d 100644
--- a/java/jakarta/servlet/annotation/WebListener.java
+++ b/java/jakarta/servlet/annotation/WebListener.java
@@ -41,6 +41,8 @@ import java.lang.annotation.Target;
 public @interface WebListener {
 
     /**
+     * Provides a description of the listener.
+     *
      * @return description of the listener, if present
      */
     String value() default "";
diff --git a/java/jakarta/servlet/annotation/WebServlet.java b/java/jakarta/servlet/annotation/WebServlet.java
index 5e1334bd1e..ed12b5b1a3 100644
--- a/java/jakarta/servlet/annotation/WebServlet.java
+++ b/java/jakarta/servlet/annotation/WebServlet.java
@@ -46,57 +46,75 @@ import java.lang.annotation.Target;
 @Documented
 public @interface WebServlet {
 
-    /**
-     * @return name of the Servlet
-     */
+   /**
+      * Provides the name of this servlet.
+      *
+      * @return name of the Servlet
+      */
     String name() default "";
 
-    /**
-     * A convenience method, to allow extremely simple annotation of a class.
-     *
-     * @return array of URL patterns
-     *
-     * @see #urlPatterns()
-     */
+      /**
+       * A convenience method, to allow extremely simple annotation of a class.
+       *
+       * @return array of URL patterns
+       *
+       * @see #urlPatterns()
+       */
     String[] value() default {};
 
-    /**
-     * @return array of URL patterns to which this Filter applies
-     */
+      /**
+       * Declares the URL patterns for this servlet.
+       *
+       * @return array of URL patterns to which this Servlet applies
+       */
     String[] urlPatterns() default {};
 
-    /**
-     * @return load on startup ordering hint
-     */
+      /**
+       * Provides a load-on-startup ordering hint for this servlet.
+       *
+       * @return load on startup ordering hint
+       */
     int loadOnStartup() default -1;
 
-    /**
-     * @return array of initialization params for this Servlet
-     */
+      /**
+       * Declares initialization parameters for this servlet.
+       *
+       * @return array of initialization params for this Servlet
+       */
     WebInitParam[] initParams() default {};
 
-    /**
-     * @return asynchronous operation supported by this Servlet
-     */
+      /**
+       * Indicates whether this servlet supports asynchronous operation.
+       *
+       * @return asynchronous operation supported by this Servlet
+       */
     boolean asyncSupported() default false;
 
-    /**
-     * @return small icon for this Servlet, if present
-     */
+      /**
+       * Provides the URL of a small icon for this servlet.
+       *
+       * @return small icon for this Servlet, if present
+       */
     String smallIcon() default "";
 
-    /**
-     * @return large icon for this Servlet, if present
-     */
+      /**
+       * Provides the URL of a large icon for this servlet.
+       *
+       * @return large icon for this Servlet, if present
+       */
     String largeIcon() default "";
 
-    /**
-     * @return description of this Servlet, if present
-     */
+      /**
+       * Provides a description of this servlet.
+       *
+       * @return description of this Servlet, if present
+       */
     String description() default "";
 
-    /**
-     * @return display name of this Servlet, if present
-     */
+      /**
+       * Provides a display name for this servlet.
+       *
+       * @return display name of this Servlet, if present
+       */
     String displayName() default "";
 }
diff --git a/java/jakarta/servlet/http/HttpFilter.java b/java/jakarta/servlet/http/HttpFilter.java
index a4cbf8208a..85070f9f58 100644
--- a/java/jakarta/servlet/http/HttpFilter.java
+++ b/java/jakarta/servlet/http/HttpFilter.java
@@ -34,6 +34,13 @@ public abstract class HttpFilter extends GenericFilter {
     @Serial
     private static final long serialVersionUID = 1L;
 
+    /**
+      * Constructs a new HttpFilter.
+      */
+    public HttpFilter() {
+        // NO-OP
+    }
+
     /**
      * {@inheritDoc} This implementation tests the request and response to see if they are instances of
      * {@link HttpServletRequest} and {@link HttpServletResponse} respectively. If they are then they are passed to
diff --git a/java/jakarta/servlet/http/HttpServletMapping.java b/java/jakarta/servlet/http/HttpServletMapping.java
index ae88d321de..aece46c8e8 100644
--- a/java/jakarta/servlet/http/HttpServletMapping.java
+++ b/java/jakarta/servlet/http/HttpServletMapping.java
@@ -25,25 +25,33 @@ import jakarta.servlet.annotation.WebServlet;
  */
 public interface HttpServletMapping {
 
-    /**
-     * @return The value that was matched or the empty String if not known.
-     */
+   /**
+      * Returns the value that was matched when mapping the request to the servlet.
+      *
+      * @return The value that was matched or the empty String if not known.
+      */
     String getMatchValue();
 
-    /**
-     * @return The {@code url-pattern} that matched this request or the empty String if not known.
-     */
+      /**
+       * Returns the URL pattern that matched this request.
+       *
+       * @return The {@code url-pattern} that matched this request or the empty String if not known.
+       */
     String getPattern();
 
-    /**
-     * @return The name of the servlet (as specified in web.xml, {@link WebServlet#name()},
-     *             {@link jakarta.servlet.ServletContext#addServlet(String, Class)} or one of the other
-     *             <code>addServlet()</code> methods) that the request was mapped to.
-     */
+      /**
+       * Returns the name of the servlet to which the request was mapped.
+       *
+       * @return The name of the servlet (as specified in web.xml, {@link WebServlet#name()},
+       *             {@link jakarta.servlet.ServletContext#addServlet(String, Class)} or one of the other
+       *             <code>addServlet()</code> methods) that the request was mapped to.
+       */
     String getServletName();
 
-    /**
-     * @return The type of match ({@code null} if not known)
-     */
+      /**
+       * Returns the type of match used to map the request to the servlet.
+       *
+       * @return The type of match ({@code null} if not known)
+       */
     MappingMatch getMappingMatch();
 }
diff --git a/java/jakarta/servlet/http/PushBuilder.java b/java/jakarta/servlet/http/PushBuilder.java
index 46c6ed72bc..0adbda4a69 100644
--- a/java/jakarta/servlet/http/PushBuilder.java
+++ b/java/jakarta/servlet/http/PushBuilder.java
@@ -156,12 +156,16 @@ public interface PushBuilder {
     String getSessionId();
 
     /**
+     * Returns the set of names of HTTP headers that will be used the next time {@code push()} is called.
+     *
      * @return The current set of names of HTTP headers to be used the next time {@code push()} is called.
      */
     Set<String> getHeaderNames();
 
     /**
-     * Obtain a value for the given HTTP header. TODO Servlet 4.0 Clarify the behaviour of this method
+     * Obtain a value for the given HTTP header. If the push builder has not had this header set, the return value is
+     * <code>null</code>. If the push builder has had this header set multiple times, the value returned is
+     * implementation-specific.
      *
      * @param name The name of the header whose value is to be returned
      *
diff --git a/java/jakarta/transaction/HeuristicCommitException.java b/java/jakarta/transaction/HeuristicCommitException.java
index 1c56f380d8..8f1e2e63a6 100644
--- a/java/jakarta/transaction/HeuristicCommitException.java
+++ b/java/jakarta/transaction/HeuristicCommitException.java
@@ -18,15 +18,29 @@ package jakarta.transaction;
 
 import java.io.Serial;
 
+/**
+ * Thrown when a transaction has been heuristically committed. A heuristic
+ * commit indicates that the transaction manager has committed the transaction
+ * without full agreement from all resource managers, typically as a result of
+ * a failure during the commit process.
+ */
 public class HeuristicCommitException extends Exception {
 
     @Serial
     private static final long serialVersionUID = -3977609782149921760L;
 
+    /**
+     * Constructs a {@code HeuristicCommitException} with no detail message.
+     */
     public HeuristicCommitException() {
         super();
     }
 
+    /**
+     * Constructs a {@code HeuristicCommitException} with the specified detail message.
+     *
+     * @param msg the detail message
+     */
     public HeuristicCommitException(String msg) {
         super(msg);
     }
diff --git a/java/jakarta/transaction/HeuristicMixedException.java b/java/jakarta/transaction/HeuristicMixedException.java
index 50b86867a3..fbc2a93eff 100644
--- a/java/jakarta/transaction/HeuristicMixedException.java
+++ b/java/jakarta/transaction/HeuristicMixedException.java
@@ -18,15 +18,29 @@ package jakarta.transaction;
 
 import java.io.Serial;
 
+/**
+ * Thrown when a transaction has been heuristically committed in part and
+ * heuristically rolled back in part. A heuristic mixed result indicates that
+ * some resource managers committed the transaction while others rolled it
+ * back, typically as a result of a failure during the commit process.
+ */
 public class HeuristicMixedException extends Exception {
 
     @Serial
     private static final long serialVersionUID = 2345014349685956666L;
 
+    /**
+     * Constructs a {@code HeuristicMixedException} with no detail message.
+     */
     public HeuristicMixedException() {
         super();
     }
 
+    /**
+     * Constructs a {@code HeuristicMixedException} with the specified detail message.
+     *
+     * @param msg the detail message
+     */
     public HeuristicMixedException(String msg) {
         super(msg);
     }
diff --git a/java/jakarta/transaction/HeuristicRollbackException.java b/java/jakarta/transaction/HeuristicRollbackException.java
index 2ee7cc6bf5..0aa897539b 100644
--- a/java/jakarta/transaction/HeuristicRollbackException.java
+++ b/java/jakarta/transaction/HeuristicRollbackException.java
@@ -18,15 +18,29 @@ package jakarta.transaction;
 
 import java.io.Serial;
 
+/**
+ * Thrown when a transaction has been heuristically rolled back. A heuristic
+ * rollback indicates that the transaction manager has rolled back the
+ * transaction without full agreement from all resource managers, typically
+ * as a result of a failure during the commit process.
+ */
 public class HeuristicRollbackException extends Exception {
 
     @Serial
     private static final long serialVersionUID = -3483618944556408897L;
 
+    /**
+     * Constructs a {@code HeuristicRollbackException} with no detail message.
+     */
     public HeuristicRollbackException() {
         super();
     }
 
+    /**
+     * Constructs a {@code HeuristicRollbackException} with the specified detail message.
+     *
+     * @param msg the detail message
+     */
     public HeuristicRollbackException(String msg) {
         super(msg);
     }
diff --git a/java/jakarta/transaction/InvalidTransactionException.java b/java/jakarta/transaction/InvalidTransactionException.java
index 97e0476ab1..d8b1e12ce6 100644
--- a/java/jakarta/transaction/InvalidTransactionException.java
+++ b/java/jakarta/transaction/InvalidTransactionException.java
@@ -18,15 +18,28 @@ package jakarta.transaction;
 
 import java.io.Serial;
 
+/**
+ * Thrown when a transaction is invalid. This exception indicates that the
+ * transaction on which an operation was attempted is no longer valid, for
+ * example because it has already completed or been rolled back.
+ */
 public class InvalidTransactionException extends java.rmi.RemoteException {
 
     @Serial
     private static final long serialVersionUID = 3597320220337691496L;
 
+    /**
+     * Constructs an {@code InvalidTransactionException} with no detail message.
+     */
     public InvalidTransactionException() {
         super();
     }
 
+    /**
+     * Constructs an {@code InvalidTransactionException} with the specified detail message.
+     *
+     * @param msg the detail message
+     */
     public InvalidTransactionException(String msg) {
         super(msg);
     }
diff --git a/java/jakarta/transaction/NotSupportedException.java b/java/jakarta/transaction/NotSupportedException.java
index 073ce36240..263a44f852 100644
--- a/java/jakarta/transaction/NotSupportedException.java
+++ b/java/jakarta/transaction/NotSupportedException.java
@@ -18,15 +18,26 @@ package jakarta.transaction;
 
 import java.io.Serial;
 
+/**
+ * Thrown when a requested operation is not supported.
+ */
 public class NotSupportedException extends Exception {
 
     @Serial
     private static final long serialVersionUID = 56870312332816390L;
 
+    /**
+     * Constructs a {@code NotSupportedException} with no detail message.
+     */
     public NotSupportedException() {
         super();
     }
 
+    /**
+     * Constructs a {@code NotSupportedException} with the specified detail message.
+     *
+     * @param msg the detail message
+     */
     public NotSupportedException(String msg) {
         super(msg);
     }
diff --git a/java/jakarta/transaction/RollbackException.java b/java/jakarta/transaction/RollbackException.java
index f0b1d0b887..7b6beb84be 100644
--- a/java/jakarta/transaction/RollbackException.java
+++ b/java/jakarta/transaction/RollbackException.java
@@ -18,15 +18,26 @@ package jakarta.transaction;
 
 import java.io.Serial;
 
+/**
+ * Thrown when a transaction must be rolled back.
+ */
 public class RollbackException extends Exception {
 
     @Serial
     private static final long serialVersionUID = 4151607774785285395L;
 
+    /**
+     * Constructs a {@code RollbackException} with no detail message.
+     */
     public RollbackException() {
         super();
     }
 
+    /**
+     * Constructs a {@code RollbackException} with the specified detail message.
+     *
+     * @param msg the detail message
+     */
     public RollbackException(String msg) {
         super(msg);
     }
diff --git a/java/jakarta/transaction/Status.java b/java/jakarta/transaction/Status.java
index 9b113fc406..d05176b77f 100644
--- a/java/jakarta/transaction/Status.java
+++ b/java/jakarta/transaction/Status.java
@@ -16,15 +16,48 @@
  */
 package jakarta.transaction;
 
+/**
+ * Defines the set of status constants for a transaction.
+ */
 public interface Status {
+    /**
+     * The transaction is active and work is in progress.
+     */
     int STATUS_ACTIVE = 0;
+    /**
+     * The transaction has been marked for rollback only.
+     */
     int STATUS_MARKED_ROLLBACK = 1;
+    /**
+     * The transaction resources have been prepared and are awaiting completion.
+     */
     int STATUS_PREPARED = 2;
+    /**
+     * The transaction has been committed successfully.
+     */
     int STATUS_COMMITTED = 3;
+    /**
+     * The transaction has been rolled back.
+     */
     int STATUS_ROLLEDBACK = 4;
+    /**
+     * The transaction status is unknown.
+     */
     int STATUS_UNKNOWN = 5;
+    /**
+     * There is no active transaction for the current thread.
+     */
     int STATUS_NO_TRANSACTION = 6;
+    /**
+     * The transaction manager is in the process of preparing the transaction resources.
+     */
     int STATUS_PREPARING = 7;
+    /**
+     * The transaction manager is in the process of committing the transaction.
+     */
     int STATUS_COMMITTING = 8;
+    /**
+     * The transaction manager is in the process of rolling back the transaction.
+     */
     int STATUS_ROLLING_BACK = 9;
 }
diff --git a/java/jakarta/transaction/Synchronization.java b/java/jakarta/transaction/Synchronization.java
index b188911cda..c9b20d0555 100644
--- a/java/jakarta/transaction/Synchronization.java
+++ b/java/jakarta/transaction/Synchronization.java
@@ -16,8 +16,25 @@
  */
 package jakarta.transaction;
 
+/**
+ * Callback interface for notification of transaction completion.
+ * Registered with a transaction so that the implementing object is
+ * notified when the transaction is about to complete and when it has
+ * completed.
+ */
 public interface Synchronization {
+    /**
+     * Called before the transaction is committed or rolled back.
+     * This method is invoked after all work on the transaction has
+     * been completed but before the commit or rollback is performed.
+     */
     void beforeCompletion();
 
+    /**
+     * Called after the transaction has completed.
+     *
+     * @param status the status of the transaction, one of the
+     *               {@link Status} constants
+     */
     void afterCompletion(int status);
 }
diff --git a/java/jakarta/transaction/SystemException.java b/java/jakarta/transaction/SystemException.java
index 5c3bd33492..9b9a71d424 100644
--- a/java/jakarta/transaction/SystemException.java
+++ b/java/jakarta/transaction/SystemException.java
@@ -18,21 +18,42 @@ package jakarta.transaction;
 
 import java.io.Serial;
 
+/**
+ * Thrown to indicate a system error during transaction processing.
+ * When this exception is thrown, the state of the transaction is
+ * unknown and may need to be rolled back.
+ */
 public class SystemException extends Exception {
 
     @Serial
     private static final long serialVersionUID = 8615483418828223571L;
 
+    /**
+     * The error code associated with this exception.
+     */
     public int errorCode;
 
+    /**
+     * Constructs a {@code SystemException} with no detail message.
+     */
     public SystemException() {
         super();
     }
 
+    /**
+     * Constructs a {@code SystemException} with the specified detail message.
+     *
+     * @param s the detail message
+     */
     public SystemException(String s) {
         super(s);
     }
 
+    /**
+     * Constructs a {@code SystemException} with the specified error code.
+     *
+     * @param errcode the error code
+     */
     public SystemException(int errcode) {
         super();
         errorCode = errcode;
diff --git a/java/jakarta/transaction/Transaction.java b/java/jakarta/transaction/Transaction.java
index 1f031d2a8b..626786afa8 100644
--- a/java/jakarta/transaction/Transaction.java
+++ b/java/jakarta/transaction/Transaction.java
@@ -18,21 +18,84 @@ package jakarta.transaction;
 
 import javax.transaction.xa.XAResource;
 
+/**
+ * Represents an active transaction.
+ * Provides methods for committing, rolling back, and managing
+ * resources enlisted in the transaction.
+ */
 public interface Transaction {
 
+    /**
+     * Commits the transaction.
+     *
+     * @throws RollbackException if the transaction has been marked for rollback only
+     * @throws HeuristicMixedException if the transaction was heuristically
+     *         partitioned, with some resources committed and others rolled back
+     * @throws HeuristicRollbackException if the transaction was heuristically rolled back
+     * @throws SecurityException if the caller is not authorized to commit
+     * @throws IllegalStateException if the transaction is not active
+     * @throws SystemException if a system error occurred
+     */
     void commit() throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SecurityException,
             IllegalStateException, SystemException;
 
+    /**
+     * Delists the specified XA resource from this transaction.
+     *
+     * @param xaRes the XA resource to delist
+     * @param flag one of {@code TMSUCCESS}, {@code TMFAIL}, or {@code TMSTARTEPOCH}
+     * @return {@code true} if the resource was delisted, {@code false} otherwise
+     * @throws IllegalStateException if the transaction is not active
+     * @throws SystemException if a system error occurred
+     */
     boolean delistResource(XAResource xaRes, int flag) throws IllegalStateException, SystemException;
 
+    /**
+     * Enlists the specified XA resource with this transaction.
+     *
+     * @param xaRes the XA resource to enlist
+     *
+     * @return {@code true} if the resource was enlisted, {@code false} otherwise
+     *
+     * @throws RollbackException if the transaction has been marked for rollback only
+     * @throws IllegalStateException if the transaction is not active or the
+     *         resource is already enlisted
+     * @throws SystemException if a system error occurred
+     */
     boolean enlistResource(XAResource xaRes) throws RollbackException, IllegalStateException, SystemException;
 
+    /**
+     * Returns the status of this transaction.
+     *
+     * @return the transaction status, one of the {@link Status} constants
+     * @throws SystemException if a system error occurred
+     */
     int getStatus() throws SystemException;
 
+    /**
+     * Registers a synchronization callback with this transaction.
+     *
+     * @param sync the synchronization callback to register
+     * @throws RollbackException if the transaction has been marked for rollback only
+     * @throws IllegalStateException if the transaction is not active
+     * @throws SystemException if a system error occurred
+     */
     void registerSynchronization(Synchronization sync) throws RollbackException, IllegalStateException, SystemException;
 
+    /**
+     * Rolls back the transaction.
+     *
+     * @throws IllegalStateException if the transaction is not active
+     * @throws SystemException if a system error occurred
+     */
     void rollback() throws IllegalStateException, SystemException;
 
+    /**
+     * Marks this transaction so that the only valid outcome is a rollback.
+     *
+     * @throws IllegalStateException if the transaction is not active
+     * @throws SystemException if a system error occurred
+     */
     void setRollbackOnly() throws IllegalStateException, SystemException;
 
 }
diff --git a/java/jakarta/transaction/TransactionManager.java b/java/jakarta/transaction/TransactionManager.java
index 2bd58e16c8..633b3775ca 100644
--- a/java/jakarta/transaction/TransactionManager.java
+++ b/java/jakarta/transaction/TransactionManager.java
@@ -16,23 +16,91 @@
  */
 package jakarta.transaction;
 
+/**
+ * Provides methods for managing transactions.
+ * Used by the transaction manager to begin, commit, and roll back
+ * transactions, and to suspend and resume them.
+ */
 public interface TransactionManager {
+    /**
+     * Begins a new transaction for the current thread.
+     *
+     * @throws NotSupportedException if the transaction manager does not
+     *         support transactions
+     * @throws SystemException if a system error occurred
+     */
     void begin() throws NotSupportedException, SystemException;
 
+    /**
+     * Commits the transaction associated with the current thread.
+     *
+     * @throws RollbackException if the transaction has been marked for rollback only
+     * @throws HeuristicMixedException if the transaction was heuristically
+     *         partitioned
+     * @throws HeuristicRollbackException if the transaction was heuristically rolled back
+     * @throws SecurityException if the caller is not authorized to commit
+     * @throws IllegalStateException if no transaction is active
+     * @throws SystemException if a system error occurred
+     */
     void commit() throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SecurityException,
             IllegalStateException, SystemException;
 
+    /**
+     * Returns the status of the transaction associated with the current thread.
+     *
+     * @return the transaction status, one of the {@link Status} constants
+     * @throws SystemException if a system error occurred
+     */
     int getStatus() throws SystemException;
 
+    /**
+     * Returns the {@link Transaction} object associated with the current thread.
+     *
+     * @return the current transaction, or {@code null} if there is no active transaction
+     * @throws SystemException if a system error occurred
+     */
     Transaction getTransaction() throws SystemException;
 
+    /**
+     * Resumes a previously suspended transaction for the current thread.
+     *
+     * @param tobj the transaction to resume
+     * @throws InvalidTransactionException if the transaction is no longer valid
+     * @throws IllegalStateException if there is already an active transaction
+     * @throws SystemException if a system error occurred
+     */
     void resume(Transaction tobj) throws InvalidTransactionException, IllegalStateException, SystemException;
 
+    /**
+     * Rolls back the transaction associated with the current thread.
+     *
+     * @throws IllegalStateException if no transaction is active
+     * @throws SecurityException if the caller is not authorized to roll back
+     * @throws SystemException if a system error occurred
+     */
     void rollback() throws IllegalStateException, SecurityException, SystemException;
 
+    /**
+     * Marks the current transaction so that the only valid outcome is a rollback.
+     *
+     * @throws IllegalStateException if no transaction is active
+     * @throws SystemException if a system error occurred
+     */
     void setRollbackOnly() throws IllegalStateException, SystemException;
 
+    /**
+     * Sets the default transaction timeout.
+     *
+     * @param seconds the timeout value in seconds
+     * @throws SystemException if a system error occurred
+     */
     void setTransactionTimeout(int seconds) throws SystemException;
 
+    /**
+     * Suspends the transaction associated with the current thread.
+     *
+     * @return the suspended transaction, or {@code null} if there was no active transaction
+     * @throws SystemException if a system error occurred
+     */
     Transaction suspend() throws SystemException;
 }
diff --git a/java/jakarta/transaction/TransactionRequiredException.java b/java/jakarta/transaction/TransactionRequiredException.java
index 32d7aef467..be6a2a6c1c 100644
--- a/java/jakarta/transaction/TransactionRequiredException.java
+++ b/java/jakarta/transaction/TransactionRequiredException.java
@@ -18,15 +18,26 @@ package jakarta.transaction;
 
 import java.io.Serial;
 
+/**
+ * Thrown when an operation requires an active transaction but none exists.
+ */
 public class TransactionRequiredException extends java.rmi.RemoteException {
 
     @Serial
     private static final long serialVersionUID = -1898806419937446439L;
 
+    /**
+     * Constructs a {@code TransactionRequiredException} with no detail message.
+     */
     public TransactionRequiredException() {
         super();
     }
 
+    /**
+     * Constructs a {@code TransactionRequiredException} with the specified detail message.
+     *
+     * @param msg the detail message
+     */
     public TransactionRequiredException(String msg) {
         super(msg);
     }
diff --git a/java/jakarta/transaction/TransactionRolledbackException.java b/java/jakarta/transaction/TransactionRolledbackException.java
index 3195c429e1..12bf91627a 100644
--- a/java/jakarta/transaction/TransactionRolledbackException.java
+++ b/java/jakarta/transaction/TransactionRolledbackException.java
@@ -18,15 +18,26 @@ package jakarta.transaction;
 
 import java.io.Serial;
 
+/**
+ * Thrown when an operation is attempted on a transaction that has been rolled back.
+ */
 public class TransactionRolledbackException extends java.rmi.RemoteException {
 
     @Serial
     private static final long serialVersionUID = -3142798139623020577L;
 
+    /**
+     * Constructs a {@code TransactionRolledbackException} with no detail message.
+     */
     public TransactionRolledbackException() {
         super();
     }
 
+    /**
+     * Constructs a {@code TransactionRolledbackException} with the specified detail message.
+     *
+     * @param msg the detail message
+     */
     public TransactionRolledbackException(String msg) {
         super(msg);
     }
diff --git a/java/jakarta/transaction/TransactionSynchronizationRegistry.java b/java/jakarta/transaction/TransactionSynchronizationRegistry.java
index b2ac98f3e2..1332cb07f0 100644
--- a/java/jakarta/transaction/TransactionSynchronizationRegistry.java
+++ b/java/jakarta/transaction/TransactionSynchronizationRegistry.java
@@ -16,18 +16,58 @@
  */
 package jakarta.transaction;
 
+/**
+ * Provides a resource and transaction registry for resource managers.
+ * Allows resource managers to associate resources with the current
+ * transaction and register synchronization callbacks.
+ */
 public interface TransactionSynchronizationRegistry {
+    /**
+     * Returns the unique key identifying the current transaction.
+     *
+     * @return the transaction key, or {@code null} if there is no active transaction
+     */
     Object getTransactionKey();
 
+    /**
+     * Associates a resource with the given key in the current transaction context.
+     *
+     * @param key the key to associate with the resource
+     * @param value the resource object to associate
+     */
     void putResource(Object key, Object value);
 
+    /**
+     * Returns the resource associated with the given key in the current transaction context.
+     *
+     * @param key the key of the resource to retrieve
+     * @return the associated resource, or {@code null} if no resource is found
+     */
     Object getResource(Object key);
 
+    /**
+     * Registers an interposed synchronization callback with the current transaction.
+     *
+     * @param sync the synchronization callback to register
+     */
     void registerInterposedSynchronization(Synchronization sync);
 
+    /**
+     * Returns the status of the current transaction.
+     *
+     * @return the transaction status, one of the {@link Status} constants
+     */
     int getTransactionStatus();
 
+    /**
+     * Marks the current transaction so that the only valid outcome is a rollback.
+     */
     void setRollbackOnly();
 
+    /**
+     * Returns whether the current transaction has been marked for rollback only.
+     *
+     * @return {@code true} if the transaction is marked for rollback only
+     */
     boolean getRollbackOnly();
 }
diff --git a/java/jakarta/transaction/UserTransaction.java b/java/jakarta/transaction/UserTransaction.java
index 0506c9c102..04c558c0a4 100644
--- a/java/jakarta/transaction/UserTransaction.java
+++ b/java/jakarta/transaction/UserTransaction.java
@@ -16,17 +16,64 @@
  */
 package jakarta.transaction;
 
+/**
+ * Provides methods for managing user transactions.
+ * Allows application code to demarcate transaction boundaries explicitly.
+ */
 public interface UserTransaction {
+    /**
+     * Begins a new transaction for the current thread.
+     *
+     * @throws NotSupportedException if the transaction manager does not
+     *         support transactions
+     * @throws SystemException if a system error occurred
+     */
     void begin() throws NotSupportedException, SystemException;
 
+    /**
+     * Commits the transaction associated with the current thread.
+     *
+     * @throws RollbackException if the transaction has been marked for rollback only
+     * @throws HeuristicMixedException if the transaction was heuristically
+     *         partitioned
+     * @throws HeuristicRollbackException if the transaction was heuristically rolled back
+     * @throws SecurityException if the caller is not authorized to commit
+     * @throws IllegalStateException if no transaction is active
+     * @throws SystemException if a system error occurred
+     */
     void commit() throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SecurityException,
             IllegalStateException, SystemException;
 
+    /**
+     * Rolls back the transaction associated with the current thread.
+     *
+     * @throws IllegalStateException if no transaction is active
+     * @throws SecurityException if the caller is not authorized to roll back
+     * @throws SystemException if a system error occurred
+     */
     void rollback() throws IllegalStateException, SecurityException, SystemException;
 
+    /**
+     * Marks the current transaction so that the only valid outcome is a rollback.
+     *
+     * @throws IllegalStateException if no transaction is active
+     * @throws SystemException if a system error occurred
+     */
     void setRollbackOnly() throws IllegalStateException, SystemException;
 
+    /**
+     * Returns the status of the transaction associated with the current thread.
+     *
+     * @return the transaction status, one of the {@link Status} constants
+     * @throws SystemException if a system error occurred
+     */
     int getStatus() throws SystemException;
 
+    /**
+     * Sets the default transaction timeout.
+     *
+     * @param seconds the timeout value in seconds
+     * @throws SystemException if a system error occurred
+     */
     void setTransactionTimeout(int seconds) throws SystemException;
 }
diff --git a/java/jakarta/websocket/ClientEndpoint.java b/java/jakarta/websocket/ClientEndpoint.java
index acaa160cc8..6cfa8cbaa6 100644
--- a/java/jakarta/websocket/ClientEndpoint.java
+++ b/java/jakarta/websocket/ClientEndpoint.java
@@ -23,14 +23,39 @@ import java.lang.annotation.Target;
 
 import jakarta.websocket.ClientEndpointConfig.Configurator;
 
+/**
+ * Annotates a class as a WebSocket client endpoint. The annotation provides configuration
+ * information about the endpoint such as subprotocols, encoders, decoders, and configurator.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 public @interface ClientEndpoint {
+
+    /**
+     * The sub-protocols that this client endpoint supports, in order of preference.
+     *
+     * @return The list of preferred sub-protocols
+     */
     String[] subprotocols() default {};
 
+    /**
+     * The decoder classes that this client endpoint uses.
+     *
+     * @return The list of decoder classes
+     */
     Class<? extends Decoder>[] decoders() default {};
 
+    /**
+     * The encoder classes that this client endpoint uses.
+     *
+     * @return The list of encoder classes
+     */
     Class<? extends Encoder>[] encoders() default {};
 
+    /**
+     * The configurator class used to customize the WebSocket handshake.
+     *
+     * @return The configurator class
+     */
     Class<? extends Configurator> configurator() default Configurator.class;
 }
diff --git a/java/jakarta/websocket/ClientEndpointConfig.java b/java/jakarta/websocket/ClientEndpointConfig.java
index 2af1f41575..05216b11e9 100644
--- a/java/jakarta/websocket/ClientEndpointConfig.java
+++ b/java/jakarta/websocket/ClientEndpointConfig.java
@@ -22,22 +22,53 @@ import java.util.Map;
 
 import javax.net.ssl.SSLContext;
 
+/**
+ * Provides configuration information for WebSocket client endpoints.
+ */
 public interface ClientEndpointConfig extends EndpointConfig {
 
+    /**
+     * Returns the list of sub-protocols that this client endpoint supports, in order of preference.
+     *
+     * @return The list of preferred sub-protocols
+     */
     List<String> getPreferredSubprotocols();
 
+    /**
+     * Returns the list of extensions that this client endpoint supports.
+     *
+     * @return The list of supported extensions
+     */
     List<Extension> getExtensions();
 
+    /**
+     * Returns the SSL context to use for secure WebSocket connections.
+     *
+     * @return The SSL context, or {@code null} if no custom SSL context is configured
+     */
     SSLContext getSSLContext();
 
+    /**
+     * Returns the configurator used to customize the WebSocket handshake.
+     *
+     * @return The configurator for this client endpoint
+     */
     Configurator getConfigurator();
 
+    /**
+     * Builder for creating {@link ClientEndpointConfig} instances.
+     */
     final class Builder {
 
         private static final Configurator DEFAULT_CONFIGURATOR = new Configurator() {
         };
 
 
+        /**
+         * Creates a new {@link Builder} instance for building a {@link ClientEndpointConfig}.
+         *
+         * @return A new builder instance
+         */
         public static Builder create() {
             return new Builder();
         }
@@ -54,12 +85,23 @@ public interface ClientEndpointConfig extends EndpointConfig {
         private List<Class<? extends Decoder>> decoders = Collections.emptyList();
         private SSLContext sslContext = null;
 
+        /**
+         * Builds and returns a {@link ClientEndpointConfig} with the configured settings.
+         *
+         * @return The configured client endpoint configuration
+         */
         public ClientEndpointConfig build() {
             return new DefaultClientEndpointConfig(preferredSubprotocols, extensions, encoders, decoders, sslContext,
                     configurator);
         }
 
 
+        /**
+         * Sets the configurator to use for the WebSocket handshake.
+         *
+         * @param configurator The configurator, or {@code null} to use the default
+         * @return This builder instance
+         */
         public Builder configurator(Configurator configurator) {
             if (configurator == null) {
                 this.configurator = DEFAULT_CONFIGURATOR;
@@ -70,6 +112,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
         }
 
 
+        /**
+         * Sets the list of preferred sub-protocols for the WebSocket connection.
+         *
+         * @param preferredSubprotocols The list of sub-protocols in order of preference
+         * @return This builder instance
+         */
         public Builder preferredSubprotocols(List<String> preferredSubprotocols) {
             if (preferredSubprotocols == null || preferredSubprotocols.isEmpty()) {
                 this.preferredSubprotocols = Collections.emptyList();
@@ -80,6 +128,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
         }
 
 
+        /**
+         * Sets the list of extensions to use for the WebSocket connection.
+         *
+         * @param extensions The list of extensions
+         * @return This builder instance
+         */
         public Builder extensions(List<Extension> extensions) {
             if (extensions == null || extensions.isEmpty()) {
                 this.extensions = Collections.emptyList();
@@ -90,6 +144,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
         }
 
 
+        /**
+         * Sets the list of encoder classes to use for the WebSocket connection.
+         *
+         * @param encoders The list of encoder classes
+         * @return This builder instance
+         */
         public Builder encoders(List<Class<? extends Encoder>> encoders) {
             if (encoders == null || encoders.isEmpty()) {
                 this.encoders = Collections.emptyList();
@@ -100,6 +160,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
         }
 
 
+        /**
+         * Sets the list of decoder classes to use for the WebSocket connection.
+         *
+         * @param decoders The list of decoder classes
+         * @return This builder instance
+         */
         public Builder decoders(List<Class<? extends Decoder>> decoders) {
             if (decoders == null || decoders.isEmpty()) {
                 this.decoders = Collections.emptyList();
@@ -110,6 +176,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
         }
 
 
+        /**
+         * Sets the SSL context to use for secure WebSocket connections.
+         *
+         * @param sslContext The SSL context, or {@code null} for default SSL behavior
+         * @return This builder instance
+         */
         public Builder sslContext(SSLContext sslContext) {
             this.sslContext = sslContext;
             return this;
@@ -117,8 +189,18 @@ public interface ClientEndpointConfig extends EndpointConfig {
     }
 
 
+    /**
+     * Provides a mechanism to customize the WebSocket handshake for client endpoints.
+     * Applications may subclass this to inspect or modify the handshake.
+     */
     class Configurator {
 
+        /**
+         * Creates a new instance of the default Configurator.
+         */
+        public Configurator() {
+        }
+
         /**
          * Provides the client with a mechanism to inspect and/or modify the headers that are sent to the server to
          * start the WebSocket handshake.
diff --git a/java/jakarta/websocket/CloseReason.java b/java/jakarta/websocket/CloseReason.java
index b7aef11305..7108dc6784 100644
--- a/java/jakarta/websocket/CloseReason.java
+++ b/java/jakarta/websocket/CloseReason.java
@@ -16,20 +16,40 @@
  */
 package jakarta.websocket;
 
+/**
+ * Represents the reason for the closure of a WebSocket connection, including a close code
+ * and an optional reason phrase.
+ */
 public class CloseReason {
 
     private final CloseCode closeCode;
     private final String reasonPhrase;
 
+    /**
+     * Creates a new CloseReason with the given close code and reason phrase.
+     *
+     * @param closeCode    The close code
+     * @param reasonPhrase The reason phrase explaining the closure
+     */
     public CloseReason(CloseReason.CloseCode closeCode, String reasonPhrase) {
         this.closeCode = closeCode;
         this.reasonPhrase = reasonPhrase;
     }
 
+    /**
+     * Returns the close code.
+     *
+     * @return The close code
+     */
     public CloseCode getCloseCode() {
         return closeCode;
     }
 
+    /**
+     * Returns the reason phrase.
+     *
+     * @return The reason phrase
+     */
     public String getReasonPhrase() {
         return reasonPhrase;
     }
@@ -39,34 +59,115 @@ public class CloseReason {
         return "CloseReason: code [" + closeCode.getCode() + "], reason [" + reasonPhrase + "]";
     }
 
+    /**
+     * Represents a WebSocket close code.
+     */
     public interface CloseCode {
+        /**
+         * Returns the numeric value of the close code.
+         *
+         * @return The numeric close code value
+         */
         int getCode();
     }
 
+    /**
+     * Standard WebSocket close codes as defined by RFC 6455 and related specifications.
+     */
     public enum CloseCodes implements CloseReason.CloseCode {
 
+        /**
+         * Indicates a normal closure, meaning that the purpose for which the connection was
+         * established has been fulfilled.
+         */
         NORMAL_CLOSURE(1000),
+        /**
+         * Indicates that the endpoint is going away, either because the browser is navigating
+         * away from the page, or because the server is shutting down.
+         */
         GOING_AWAY(1001),
+        /**
+         * Indicates that the endpoint is terminating the connection due to a protocol error.
+         */
         PROTOCOL_ERROR(1002),
+        /**
+         * Indicates that the endpoint is terminating the connection because it has received a
+         * type of data it cannot accept.
+         */
         CANNOT_ACCEPT(1003),
+        /**
+         * Reserved. The specific meaning might be defined in the future.
+         */
         RESERVED(1004),
+        /**
+         * Indicates that no status code was included in the closing frame. This value is
+         * reserved and must not be set as a status code in a Close control frame.
+         */
         NO_STATUS_CODE(1005),
+        /**
+         * Indicates that the connection was closed abnormally without receiving a close frame.
+         * This value is reserved and must not be set as a status code in a Close control frame.
+         */
         CLOSED_ABNORMALLY(1006),
+        /**
+         * Indicates that the endpoint is terminating the connection because it has received a
+         * message that contains data that is not consistent with the type of the message.
+         */
         NOT_CONSISTENT(1007),
+        /**
+         * Indicates that the endpoint is terminating the connection because it has received a
+         * message that violates its policy.
+         */
         VIOLATED_POLICY(1008),
+        /**
+         * Indicates that the endpoint is terminating the connection because it has received a
+         * message that is too big to process.
+         */
         TOO_BIG(1009),
+        /**
+         * Indicates that the client is terminating the connection because it expected the
+         * server to negotiate one or more extension, but the server didn't return them in the
+         * handshake response.
+         */
         NO_EXTENSION(1010),
+        /**
+         * Indicates that the server is terminating the connection because it encountered an
+         * unexpected condition that prevented it from fulfilling the request.
+         */
         UNEXPECTED_CONDITION(1011),
+        /**
+         * Indicates that the server is restarting. A client may choose to reconnect.
+         */
         SERVICE_RESTART(1012),
+        /**
+         * Indicates that the server is experiencing a temporary condition and the client should
+         * try to connect again later.
+         */
         TRY_AGAIN_LATER(1013),
+        /**
+         * Indicates that the connection was closed due to a failure to perform a TLS handshake.
+         * This value is reserved and must not be set as a status code in a Close control frame.
+         */
         TLS_HANDSHAKE_FAILURE(1015);
 
         private final int code;
 
+        /**
+         * Creates a close code with the given numeric value.
+         *
+         * @param code The numeric close code value
+         */
         CloseCodes(int code) {
             this.code = code;
         }
 
+        /**
+         * Returns the {@link CloseCode} for the given numeric code value.
+         *
+         * @param code The numeric close code value
+         * @return The corresponding {@link CloseCode}
+         * @throws IllegalArgumentException if the code is not a valid close code
+         */
         public static CloseCode getCloseCode(final int code) {
             if (code > 2999 && code < 5000) {
                 return () -> code;
@@ -91,6 +192,11 @@ public class CloseReason {
             };
         }
 
+        /**
+         * Returns the numeric value of this close code.
+         *
+         * @return The numeric close code value
+         */
         @Override
         public int getCode() {
             return code;
diff --git a/java/jakarta/websocket/ContainerProvider.java b/java/jakarta/websocket/ContainerProvider.java
index 56381d0dde..f79f7f8ed3 100644
--- a/java/jakarta/websocket/ContainerProvider.java
+++ b/java/jakarta/websocket/ContainerProvider.java
@@ -24,6 +24,12 @@ import java.util.ServiceLoader;
  */
 public abstract class ContainerProvider {
 
+    /**
+     * Creates a new ContainerProvider instance.
+     */
+    protected ContainerProvider() {
+    }
+
     private static final String DEFAULT_PROVIDER_CLASS_NAME = "org.apache.tomcat.websocket.WsWebSocketContainer";
 
     /**
@@ -54,5 +60,10 @@ public abstract class ContainerProvider {
         return result;
     }
 
+    /**
+     * Returns the WebSocket container provided by this provider.
+     *
+     * @return The WebSocket container
+     */
     protected abstract WebSocketContainer getContainer();
 }
diff --git a/java/jakarta/websocket/DecodeException.java b/java/jakarta/websocket/DecodeException.java
index e6a9279094..d40fb4870f 100644
--- a/java/jakarta/websocket/DecodeException.java
+++ b/java/jakarta/websocket/DecodeException.java
@@ -19,38 +19,83 @@ package jakarta.websocket;
 import java.io.Serial;
 import java.nio.ByteBuffer;
 
+/**
+ * Exception thrown when a decoder fails to decode a WebSocket message.
+ */
 public class DecodeException extends Exception {
 
     @Serial
     private static final long serialVersionUID = 1L;
 
+    /**
+     * The binary data that could not be decoded.
+     */
     private ByteBuffer bb;
+    /**
+     * The text data that could not be decoded.
+     */
     private String encodedString;
 
+    /**
+     * Creates a DecodeException for binary data with the specified detail message and cause.
+     *
+     * @param bb      The binary data that could not be decoded
+     * @param message The detail message
+     * @param cause   The underlying cause of the exception
+     */
     public DecodeException(ByteBuffer bb, String message, Throwable cause) {
         super(message, cause);
         this.bb = bb;
     }
 
+    /**
+     * Creates a DecodeException for text data with the specified detail message and cause.
+     *
+     * @param encodedString The text data that could not be decoded
+     * @param message       The detail message
+     * @param cause         The underlying cause of the exception
+     */
     public DecodeException(String encodedString, String message, Throwable cause) {
         super(message, cause);
         this.encodedString = encodedString;
     }
 
+    /**
+     * Creates a DecodeException for binary data with the specified detail message.
+     *
+     * @param bb      The binary data that could not be decoded
+     * @param message The detail message
+     */
     public DecodeException(ByteBuffer bb, String message) {
         super(message);
         this.bb = bb;
     }
 
+    /**
+     * Creates a DecodeException for text data with the specified detail message.
+     *
+     * @param encodedString The text data that could not be decoded
+     * @param message       The detail message
+     */
     public DecodeException(String encodedString, String message) {
         super(message);
         this.encodedString = encodedString;
     }
 
+    /**
+     * Returns the binary data that could not be decoded.
+     *
+     * @return The binary data, or {@code null} if the exception was for text data
+     */
     public ByteBuffer getBytes() {
         return bb;
     }
 
+    /**
+     * Returns the text data that could not be decoded.
+     *
+     * @return The text data, or {@code null} if the exception was for binary data
+     */
     public String getText() {
         return encodedString;
     }
diff --git a/java/jakarta/websocket/Decoder.java b/java/jakarta/websocket/Decoder.java
index 4f0a4e4c04..03db069e6a 100644
--- a/java/jakarta/websocket/Decoder.java
+++ b/java/jakarta/websocket/Decoder.java
@@ -21,6 +21,10 @@ import java.io.InputStream;
 import java.io.Reader;
 import java.nio.ByteBuffer;
 
+/**
+ * Base interface for WebSocket message decoders. Decoders convert incoming WebSocket messages
+ * from their raw form (text or binary) into application-specific objects.
+ */
 public interface Decoder {
 
     /**
@@ -37,27 +41,91 @@ public interface Decoder {
     default void destroy() {
     }
 
+    /**
+     * A decoder that decodes entire binary WebSocket messages into an object of type T.
+     *
+     * @param <T> The type of object produced by the decoder
+     */
     interface Binary<T> extends Decoder {
 
+        /**
+         * Decodes the binary data into an object.
+         *
+         * @param bytes The binary data to decode
+         * @return The decoded object
+         * @throws DecodeException If the data cannot be decoded
+         */
         T decode(ByteBuffer bytes) throws DecodeException;
 
+        /**
+         * Determines whether this decoder can decode the given binary data.
+         *
+         * @param bytes The binary data to check
+         * @return {@code true} if this decoder can decode the data
+         */
         boolean willDecode(ByteBuffer bytes);
     }
 
+    /**
+     * A decoder that decodes entire binary WebSocket messages from an input stream into an
+     * object of type T.
+     *
+     * @param <T> The type of object produced by the decoder
+     */
     interface BinaryStream<T> extends Decoder {
 
+        /**
+         * Decodes the binary data from the input stream into an object.
+         *
+         * @param is The input stream containing the binary data
+         * @return The decoded object
+         * @throws DecodeException If the data cannot be decoded
+         * @throws IOException     If an I/O error occurs
+         */
         T decode(InputStream is) throws DecodeException, IOException;
     }
 
+    /**
+     * A decoder that decodes entire text WebSocket messages into an object of type T.
+     *
+     * @param <T> The type of object produced by the decoder
+     */
     interface Text<T> extends Decoder {
 
+        /**
+         * Decodes the text data into an object.
+         *
+         * @param s The text data to decode
+         * @return The decoded object
+         * @throws DecodeException If the data cannot be decoded
+         */
         T decode(String s) throws DecodeException;
 
+        /**
+         * Determines whether this decoder can decode the given text data.
+         *
+         * @param s The text data to check
+         * @return {@code true} if this decoder can decode the data
+         */
         boolean willDecode(String s);
     }
 
+    /**
+     * A decoder that decodes entire text WebSocket messages from a reader into an object of
+     * type T.
+     *
+     * @param <T> The type of object produced by the decoder
+     */
     interface TextStream<T> extends Decoder {
 
+        /**
+         * Decodes the text data from the reader into an object.
+         *
+         * @param reader The reader containing the text data
+         * @return The decoded object
+         * @throws DecodeException If the data cannot be decoded
+         * @throws IOException     If an I/O error occurs
+         */
         T decode(Reader reader) throws DecodeException, IOException;
     }
 }
diff --git a/java/jakarta/websocket/DeploymentException.java b/java/jakarta/websocket/DeploymentException.java
index d12f62680b..1bc0202cbd 100644
--- a/java/jakarta/websocket/DeploymentException.java
+++ b/java/jakarta/websocket/DeploymentException.java
@@ -18,15 +18,29 @@ package jakarta.websocket;
 
 import java.io.Serial;
 
+/**
+ * Exception thrown when a WebSocket endpoint cannot be deployed due to a configuration error.
+ */
 public class DeploymentException extends Exception {
 
     @Serial
     private static final long serialVersionUID = 1L;
 
+    /**
+     * Creates a DeploymentException with the specified detail message.
+     *
+     * @param message The detail message
+     */
     public DeploymentException(String message) {
         super(message);
     }
 
+    /**
+     * Creates a DeploymentException with the specified detail message and cause.
+     *
+     * @param message The detail message
+     * @param cause   The underlying cause of the exception
+     */
     public DeploymentException(String message, Throwable cause) {
         super(message, cause);
     }
diff --git a/java/jakarta/websocket/EncodeException.java b/java/jakarta/websocket/EncodeException.java
index 406b0ffee1..86b78c29d1 100644
--- a/java/jakarta/websocket/EncodeException.java
+++ b/java/jakarta/websocket/EncodeException.java
@@ -18,23 +18,47 @@ package jakarta.websocket;
 
 import java.io.Serial;
 
+/**
+ * Exception thrown when an encoder fails to encode an object as a WebSocket message.
+ */
 public class EncodeException extends Exception {
 
     @Serial
     private static final long serialVersionUID = 1L;
 
+    /**
+     * The object that could not be encoded.
+     */
     private final Object object;
 
+    /**
+     * Creates an EncodeException with the specified object and detail message.
+     *
+     * @param object  The object that could not be encoded
+     * @param message The detail message
+     */
     public EncodeException(Object object, String message) {
         super(message);
         this.object = object;
     }
 
+    /**
+     * Creates an EncodeException with the specified object, detail message, and cause.
+     *
+     * @param object  The object that could not be encoded
+     * @param message The detail message
+     * @param cause   The underlying cause of the exception
+     */
     public EncodeException(Object object, String message, Throwable cause) {
         super(message, cause);
         this.object = object;
     }
 
+    /**
+     * Returns the object that could not be encoded.
+     *
+     * @return The object that could not be encoded
+     */
     public Object getObject() {
         return this.object;
     }
diff --git a/java/jakarta/websocket/Encoder.java b/java/jakarta/websocket/Encoder.java
index 808cf3d79b..a1268268dd 100644
--- a/java/jakarta/websocket/Encoder.java
+++ b/java/jakarta/websocket/Encoder.java
@@ -21,6 +21,10 @@ import java.io.OutputStream;
 import java.io.Writer;
 import java.nio.ByteBuffer;
 
+/**
+ * Base interface for WebSocket message encoders. Encoders convert application-specific objects
+ * into WebSocket messages in text or binary form.
+ */
 public interface Encoder {
 
     /**
@@ -32,28 +36,80 @@ public interface Encoder {
     }
 
     /**
-     * Destroy the decoder. The default implementation is a NO-OP.
+     * Destroy the encoder. The default implementation is a NO-OP.
      */
     default void destroy() {
     }
 
+    /**
+     * An encoder that encodes an object of type T into a text WebSocket message.
+     *
+     * @param <T> The type of object accepted by the encoder
+     */
     interface Text<T> extends Encoder {
 
+        /**
+         * Encodes the given object into a text string.
+         *
+         * @param object The object to encode
+         * @return The encoded text string
+         * @throws EncodeException If the object cannot be encoded
+         */
         String encode(T object) throws EncodeException;
     }
 
+    /**
+     * An encoder that encodes an object of type T into a text WebSocket message written to
+     * a {@link Writer}.
+     *
+     * @param <T> The type of object accepted by the encoder
+     */
     interface TextStream<T> extends Encoder {
 
+        /**
+         * Encodes the given object and writes the result to the writer.
+         *
+         * @param object The object to encode
+         * @param writer The writer to write the encoded data to
+         * @throws EncodeException If the object cannot be encoded
+         * @throws IOException     If an I/O error occurs
+         */
         void encode(T object, Writer writer) throws EncodeException, IOException;
     }
 
+    /**
+     * An encoder that encodes an object of type T into a binary WebSocket message.
+     *
+     * @param <T> The type of object accepted by the encoder
+     */
     interface Binary<T> extends Encoder {
 
+        /**
+         * Encodes the given object into a ByteBuffer.
+         *
+         * @param object The object to encode
+         * @return The encoded binary data
+         * @throws EncodeException If the object cannot be encoded
+         */
         ByteBuffer encode(T object) throws EncodeException;
     }
 
+    /**
+     * An encoder that encodes an object of type T into a binary WebSocket message written to
+     * an {@link OutputStream}.
+     *
+     * @param <T> The type of object accepted by the encoder
+     */
     interface BinaryStream<T> extends Encoder {
 
+        /**
+         * Encodes the given object and writes the result to the output stream.
+         *
+         * @param object The object to encode
+         * @param os     The output stream to write the encoded data to
+         * @throws EncodeException If the object cannot be encoded
+         * @throws IOException     If an I/O error occurs
+         */
         void encode(T object, OutputStream os) throws EncodeException, IOException;
     }
 }
diff --git a/java/jakarta/websocket/Endpoint.java b/java/jakarta/websocket/Endpoint.java
index 059430d25e..a832ac9538 100644
--- a/java/jakarta/websocket/Endpoint.java
+++ b/java/jakarta/websocket/Endpoint.java
@@ -16,8 +16,18 @@
  */
 package jakarta.websocket;
 
+/**
+ * Base class for programmatic WebSocket endpoints. Subclasses must implement the
+ * {@link #onOpen(Session, EndpointConfig)} method to handle new connections.
+ */
 public abstract class Endpoint {
 
+    /**
+     * Creates a new Endpoint instance.
+     */
+    public Endpoint() {
+    }
+
     /**
      * Event that is triggered when a new session starts.
      *
diff --git a/java/jakarta/websocket/EndpointConfig.java b/java/jakarta/websocket/EndpointConfig.java
index ed2d423610..7e85ca55c0 100644
--- a/java/jakarta/websocket/EndpointConfig.java
+++ b/java/jakarta/websocket/EndpointConfig.java
@@ -19,11 +19,30 @@ package jakarta.websocket;
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Provides configuration information for a WebSocket endpoint, including encoders, decoders,
+ * and user properties.
+ */
 public interface EndpointConfig {
 
+    /**
+     * Returns the list of encoder classes for this endpoint.
+     *
+     * @return The list of encoder classes
+     */
     List<Class<? extends Encoder>> getEncoders();
 
+    /**
+     * Returns the list of decoder classes for this endpoint.
+     *
+     * @return The list of decoder classes
+     */
     List<Class<? extends Decoder>> getDecoders();
 
+    /**
+     * Returns a map of user properties associated with this endpoint configuration.
+     *
+     * @return The user properties map
+     */
     Map<String,Object> getUserProperties();
 }
diff --git a/java/jakarta/websocket/Extension.java b/java/jakarta/websocket/Extension.java
index a4cbca8f62..61a261c307 100644
--- a/java/jakarta/websocket/Extension.java
+++ b/java/jakarta/websocket/Extension.java
@@ -18,14 +18,42 @@ package jakarta.websocket;
 
 import java.util.List;
 
+/**
+ * Represents a WebSocket extension that can be negotiated during the handshake.
+ */
 public interface Extension {
+
+    /**
+     * Returns the name of this extension.
+     *
+     * @return The extension name
+     */
     String getName();
 
+    /**
+     * Returns the parameters associated with this extension.
+     *
+     * @return The list of extension parameters
+     */
     List<Parameter> getParameters();
 
+    /**
+     * Represents a parameter of a WebSocket extension.
+     */
     interface Parameter {
+
+        /**
+         * Returns the name of this parameter.
+         *
+         * @return The parameter name
+         */
         String getName();
 
+        /**
+         * Returns the value of this parameter.
+         *
+         * @return The parameter value
+         */
         String getValue();
     }
 }
diff --git a/java/jakarta/websocket/HandshakeResponse.java b/java/jakarta/websocket/HandshakeResponse.java
index e5faf9d801..900551f880 100644
--- a/java/jakarta/websocket/HandshakeResponse.java
+++ b/java/jakarta/websocket/HandshakeResponse.java
@@ -19,6 +19,9 @@ package jakarta.websocket;
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Represents the HTTP response returned by the server during a WebSocket handshake.
+ */
 public interface HandshakeResponse {
 
     /**
@@ -26,5 +29,10 @@ public interface HandshakeResponse {
      */
     String SEC_WEBSOCKET_ACCEPT = "Sec-WebSocket-Accept";
 
+    /**
+     * Returns the HTTP headers from the handshake response.
+     *
+     * @return The HTTP headers
+     */
     Map<String,List<String>> getHeaders();
 }
diff --git a/java/jakarta/websocket/MessageHandler.java b/java/jakarta/websocket/MessageHandler.java
index 748dd76776..ace7c96702 100644
--- a/java/jakarta/websocket/MessageHandler.java
+++ b/java/jakarta/websocket/MessageHandler.java
@@ -16,8 +16,18 @@
  */
 package jakarta.websocket;
 
+/**
+ * Base interface for WebSocket message handlers. Use {@link Whole} for handling complete
+ * messages and {@link Partial} for handling messages that may arrive in fragments.
+ */
 public interface MessageHandler {
 
+    /**
+     * A message handler that receives partial (fragmented) messages. The handler is called
+     * multiple times for a single WebSocket message if it arrives in fragments.
+     *
+     * @param <T> The type of message data
+     */
     interface Partial<T> extends MessageHandler {
 
         /**
@@ -29,6 +39,12 @@ public interface MessageHandler {
         void onMessage(T messagePart, boolean last);
     }
 
+   /**
+     * A message handler that receives whole (complete) messages. The handler is called once
+     * per WebSocket message.
+     *
+     * @param <T> The type of message data
+     */
     interface Whole<T> extends MessageHandler {
 
         /**
diff --git a/java/jakarta/websocket/OnClose.java b/java/jakarta/websocket/OnClose.java
index 31291165bc..8c071d1f85 100644
--- a/java/jakarta/websocket/OnClose.java
+++ b/java/jakarta/websocket/OnClose.java
@@ -21,6 +21,10 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Annotates a method on a POJO endpoint to handle the close event. The annotated method
+ * will be called when the WebSocket session is closed.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface OnClose {
diff --git a/java/jakarta/websocket/OnError.java b/java/jakarta/websocket/OnError.java
index a09a5bde28..cba6abd9ac 100644
--- a/java/jakarta/websocket/OnError.java
+++ b/java/jakarta/websocket/OnError.java
@@ -21,6 +21,10 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Annotates a method on a POJO endpoint to handle error events. The annotated method
+ * will be called when an error occurs on the WebSocket session.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface OnError {
diff --git a/java/jakarta/websocket/OnMessage.java b/java/jakarta/websocket/OnMessage.java
index 34cfcfa18e..49d95b8c74 100644
--- a/java/jakarta/websocket/OnMessage.java
+++ b/java/jakarta/websocket/OnMessage.java
@@ -21,8 +21,19 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Annotates a method on a POJO endpoint to handle incoming WebSocket messages. The annotated
+ * method will be called when a message is received.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface OnMessage {
+
+    /**
+     * The maximum message size in bytes that this handler will accept. Messages larger than
+     * this size will be discarded. A value of -1 indicates no limit.
+     *
+     * @return The maximum message size in bytes
+     */
     long maxMessageSize() default -1;
 }
diff --git a/java/jakarta/websocket/OnOpen.java b/java/jakarta/websocket/OnOpen.java
index 26b8e9d1e0..48f98d7bbd 100644
--- a/java/jakarta/websocket/OnOpen.java
+++ b/java/jakarta/websocket/OnOpen.java
@@ -21,6 +21,10 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Annotates a method on a POJO endpoint to handle the open event. The annotated method
+ * will be called when a new WebSocket session is established.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface OnOpen {
diff --git a/java/jakarta/websocket/RemoteEndpoint.java b/java/jakarta/websocket/RemoteEndpoint.java
index 9826d98cc0..a485581c65 100644
--- a/java/jakarta/websocket/RemoteEndpoint.java
+++ b/java/jakarta/websocket/RemoteEndpoint.java
@@ -23,8 +23,15 @@ import java.nio.ByteBuffer;
 import java.util.concurrent.Future;
 
 
+/**
+ * Interface for sending messages to the remote endpoint of a WebSocket session.
+ * Provides both synchronous ({@link Basic}) and asynchronous ({@link Async}) sending capabilities.
+ */
 public interface RemoteEndpoint {
 
+    /**
+     * Asynchronous API for sending messages to the remote endpoint.
+     */
     interface Async extends RemoteEndpoint {
 
         /**
@@ -109,6 +116,9 @@ public interface RemoteEndpoint {
 
     }
 
+   /**
+     * Synchronous (blocking) API for sending messages to the remote endpoint.
+     */
     interface Basic extends RemoteEndpoint {
 
         /**
@@ -155,8 +165,20 @@ public interface RemoteEndpoint {
          */
         void sendBinary(ByteBuffer partialByte, boolean isLast) throws IOException;
 
+        /**
+         * Returns an {@link OutputStream} for sending a binary message to the remote endpoint.
+         *
+         * @return An output stream for sending binary data
+         * @throws IOException if an I/O error occurs
+         */
         OutputStream getSendStream() throws IOException;
 
+        /**
+         * Returns a {@link Writer} for sending a text message to the remote endpoint.
+         *
+         * @return A writer for sending text data
+         * @throws IOException if an I/O error occurs
+         */
         Writer getSendWriter() throws IOException;
 
         /**
diff --git a/java/jakarta/websocket/SendHandler.java b/java/jakarta/websocket/SendHandler.java
index 9e8317c5b5..ee34f7a25c 100644
--- a/java/jakarta/websocket/SendHandler.java
+++ b/java/jakarta/websocket/SendHandler.java
@@ -16,7 +16,15 @@
  */
 package jakarta.websocket;
 
+/**
+ * Callback interface for handling the result of an asynchronous WebSocket message send operation.
+ */
 public interface SendHandler {
 
+    /**
+     * Called when the asynchronous send operation completes.
+     *
+     * @param result The result of the send operation
+     */
     void onResult(SendResult result);
 }
diff --git a/java/jakarta/websocket/SendResult.java b/java/jakarta/websocket/SendResult.java
index f506c881af..b7a6842f37 100644
--- a/java/jakarta/websocket/SendResult.java
+++ b/java/jakarta/websocket/SendResult.java
@@ -16,6 +16,9 @@
  */
 package jakarta.websocket;
 
+/**
+ * Represents the result of an asynchronous WebSocket message send operation.
+ */
 public final class SendResult {
     private final Session session;
     private final Throwable exception;
@@ -66,10 +69,21 @@ public final class SendResult {
         this(null, null);
     }
 
+    /**
+     * Returns the exception that occurred during the send operation, or {@code null} if the
+     * operation was successful.
+     *
+     * @return The exception, or {@code null} if successful
+     */
     public Throwable getException() {
         return exception;
     }
 
+    /**
+     * Returns whether the send operation was successful.
+     *
+     * @return {@code true} if the send was successful, {@code false} otherwise
+     */
     public boolean isOK() {
         return ok;
     }
diff --git a/java/jakarta/websocket/Session.java b/java/jakarta/websocket/Session.java
index 21e20ea086..eb439795a4 100644
--- a/java/jakarta/websocket/Session.java
+++ b/java/jakarta/websocket/Session.java
@@ -24,6 +24,11 @@ import java.util.List;
 import java.util.Map;
 import java.util.Set;
 
+/**
+ * Represents a WebSocket session, which is the WebSocket connection between a client and a server.
+ * A session is created when a WebSocket connection is established and is used to send and receive
+ * messages.
+ */
 public interface Session extends Closeable {
 
     /**
@@ -46,18 +51,54 @@ public interface Session extends Closeable {
      */
     void addMessageHandler(MessageHandler handler) throws IllegalStateException;
 
+    /**
+     * Returns the set of message handlers currently registered on this session.
+     *
+     * @return The set of registered message handlers
+     */
     Set<MessageHandler> getMessageHandlers();
 
+    /**
+     * Removes the specified message handler from this session.
+     *
+     * @param listener The message handler to remove
+     */
     void removeMessageHandler(MessageHandler listener);
 
+    /**
+     * Returns the version of the WebSocket protocol in use for this session.
+     *
+     * @return The protocol version
+     */
     String getProtocolVersion();
 
+    /**
+     * Returns the sub-protocol negotiated for this session, or {@code null} if no sub-protocol
+     * was negotiated.
+     *
+     * @return The negotiated sub-protocol
+     */
     String getNegotiatedSubprotocol();
 
+    /**
+     * Returns the list of extensions negotiated for this session.
+     *
+     * @return The list of negotiated extensions
+     */
     List<Extension> getNegotiatedExtensions();
 
+    /**
+     * Returns whether this session is using a secure connection (wss://).
+     *
+     * @return {@code true} if the connection is secure
+     */
     boolean isSecure();
 
+    /**
+     * Returns whether this session is currently open.
+     *
+     * @return {@code true} if the session is open
+     */
     boolean isOpen();
 
     /**
@@ -104,8 +145,19 @@ public interface Session extends Closeable {
      */
     int getMaxTextMessageBufferSize();
 
+    /**
+     * Returns the asynchronous remote endpoint for this session, used for non-blocking message
+     * sending.
+     *
+     * @return The asynchronous remote endpoint
+     */
     RemoteEndpoint.Async getAsyncRemote();
 
+    /**
+     * Returns the synchronous remote endpoint for this session, used for blocking message sending.
+     *
+     * @return The synchronous remote endpoint
+     */
     RemoteEndpoint.Basic getBasicRemote();
 
     /**
@@ -135,16 +187,47 @@ public interface Session extends Closeable {
      */
     void close(CloseReason closeReason) throws IOException;
 
+    /**
+     * Returns the URI of the request that initiated this WebSocket session.
+     *
+     * @return The request URI
+     */
     URI getRequestURI();
 
+    /**
+     * Returns the query parameters from the request that initiated this WebSocket session.
+     *
+     * @return The query parameter map
+     */
     Map<String,List<String>> getRequestParameterMap();
 
+    /**
+     * Returns the query string from the request that initiated this WebSocket session.
+     *
+     * @return The query string
+     */
     String getQueryString();
 
+    /**
+     * Returns the path parameters extracted from the request URI using the endpoint's URI template.
+     *
+     * @return The path parameter map
+     */
     Map<String,String> getPathParameters();
 
+    /**
+     * Returns a map of user properties associated with this session.
+     *
+     * @return The user properties map
+     */
     Map<String,Object> getUserProperties();
 
+    /**
+     * Returns the principal of the user associated with this session, or {@code null} if the
+     * user is not authenticated.
+     *
+     * @return The user principal
+     */
     Principal getUserPrincipal();
 
     /**
diff --git a/java/jakarta/websocket/SessionException.java b/java/jakarta/websocket/SessionException.java
index d1d0f9908c..7645c73fa0 100644
--- a/java/jakarta/websocket/SessionException.java
+++ b/java/jakarta/websocket/SessionException.java
@@ -18,20 +18,38 @@ package jakarta.websocket;
 
 import java.io.Serial;
 
+/**
+ * Exception thrown when an error occurs on a WebSocket session.
+ */
 public class SessionException extends Exception {
 
     @Serial
     private static final long serialVersionUID = 1L;
 
+    /**
+     * The session on which the error occurred.
+     */
     private final Session session;
 
 
+    /**
+     * Creates a SessionException with the specified detail message, cause, and session.
+     *
+     * @param message The detail message
+     * @param cause   The underlying cause of the exception
+     * @param session The session on which the error occurred
+     */
     public SessionException(String message, Throwable cause, Session session) {
         super(message, cause);
         this.session = session;
     }
 
 
+    /**
+     * Returns the session on which the error occurred.
+     *
+     * @return The session
+     */
     public Session getSession() {
         return session;
     }
diff --git a/java/jakarta/websocket/WebSocketContainer.java b/java/jakarta/websocket/WebSocketContainer.java
index 82ddb7ff47..7613ece7a7 100644
--- a/java/jakarta/websocket/WebSocketContainer.java
+++ b/java/jakarta/websocket/WebSocketContainer.java
@@ -20,6 +20,9 @@ import java.io.IOException;
 import java.net.URI;
 import java.util.Set;
 
+/**
+ * Provides the ability to create new WebSocket client connections.
+ */
 public interface WebSocketContainer {
 
     /**
@@ -36,8 +39,27 @@ public interface WebSocketContainer {
      */
     void setAsyncSendTimeout(long timeout);
 
+    /**
+     * Creates a new connection to the WebSocket server endpoint.
+     *
+     * @param endpoint The POJO endpoint instance that will handle responses from the server
+     * @param path     The full URL of the WebSocket endpoint to connect to
+     * @return The WebSocket session for the connection
+     * @throws DeploymentException If the connection cannot be established
+     * @throws IOException         If an I/O error occurred while trying to establish the connection
+     */
     Session connectToServer(Object endpoint, URI path) throws DeploymentException, IOException;
 
+    /**
+     * Creates a new connection to the WebSocket server endpoint.
+     *
+     * @param annotatedEndpointClass The annotated endpoint class. An instance of this class will be
+     *                                   created to handle responses from the server
+     * @param path                   The full URL of the WebSocket endpoint to connect to
+     * @return The WebSocket session for the connection
+     * @throws DeploymentException If the connection cannot be established
+     * @throws IOException         If an I/O error occurred while trying to establish the connection
+     */
     Session connectToServer(Class<?> annotatedEndpointClass, URI path) throws DeploymentException, IOException;
 
     /**
diff --git a/java/jakarta/websocket/server/HandshakeRequest.java b/java/jakarta/websocket/server/HandshakeRequest.java
index 457942ed76..a17cb21545 100644
--- a/java/jakarta/websocket/server/HandshakeRequest.java
+++ b/java/jakarta/websocket/server/HandshakeRequest.java
@@ -26,17 +26,51 @@ import java.util.Map;
  */
 public interface HandshakeRequest {
 
+    /**
+     * Name of the Sec-WebSocket-Key HTTP header.
+     */
     String SEC_WEBSOCKET_KEY = "Sec-WebSocket-Key";
+    /**
+     * Name of the Sec-WebSocket-Protocol HTTP header.
+     */
     String SEC_WEBSOCKET_PROTOCOL = "Sec-WebSocket-Protocol";
+    /**
+     * Name of the Sec-WebSocket-Version HTTP header.
+     */
     String SEC_WEBSOCKET_VERSION = "Sec-WebSocket-Version";
+    /**
+     * Name of the Sec-WebSocket-Extensions HTTP header.
+     */
     String SEC_WEBSOCKET_EXTENSIONS = "Sec-WebSocket-Extensions";
 
+    /**
+     * Returns the HTTP headers from the handshake request.
+     *
+     * @return The HTTP headers
+     */
     Map<String,List<String>> getHeaders();
 
+    /**
+     * Returns the principal of the user associated with this request, or {@code null} if the
+     * user is not authenticated.
+     *
+     * @return The user principal
+     */
     Principal getUserPrincipal();
 
+    /**
+     * Returns the URI of the handshake request.
+     *
+     * @return The request URI
+     */
     URI getRequestURI();
 
+    /**
+     * Returns whether the user associated with this request is in the given role.
+     *
+     * @param role The role to check
+     * @return {@code true} if the user is in the specified role
+     */
     boolean isUserInRole(String role);
 
     /**
@@ -47,7 +81,17 @@ public interface HandshakeRequest {
      */
     Object getHttpSession();
 
+    /**
+     * Returns the query parameters from the handshake request.
+     *
+     * @return The query parameter map
+     */
     Map<String,List<String>> getParameterMap();
 
+    /**
+     * Returns the query string from the handshake request.
+     *
+     * @return The query string
+     */
     String getQueryString();
 }
diff --git a/java/jakarta/websocket/server/PathParam.java b/java/jakarta/websocket/server/PathParam.java
index 22293b3dda..b86dbbf85b 100644
--- a/java/jakarta/websocket/server/PathParam.java
+++ b/java/jakarta/websocket/server/PathParam.java
@@ -28,5 +28,11 @@ import java.lang.annotation.Target;
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.PARAMETER)
 public @interface PathParam {
+
+    /**
+     * The name of the path parameter from the URI template.
+     *
+     * @return The path parameter name
+     */
     String value();
 }
diff --git a/java/jakarta/websocket/server/ServerContainer.java b/java/jakarta/websocket/server/ServerContainer.java
index 82b92dc7bd..e6c4f68c91 100644
--- a/java/jakarta/websocket/server/ServerContainer.java
+++ b/java/jakarta/websocket/server/ServerContainer.java
@@ -26,8 +26,21 @@ import jakarta.websocket.WebSocketContainer;
  * Provides the ability to deploy endpoints programmatically.
  */
 public interface ServerContainer extends WebSocketContainer {
+    /**
+     * Deploys the given endpoint class. The class must be annotated with
+     * {@link jakarta.websocket.server.ServerEndpoint} or extend {@link jakarta.websocket.Endpoint}.
+     *
+     * @param clazz The endpoint class to deploy
+     * @throws DeploymentException If the endpoint cannot be deployed
+     */
     void addEndpoint(Class<?> clazz) throws DeploymentException;
 
+    /**
+     * Deploys the endpoint configured by the given {@link ServerEndpointConfig}.
+     *
+     * @param sec The server endpoint configuration
+     * @throws DeploymentException If the endpoint cannot be deployed
+     */
     void addEndpoint(ServerEndpointConfig sec) throws DeploymentException;
 
     /**
diff --git a/java/jakarta/websocket/server/ServerEndpoint.java b/java/jakarta/websocket/server/ServerEndpoint.java
index b29ebec134..f0efc31112 100644
--- a/java/jakarta/websocket/server/ServerEndpoint.java
+++ b/java/jakarta/websocket/server/ServerEndpoint.java
@@ -24,6 +24,11 @@ import java.lang.annotation.Target;
 import jakarta.websocket.Decoder;
 import jakarta.websocket.Encoder;
 
+/**
+ * Annotates a class as a WebSocket server endpoint. The annotation provides configuration
+ * information about the endpoint such as the URI path, subprotocols, encoders, decoders,
+ * and configurator.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 public @interface ServerEndpoint {
@@ -35,11 +40,31 @@ public @interface ServerEndpoint {
      */
     String value();
 
+    /**
+     * The sub-protocols that this server endpoint supports.
+     *
+     * @return The list of supported sub-protocols
+     */
     String[] subprotocols() default {};
 
+    /**
+     * The decoder classes that this server endpoint uses.
+     *
+     * @return The list of decoder classes
+     */
     Class<? extends Decoder>[] decoders() default {};
 
+    /**
+     * The encoder classes that this server endpoint uses.
+     *
+     * @return The list of encoder classes
+     */
     Class<? extends Encoder>[] encoders() default {};
 
+    /**
+     * The configurator class used to customize the WebSocket handshake.
+     *
+     * @return The configurator class
+     */
     Class<? extends ServerEndpointConfig.Configurator> configurator() default ServerEndpointConfig.Configurator.class;
 }
diff --git a/java/jakarta/websocket/server/ServerEndpointConfig.java b/java/jakarta/websocket/server/ServerEndpointConfig.java
index e72a879608..caf697a61b 100644
--- a/java/jakarta/websocket/server/ServerEndpointConfig.java
+++ b/java/jakarta/websocket/server/ServerEndpointConfig.java
@@ -33,6 +33,11 @@ import jakarta.websocket.HandshakeResponse;
  */
 public interface ServerEndpointConfig extends EndpointConfig {
 
+    /**
+     * Returns the class of the endpoint.
+     *
+     * @return The endpoint class
+     */
     Class<?> getEndpointClass();
 
     /**
@@ -43,15 +48,40 @@ public interface ServerEndpointConfig extends EndpointConfig {
      */
     String getPath();
 
+    /**
+     * Returns the list of sub-protocols supported by this endpoint.
+     *
+     * @return The list of supported sub-protocols
+     */
     List<String> getSubprotocols();
 
+    /**
+     * Returns the list of extensions supported by this endpoint.
+     *
+     * @return The list of supported extensions
+     */
     List<Extension> getExtensions();
 
+    /**
+     * Returns the configurator for this server endpoint.
+     *
+     * @return The configurator
+     */
     Configurator getConfigurator();
 
 
+    /**
+     * Builder for creating {@link ServerEndpointConfig} instances.
+     */
     final class Builder {
 
+        /**
+         * Creates a new builder for the given endpoint class and path.
+         *
+         * @param endpointClass The endpoint class
+         * @param path          The path at which the endpoint will be registered
+         * @return A new builder instance
+         */
         public static Builder create(Class<?> endpointClass, String path) {
             return new Builder(endpointClass, path);
         }
@@ -83,12 +113,23 @@ public interface ServerEndpointConfig extends EndpointConfig {
             this.path = path;
         }
 
+ /**
+         * Builds and returns a {@link ServerEndpointConfig} with the configured settings.
+         *
+         * @return The configured server endpoint configuration
+         */
         public ServerEndpointConfig build() {
             return new DefaultServerEndpointConfig(endpointClass, path, subprotocols, extensions, encoders, decoders,
                     configurator);
         }
 
 
+        /**
+         * Sets the list of encoder classes to use for the WebSocket connection.
+         *
+         * @param encoders The list of encoder classes
+         * @return This builder instance
+         */
         public Builder encoders(List<Class<? extends Encoder>> encoders) {
             if (encoders == null || encoders.isEmpty()) {
                 this.encoders = Collections.emptyList();
@@ -99,6 +140,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
         }
 
 
+        /**
+         * Sets the list of decoder classes to use for the WebSocket connection.
+         *
+         * @param decoders The list of decoder classes
+         * @return This builder instance
+         */
         public Builder decoders(List<Class<? extends Decoder>> decoders) {
             if (decoders == null || decoders.isEmpty()) {
                 this.decoders = Collections.emptyList();
@@ -109,6 +156,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
         }
 
 
+        /**
+         * Sets the list of sub-protocols supported by the endpoint.
+         *
+         * @param subprotocols The list of sub-protocols
+         * @return This builder instance
+         */
         public Builder subprotocols(List<String> subprotocols) {
             if (subprotocols == null || subprotocols.isEmpty()) {
                 this.subprotocols = Collections.emptyList();
@@ -119,6 +172,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
         }
 
 
+        /**
+         * Sets the list of extensions supported by the endpoint.
+         *
+         * @param extensions The list of extensions
+         * @return This builder instance
+         */
         public Builder extensions(List<Extension> extensions) {
             if (extensions == null || extensions.isEmpty()) {
                 this.extensions = Collections.emptyList();
@@ -129,6 +188,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
         }
 
 
+        /**
+         * Sets the configurator to use for the WebSocket handshake.
+         *
+         * @param serverEndpointConfigurator The configurator, or {@code null} to use the default
+         * @return This builder instance
+         */
         public Builder configurator(Configurator serverEndpointConfigurator) {
             if (serverEndpointConfigurator == null) {
                 this.configurator = Configurator.fetchContainerDefaultConfigurator();
@@ -140,8 +205,18 @@ public interface ServerEndpointConfig extends EndpointConfig {
     }
 
 
+    /**
+     * Provides a mechanism to customize the WebSocket handshake for server endpoints.
+     * Applications may subclass this to inspect or modify the handshake.
+     */
     class Configurator {
 
+        /**
+         * Creates a new instance of the Configurator.
+         */
+        public Configurator() {
+        }
+
         private static volatile Configurator defaultImpl = null;
         private static final Object defaultImplLock = new Object();
 
@@ -195,22 +270,61 @@ public interface ServerEndpointConfig extends EndpointConfig {
             return fetchContainerDefaultConfigurator();
         }
 
+        /**
+         * Determines the sub-protocol to use for the WebSocket connection by comparing the
+         * supported and requested sub-protocols.
+         *
+         * @param supported The list of sub-protocols supported by the endpoint
+         * @param requested The list of sub-protocols requested by the client
+         * @return The negotiated sub-protocol, or {@code null} if none matches
+         */
         public String getNegotiatedSubprotocol(List<String> supported, List<String> requested) {
             return fetchContainerDefaultConfigurator().getNegotiatedSubprotocol(supported, requested);
         }
 
+        /**
+         * Determines the extensions to use for the WebSocket connection by comparing the
+         * installed and requested extensions.
+         *
+         * @param installed The list of extensions installed on the server
+         * @param requested The list of extensions requested by the client
+         * @return The list of negotiated extensions
+         */
         public List<Extension> getNegotiatedExtensions(List<Extension> installed, List<Extension> requested) {
             return fetchContainerDefaultConfigurator().getNegotiatedExtensions(installed, requested);
         }
 
+        /**
+         * Checks whether the given Origin header value is acceptable. The default implementation
+         * always returns {@code true}.
+         *
+         * @param originHeaderValue The Origin header value to check
+         * @return {@code true} if the origin is acceptable
+         */
         public boolean checkOrigin(String originHeaderValue) {
             return fetchContainerDefaultConfigurator().checkOrigin(originHeaderValue);
         }
 
+        /**
+         * Provides the opportunity to modify the handshake before it is completed. This method
+         * is called after the sub-protocol and extensions have been negotiated.
+         *
+         * @param sec     The server endpoint configuration
+         * @param request The handshake request
+         * @param response The handshake response
+         */
         public void modifyHandshake(ServerEndpointConfig sec, HandshakeRequest request, HandshakeResponse response) {
             fetchContainerDefaultConfigurator().modifyHandshake(sec, request, response);
         }
 
+        /**
+         * Creates a new instance of the endpoint class.
+         *
+         * @param <T>    The type of the endpoint class
+         * @param clazz  The endpoint class
+         * @return A new instance of the endpoint
+         * @throws InstantiationException If the endpoint cannot be instantiated
+         */
         public <T extends Object> T getEndpointInstance(Class<T> clazz) throws InstantiationException {
             return fetchContainerDefaultConfigurator().getEndpointInstance(clazz);
         }
diff --git a/java/jakarta/xml/ws/WebServiceRef.java b/java/jakarta/xml/ws/WebServiceRef.java
index 3c7e7a4738..e90a6f9c3c 100644
--- a/java/jakarta/xml/ws/WebServiceRef.java
+++ b/java/jakarta/xml/ws/WebServiceRef.java
@@ -21,19 +21,48 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Declares a reference to a web service. The WebServiceRef annotation can be applied to a field or method to inject
+ * a reference to a web service, or to a class to declare web service dependencies.
+ */
 @Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD })
 @Retention(RetentionPolicy.RUNTIME)
-
 public @interface WebServiceRef {
+
+    /**
+     * The name for the web service reference. The name is relative to the default initial context.
+     *
+     * @return the name of the web service reference
+     */
     String name() default "";
 
+    /**
+     * The type of the injected object, typically the service endpoint interface.
+     *
+     * @return the type class
+     */
     @SuppressWarnings("rawtypes") // Can't use Class<?> because API needs to match specification
     Class type() default Object.class;
 
+    /**
+     * The web service class, typically the service endpoint interface class.
+     *
+     * @return the web service class
+     */
     @SuppressWarnings("rawtypes") // Can't use Class<?> because API needs to match specification
     Class value() default Object.class;
 
+    /**
+     * The location of the WSDL document for the web service.
+     *
+     * @return the WSDL location
+     */
     String wsdlLocation() default "";
 
+    /**
+     * A provider-specific name that this reference should be mapped to.
+     *
+     * @return the provider-specific mapped name
+     */
     String mappedName() default "";
 }
diff --git a/java/jakarta/xml/ws/WebServiceRefs.java b/java/jakarta/xml/ws/WebServiceRefs.java
index 0b69d9e1f2..020d86a674 100644
--- a/java/jakarta/xml/ws/WebServiceRefs.java
+++ b/java/jakarta/xml/ws/WebServiceRefs.java
@@ -21,9 +21,18 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Groups multiple {@link WebServiceRef} annotations on a single declaration. Use this annotation when a class has
+ * dependencies on more than one web service.
+ */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
-
 public @interface WebServiceRefs {
+
+    /**
+     * The array of WebServiceRef annotations.
+     *
+     * @return the WebServiceRef annotations
+     */
     WebServiceRef[] value();
 }


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org


Re: (tomcat) branch 11.0.x updated: Fix Jakarta EE APIs javadoc issues

Posted by Mark Thomas <ma...@apache.org>.
On 11/05/2026 10:17, Rémy Maucherat wrote:
> On Mon, May 11, 2026 at 11:16 AM <re...@apache.org> wrote:
>>
>> This is an automated email from the ASF dual-hosted git repository.
>>
>> rmaucher pushed a commit to branch 11.0.x
>> in repository https://gitbox.apache.org/repos/asf/tomcat.git
>>
>>
>> The following commit(s) were added to refs/heads/11.0.x by this push:
>>       new 9d8b4c99e9 Fix Jakarta EE APIs javadoc issues
>> 9d8b4c99e9 is described below
>>
>> commit 9d8b4c99e9075901a651fbb3152981a547e96121
>> Author: remm <re...@apache.org>
>> AuthorDate: Sat May 9 09:04:07 2026 +0200
>>
>>      Fix Jakarta EE APIs javadoc issues
>>
>>      Includes TODO fixes and a few cut and paste issues.
>>      Coauthored by OpenCode.
>>      One question is if the explicit default constructor will mess up with
>>      the signature validation from the TCK, in which case I will redo it
>>      without that (so I will not backport for now).
> 
> I have not noticed any TCK troubles caused by the change.

I haven't checked exhaustively but there first couple of classes I 
checked, the signature file already included the default constructor so 
an explicit declaration should be fine.

Mark


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org


Re: (tomcat) branch 11.0.x updated: Fix Jakarta EE APIs javadoc issues

Posted by Rémy Maucherat <re...@apache.org>.
On Mon, May 11, 2026 at 11:16 AM <re...@apache.org> wrote:
>
> This is an automated email from the ASF dual-hosted git repository.
>
> rmaucher pushed a commit to branch 11.0.x
> in repository https://gitbox.apache.org/repos/asf/tomcat.git
>
>
> The following commit(s) were added to refs/heads/11.0.x by this push:
>      new 9d8b4c99e9 Fix Jakarta EE APIs javadoc issues
> 9d8b4c99e9 is described below
>
> commit 9d8b4c99e9075901a651fbb3152981a547e96121
> Author: remm <re...@apache.org>
> AuthorDate: Sat May 9 09:04:07 2026 +0200
>
>     Fix Jakarta EE APIs javadoc issues
>
>     Includes TODO fixes and a few cut and paste issues.
>     Coauthored by OpenCode.
>     One question is if the explicit default constructor will mess up with
>     the signature validation from the TCK, in which case I will redo it
>     without that (so I will not backport for now).

I have not noticed any TCK troubles caused by the change.

Rémy

> ---
>  java/jakarta/annotation/Generated.java             |  16 ++-
>  java/jakarta/annotation/Priority.java              |   6 +-
>  java/jakarta/annotation/Resource.java              |  35 +++++--
>  java/jakarta/annotation/Resources.java             |   5 +-
>  java/jakarta/annotation/security/DeclareRoles.java |  11 +-
>  java/jakarta/annotation/security/DenyAll.java      |   6 ++
>  java/jakarta/annotation/security/PermitAll.java    |   6 ++
>  java/jakarta/annotation/security/RolesAllowed.java |  12 ++-
>  java/jakarta/annotation/security/RunAs.java        |  10 +-
>  .../annotation/sql/DataSourceDefinition.java       |  95 +++++++++++++----
>  .../annotation/sql/DataSourceDefinitions.java      |   8 +-
>  java/jakarta/ejb/EJB.java                          |  38 ++++++-
>  java/jakarta/ejb/EJBs.java                         |  11 +-
>  java/jakarta/el/BeanNameELResolver.java            |   8 ++
>  java/jakarta/el/BeanNameResolver.java              |   9 +-
>  java/jakarta/el/CompositeELResolver.java           |  15 +++
>  java/jakarta/el/ELClass.java                       |  14 +++
>  java/jakarta/el/ELContext.java                     |  50 +++++++++
>  java/jakarta/el/ELContextEvent.java                |  13 +++
>  java/jakarta/el/ELContextListener.java             |  13 +++
>  java/jakarta/el/ELManager.java                     |  98 ++++++++++++++++++
>  java/jakarta/el/ELProcessor.java                   |  86 +++++++++++++++-
>  java/jakarta/el/ELResolver.java                    |  17 +++
>  java/jakarta/el/EvaluationListener.java            |  10 ++
>  java/jakarta/el/Expression.java                    |  21 +++-
>  java/jakarta/el/ExpressionFactory.java             |  35 ++++++-
>  java/jakarta/el/FunctionMapper.java                |  24 +++++
>  java/jakarta/el/ImportHandler.java                 |  57 ++++++++++-
>  java/jakarta/el/LambdaExpression.java              |  45 ++++++++
>  java/jakarta/el/ListELResolver.java                |  18 ++++
>  java/jakarta/el/MapELResolver.java                 |  18 ++++
>  java/jakarta/el/MethodExpression.java              |  16 +++
>  java/jakarta/el/MethodInfo.java                    |  29 ++++++
>  java/jakarta/el/MethodNotFoundException.java       |  22 ++++
>  java/jakarta/el/MethodReference.java               |  12 +++
>  java/jakarta/el/OptionalELResolver.java            |   6 ++
>  java/jakarta/el/PropertyNotFoundException.java     |  27 +++++
>  java/jakarta/el/PropertyNotWritableException.java  |  27 +++++
>  java/jakarta/el/RecordELResolver.java              |   7 ++
>  java/jakarta/el/ResourceBundleELResolver.java      |  18 ++++
>  java/jakarta/el/StandardELContext.java             |  29 ++++++
>  java/jakarta/el/StaticFieldELResolver.java         |  11 ++
>  java/jakarta/el/TypeConverter.java                 |  11 ++
>  java/jakarta/el/ValueExpression.java               |  33 ++++++
>  java/jakarta/el/ValueReference.java                |  23 +++++
>  java/jakarta/el/VariableMapper.java                |  25 ++++-
>  java/jakarta/mail/Authenticator.java               |  18 ++++
>  java/jakarta/mail/PasswordAuthentication.java      |  12 +++
>  java/jakarta/mail/Session.java                     |  22 ++++
>  java/jakarta/mail/internet/InternetAddress.java    |  11 ++
>  java/jakarta/mail/internet/MimeMessage.java        |  19 ++++
>  java/jakarta/mail/internet/MimePart.java           |   4 +
>  java/jakarta/mail/internet/MimePartDataSource.java |   9 ++
>  java/jakarta/persistence/PersistenceContext.java   |  30 +++++-
>  .../persistence/PersistenceContextType.java        |  16 ++-
>  java/jakarta/persistence/PersistenceContexts.java  |   9 +-
>  java/jakarta/persistence/PersistenceProperty.java  |  15 ++-
>  java/jakarta/persistence/PersistenceUnit.java      |  16 ++-
>  java/jakarta/persistence/PersistenceUnits.java     |   9 +-
>  java/jakarta/persistence/SynchronizationType.java  |   9 ++
>  .../security/auth/message/AuthException.java       |  12 +++
>  java/jakarta/security/auth/message/AuthStatus.java |  23 +++++
>  java/jakarta/security/auth/message/ClientAuth.java |   4 +
>  .../jakarta/security/auth/message/MessageInfo.java |  38 +++++++
>  .../security/auth/message/MessagePolicy.java       |  99 ++++++++++++++++++
>  java/jakarta/security/auth/message/ServerAuth.java |   7 ++
>  .../message/callback/CallerPrincipalCallback.java  |  34 +++++-
>  .../auth/message/callback/CertStoreCallback.java   |  16 ++-
>  .../message/callback/GroupPrincipalCallback.java   |  19 ++++
>  .../callback/PasswordValidationCallback.java       |  49 ++++++++-
>  .../auth/message/callback/PrivateKeyCallback.java  | 113 +++++++++++++++++++-
>  .../auth/message/callback/SecretKeyCallback.java   |  37 +++++++
>  .../auth/message/callback/TrustStoreCallback.java  |  16 +++
>  .../security/auth/message/config/AuthConfig.java   |  31 ++++++
>  .../auth/message/config/AuthConfigFactory.java     | 112 ++++++++++++++++++++
>  .../auth/message/config/AuthConfigProvider.java    |  30 ++++++
>  .../auth/message/config/ClientAuthConfig.java      |  15 +++
>  .../auth/message/config/ClientAuthContext.java     |   5 +
>  .../auth/message/config/RegistrationListener.java  |   9 ++
>  .../auth/message/config/ServerAuthConfig.java      |  12 +++
>  .../auth/message/config/ServerAuthContext.java     |   7 ++
>  .../auth/message/module/ClientAuthModule.java      |  21 ++++
>  .../auth/message/module/ServerAuthModule.java      |  25 +++++
>  java/jakarta/servlet/AsyncContext.java             |  34 ++++--
>  java/jakarta/servlet/GenericFilter.java            |  13 ++-
>  java/jakarta/servlet/HttpConstraintElement.java    |  12 +--
>  java/jakarta/servlet/ServletContext.java           |  84 ++++++++++-----
>  java/jakarta/servlet/ServletRequest.java           |  53 ++++++----
>  java/jakarta/servlet/ServletRequestWrapper.java    |   8 +-
>  java/jakarta/servlet/ServletResponseWrapper.java   |   6 +-
>  java/jakarta/servlet/annotation/HandlesTypes.java  |   8 +-
>  .../servlet/annotation/MultipartConfig.java        |   9 ++
>  java/jakarta/servlet/annotation/WebFilter.java     |  22 +++-
>  java/jakarta/servlet/annotation/WebInitParam.java  |   6 ++
>  java/jakarta/servlet/annotation/WebListener.java   |   2 +
>  java/jakarta/servlet/annotation/WebServlet.java    |  86 ++++++++++------
>  java/jakarta/servlet/http/HttpFilter.java          |   7 ++
>  java/jakarta/servlet/http/HttpServletMapping.java  |  36 ++++---
>  java/jakarta/servlet/http/PushBuilder.java         |   6 +-
>  .../transaction/HeuristicCommitException.java      |  14 +++
>  .../transaction/HeuristicMixedException.java       |  14 +++
>  .../transaction/HeuristicRollbackException.java    |  14 +++
>  .../transaction/InvalidTransactionException.java   |  13 +++
>  .../jakarta/transaction/NotSupportedException.java |  11 ++
>  java/jakarta/transaction/RollbackException.java    |  11 ++
>  java/jakarta/transaction/Status.java               |  33 ++++++
>  java/jakarta/transaction/Synchronization.java      |  17 +++
>  java/jakarta/transaction/SystemException.java      |  21 ++++
>  java/jakarta/transaction/Transaction.java          |  63 ++++++++++++
>  java/jakarta/transaction/TransactionManager.java   |  68 ++++++++++++
>  .../transaction/TransactionRequiredException.java  |  11 ++
>  .../TransactionRolledbackException.java            |  11 ++
>  .../TransactionSynchronizationRegistry.java        |  40 ++++++++
>  java/jakarta/transaction/UserTransaction.java      |  47 +++++++++
>  java/jakarta/websocket/ClientEndpoint.java         |  25 +++++
>  java/jakarta/websocket/ClientEndpointConfig.java   |  82 +++++++++++++++
>  java/jakarta/websocket/CloseReason.java            | 106 +++++++++++++++++++
>  java/jakarta/websocket/ContainerProvider.java      |  11 ++
>  java/jakarta/websocket/DecodeException.java        |  45 ++++++++
>  java/jakarta/websocket/Decoder.java                |  68 ++++++++++++
>  java/jakarta/websocket/DeploymentException.java    |  14 +++
>  java/jakarta/websocket/EncodeException.java        |  24 +++++
>  java/jakarta/websocket/Encoder.java                |  58 ++++++++++-
>  java/jakarta/websocket/Endpoint.java               |  10 ++
>  java/jakarta/websocket/EndpointConfig.java         |  19 ++++
>  java/jakarta/websocket/Extension.java              |  28 +++++
>  java/jakarta/websocket/HandshakeResponse.java      |   8 ++
>  java/jakarta/websocket/MessageHandler.java         |  16 +++
>  java/jakarta/websocket/OnClose.java                |   4 +
>  java/jakarta/websocket/OnError.java                |   4 +
>  java/jakarta/websocket/OnMessage.java              |  11 ++
>  java/jakarta/websocket/OnOpen.java                 |   4 +
>  java/jakarta/websocket/RemoteEndpoint.java         |  22 ++++
>  java/jakarta/websocket/SendHandler.java            |   8 ++
>  java/jakarta/websocket/SendResult.java             |  14 +++
>  java/jakarta/websocket/Session.java                |  83 +++++++++++++++
>  java/jakarta/websocket/SessionException.java       |  18 ++++
>  java/jakarta/websocket/WebSocketContainer.java     |  22 ++++
>  .../jakarta/websocket/server/HandshakeRequest.java |  44 ++++++++
>  java/jakarta/websocket/server/PathParam.java       |   6 ++
>  java/jakarta/websocket/server/ServerContainer.java |  13 +++
>  java/jakarta/websocket/server/ServerEndpoint.java  |  25 +++++
>  .../websocket/server/ServerEndpointConfig.java     | 114 +++++++++++++++++++++
>  java/jakarta/xml/ws/WebServiceRef.java             |  31 +++++-
>  java/jakarta/xml/ws/WebServiceRefs.java            |  11 +-
>  145 files changed, 3585 insertions(+), 182 deletions(-)
>
> diff --git a/java/jakarta/annotation/Generated.java b/java/jakarta/annotation/Generated.java
> index 19cbed8bc6..8251be3970 100644
> --- a/java/jakarta/annotation/Generated.java
> +++ b/java/jakarta/annotation/Generated.java
> @@ -33,18 +33,26 @@ import java.lang.annotation.Target;
>  @Retention(RetentionPolicy.SOURCE)
>  public @interface Generated {
>      /**
> -     * @return The name of the code generator. It is recommended that the fully qualified name of the code generator is
> -     *             used.
> +     * Specifies the name(s) of the tool(s) that generated the annotated element.
> +     * It is recommended that the fully qualified name of the code generator is used.
> +     *
> +     * @return the array of code generator names
>       */
>      String[] value();
>
>      /**
> -     * @return The date the code was generated
> +     * Specifies the date and time when the code was generated, typically in
> +     * ISO 8601 format. An empty string indicates the date is not specified.
> +     *
> +     * @return the code generation date, or an empty string if not specified
>       */
>      String date() default "";
>
>      /**
> -     * @return Additional comments (if any) related to the code generation
> +     * Provides additional comments or metadata related to the code generation
> +     * process, such as version information or configuration details.
> +     *
> +     * @return additional comments about the code generation, or an empty string if none
>       */
>      String comments() default "";
>  }
> diff --git a/java/jakarta/annotation/Priority.java b/java/jakarta/annotation/Priority.java
> index c44be40d7f..4809275165 100644
> --- a/java/jakarta/annotation/Priority.java
> +++ b/java/jakarta/annotation/Priority.java
> @@ -31,7 +31,11 @@ import java.lang.annotation.RetentionPolicy;
>  public @interface Priority {
>
>      /**
> -     * @return the int value
> +     * Specifies the priority value used to determine the ordering of the annotated
> +     * element. Lower values indicate higher priority. The annotated class or
> +     * parameter defines how the priority value is interpreted and applied.
> +     *
> +     * @return the priority ordering value
>       */
>      int value();
>  }
> diff --git a/java/jakarta/annotation/Resource.java b/java/jakarta/annotation/Resource.java
> index 692d13418e..a66f5fc621 100644
> --- a/java/jakarta/annotation/Resource.java
> +++ b/java/jakarta/annotation/Resource.java
> @@ -48,7 +48,10 @@ public @interface Resource {
>      }
>
>      /**
> -     * @return a String with the name of the resource
> +     * Specifies the logical name of the resource. If not specified, the container
> +     * derives the name from the field or method to which the annotation is applied.
> +     *
> +     * @return the logical name of the resource
>       */
>      String name() default "";
>
> @@ -60,29 +63,49 @@ public @interface Resource {
>      Class<?> type() default Object.class;
>
>      /**
> -     * @return the AuthenticationType of the resource default CONTAINER
> +     * Specifies the authentication type for the resource. Container authentication
> +     * means the container handles authentication, while application authentication
> +     * means the application code is responsible for authentication.
> +     *
> +     * @return the authentication type, defaulting to {@link AuthenticationType#CONTAINER}
>       */
>      AuthenticationType authenticationType() default AuthenticationType.CONTAINER;
>
>      /**
> -     * @return true (default) if the resource is shareable, or false if not
> +     * Indicates whether the resource can be shared among multiple injection points.
> +     * When true, the same resource instance may be injected into multiple components.
> +     * When false, each injection point receives a distinct resource instance.
> +     *
> +     * @return true if the resource is shareable across injection points, false otherwise
>       */
>      boolean shareable() default true;
>
>      /**
> -     * @return a string with the description for the resource
> +     * Provides a human-readable description of the resource for documentation
> +     * and administrative purposes.
> +     *
> +     * @return the resource description
>       */
>      String description() default "";
>
>      /**
> -     * @return a string with the mappedName of the resource
> +     * Specifies a product-dependent name for the resource, allowing the container
> +     * to map the logical resource name to a physical resource in a vendor-specific
> +     * manner. This is typically used for environment-specific configuration.
> +     *
> +     * @return the product-specific mapped name for the resource
>       */
>      String mappedName() default "";
>
>      /**
> +     * Specifies the JNDI lookup name for the resource. This attribute allows
> +     * explicit control over the JNDI name used to locate the resource, overriding
> +     * the default name derivation. The lookup name is typically prefixed with
> +     * "java:comp/env/" for component environment entries.
> +     *
>       * @since Common Annotations 1.1
>       *
> -     * @return The name of the entry, if any, to use for this resource
> +     * @return the JNDI lookup name for the resource
>       */
>      String lookup() default "";
>  }
> diff --git a/java/jakarta/annotation/Resources.java b/java/jakarta/annotation/Resources.java
> index 6ade76d6a6..bf668c6f1f 100644
> --- a/java/jakarta/annotation/Resources.java
> +++ b/java/jakarta/annotation/Resources.java
> @@ -33,7 +33,10 @@ import java.lang.annotation.Target;
>  public @interface Resources {
>
>      /**
> -     * @return a Resource[] with the value of this Resources
> +     * Specifies the array of {@link Resource} annotations that define the resources
> +     * required by the annotated component.
> +     *
> +     * @return the array of resource definitions
>       */
>      Resource[] value();
>  }
> diff --git a/java/jakarta/annotation/security/DeclareRoles.java b/java/jakarta/annotation/security/DeclareRoles.java
> index 3762af6a94..434aea50fd 100644
> --- a/java/jakarta/annotation/security/DeclareRoles.java
> +++ b/java/jakarta/annotation/security/DeclareRoles.java
> @@ -23,6 +23,11 @@ import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
>  /**
> + * Declares that role names used in security constraints for the annotated
> + * enterprise bean should be treated as declared roles. When this annotation
> + * is present, the container must create any roles referenced in security
> + * constraints that are not explicitly defined in the deployment descriptor.
> + *
>   * @since Common Annotations 1.0
>   */
>  @Documented
> @@ -31,7 +36,11 @@ import java.lang.annotation.Target;
>  public @interface DeclareRoles {
>
>      /**
> -     * @return a String[] with the roles
> +     * Specifies the declared role names that should be recognized by the container.
> +     * These roles may be referenced in security constraints without being explicitly
> +     * defined in the deployment descriptor.
> +     *
> +     * @return the array of declared role names
>       */
>      String[] value();
>  }
> diff --git a/java/jakarta/annotation/security/DenyAll.java b/java/jakarta/annotation/security/DenyAll.java
> index 9944210ce7..10db8d2a76 100644
> --- a/java/jakarta/annotation/security/DenyAll.java
> +++ b/java/jakarta/annotation/security/DenyAll.java
> @@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
>  /**
> + * Indicates that all access to the annotated enterprise bean or business method
> + * is denied. When applied at the class level, all security roles are prohibited
> + * from invoking any business method of the bean. When applied at the method level,
> + * the specified method is inaccessible to all roles. This annotation takes
> + * precedence over {@link PermitAll} and {@link RolesAllowed}.
> + *
>   * @since Common Annotations 1.0
>   */
>  @Documented
> diff --git a/java/jakarta/annotation/security/PermitAll.java b/java/jakarta/annotation/security/PermitAll.java
> index 0e0c784c65..d129f8f2bc 100644
> --- a/java/jakarta/annotation/security/PermitAll.java
> +++ b/java/jakarta/annotation/security/PermitAll.java
> @@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
>  /**
> + * Indicates that all authenticated users are permitted to access the annotated
> + * enterprise bean or business method. When applied at the class level, any
> + * authenticated user may invoke any business method of the bean. When applied
> + * at the method level, the specified method is accessible to all authenticated
> + * users. This annotation takes precedence over {@link RolesAllowed}.
> + *
>   * @since Common Annotations 1.0
>   */
>  @Documented
> diff --git a/java/jakarta/annotation/security/RolesAllowed.java b/java/jakarta/annotation/security/RolesAllowed.java
> index 7092d01ab3..48b003de31 100644
> --- a/java/jakarta/annotation/security/RolesAllowed.java
> +++ b/java/jakarta/annotation/security/RolesAllowed.java
> @@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
>  /**
> + * Specifies the security roles that are allowed to access the annotated enterprise
> + * bean or business method. When applied at the class level, only the listed roles
> + * may invoke any business method of the bean. When applied at the method level,
> + * only the listed roles may invoke the specified method. This annotation is
> + * mutually exclusive with {@link PermitAll} and {@link DenyAll}.
> + *
>   * @since Common Annotations 1.0
>   */
>  @Documented
> @@ -31,7 +37,11 @@ import java.lang.annotation.Target;
>  public @interface RolesAllowed {
>
>      /**
> -     * @return a String[] of the allowed roles
> +     * Specifies the security role names that are authorized to access the
> +     * annotated component or method. Only callers assigned one of these roles
> +     * will be permitted access.
> +     *
> +     * @return the array of authorized role names
>       */
>      String[] value();
>  }
> diff --git a/java/jakarta/annotation/security/RunAs.java b/java/jakarta/annotation/security/RunAs.java
> index d5029b7ecc..8d935eb51c 100644
> --- a/java/jakarta/annotation/security/RunAs.java
> +++ b/java/jakarta/annotation/security/RunAs.java
> @@ -23,6 +23,11 @@ import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
>  /**
> + * Defines the run-as security role for an enterprise bean. The container assumes
> + * the specified role as the caller identity for all business method invocations
> + * made by the bean, regardless of the actual caller's identity. This allows the
> + * bean to access resources with a consistent security context.
> + *
>   * @since Common Annotations 1.0
>   */
>  @Documented
> @@ -31,7 +36,10 @@ import java.lang.annotation.Target;
>  public @interface RunAs {
>
>      /**
> -     * @return a String with the value for RunAs
> +     * Specifies the security role name that the container should assume as the
> +     * caller identity when executing business methods on behalf of this component.
> +     *
> +     * @return the run-as role name
>       */
>      String value();
>  }
> diff --git a/java/jakarta/annotation/sql/DataSourceDefinition.java b/java/jakarta/annotation/sql/DataSourceDefinition.java
> index 9e5c46d0f3..0bea20aa2b 100644
> --- a/java/jakarta/annotation/sql/DataSourceDefinition.java
> +++ b/java/jakarta/annotation/sql/DataSourceDefinition.java
> @@ -23,6 +23,12 @@ import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
>  /**
> + * Defines a data source for dependency injection via the {@link jakarta.annotation.Resource}
> + * annotation. This annotation allows developers to declaratively specify the properties
> + * of a JDBC data source, including connection details, pool sizing, and transactional
> + * behavior. The container creates and manages the data source based on the specified
> + * configuration, making it available for injection into application components.
> + *
>   * @since Common Annotations 1.1
>   */
>  @Target(ElementType.TYPE)
> @@ -31,92 +37,145 @@ import java.lang.annotation.Target;
>  public @interface DataSourceDefinition {
>
>      /**
> -     * @return the className
> +     * Specifies the fully qualified class name of the JDBC driver or the Jakarta
> +     * Connector connection factory class that implements this data source.
> +     *
> +     * @return the fully qualified class name of the data source implementation
>       */
>      String className();
>
>      /**
> -     * @return the name
> +     * Specifies the JNDI name under which the data source will be registered.
> +     * This is the lookup name used for dependency injection or explicit JNDI
> +     * lookup of the data source.
> +     *
> +     * @return the JNDI name for the data source
>       */
>      String name();
>
>      /**
> -     * @return the description
> +     * Provides a human-readable description of the data source for documentation
> +     * and administrative purposes.
> +     *
> +     * @return the description of the data source
>       */
>      String description() default "";
>
>      /**
> -     * @return the url
> +     * Specifies the JDBC connection URL for the database. This URL is used by
> +     * the driver to establish connections to the database server.
> +     *
> +     * @return the JDBC connection URL
>       */
>      String url() default "";
>
>      /**
> -     * @return the user
> +     * Specifies the database user name used to establish connections.
> +     *
> +     * @return the database user name
>       */
>      String user() default "";
>
>      /**
> -     * @return the password
> +     * Specifies the password for the database user account used to establish connections.
> +     *
> +     * @return the database password
>       */
>      String password() default "";
>
>      /**
> -     * @return database name
> +     * Specifies the name of the database to connect to. This is used in conjunction
> +     * with the server name and port number to locate the target database.
> +     *
> +     * @return the database name
>       */
>      String databaseName() default "";
>
>      /**
> -     * @return the port number
> +     * Specifies the network port number on which the database server is listening.
> +     * A value of -1 indicates the default port for the database type.
> +     *
> +     * @return the database server port number, or -1 for the default
>       */
>      int portNumber() default -1;
>
>      /**
> -     * @return the server name
> +     * Specifies the host name or IP address of the database server.
> +     *
> +     * @return the database server host name, defaulting to "localhost"
>       */
>      String serverName() default "localhost";
>
>      /**
> -     * @return the isolation level
> +     * Specifies the transaction isolation level for connections from this data source,
> +     * using the constants defined in {@link java.sql.Connection}. A value of -1
> +     * indicates the database default isolation level should be used.
> +     *
> +     * @return the transaction isolation level, or -1 for the database default
>       */
>      int isolationLevel() default -1;
>
>      /**
> -     * @return true if the data source is transactional
> +     * Indicates whether connections from this data source support container-managed
> +     * transactions. When true, the data source participates in Jakarta Transactions.
> +     *
> +     * @return true if the data source participates in container-managed transactions
>       */
>      boolean transactional() default true;
>
>      /**
> -     * @return the initial pool size
> +     * Specifies the number of connections to create when the connection pool is
> +     * initialized. A value of -1 indicates the container default should be used.
> +     *
> +     * @return the initial number of connections in the pool, or -1 for default
>       */
>      int initialPoolSize() default -1;
>
>      /**
> -     * @return the max pool size
> +     * Specifies the maximum number of connections that the pool may create.
> +     * A value of -1 indicates the container default should be used.
> +     *
> +     * @return the maximum pool size, or -1 for the container default
>       */
>      int maxPoolSize() default -1;
>
>      /**
> -     * @return the min pool size
> +     * Specifies the minimum number of connections that the pool must maintain.
> +     * A value of -1 indicates the container default should be used.
> +     *
> +     * @return the minimum pool size, or -1 for the container default
>       */
>      int minPoolSize() default -1;
>
>      /**
> -     * @return the max idle time
> +     * Specifies the maximum idle time in seconds before a connection is closed
> +     * and removed from the pool. A value of -1 indicates no idle timeout.
> +     *
> +     * @return the maximum idle time in seconds, or -1 for no timeout
>       */
>      int maxIdleTime() default -1;
>
>      /**
> -     * @return the max statements
> +     * Specifies the maximum number of prepared statements that may be cached
> +     * per connection in the pool. A value of -1 indicates the container default.
> +     *
> +     * @return the maximum cached prepared statements per connection, or -1 for default
>       */
>      int maxStatements() default -1;
>
>      /**
> -     * @return a String[] with the properties
> +     * Specifies additional connection properties in the form "name=value" strings.
> +     * These properties are passed to the JDBC driver during connection establishment.
> +     *
> +     * @return the array of additional connection properties
>       */
>      String[] properties() default {};
>
>      /**
> -     * @return the login timeout
> +     * Specifies the maximum time in seconds that the driver will wait when
> +     * attempting to connect to the database. A value of 0 means no timeout.
> +     *
> +     * @return the login timeout in seconds, or 0 for no timeout
>       */
>      int loginTimeout() default 0;
>  }
> diff --git a/java/jakarta/annotation/sql/DataSourceDefinitions.java b/java/jakarta/annotation/sql/DataSourceDefinitions.java
> index d40e357af5..ace5402e7a 100644
> --- a/java/jakarta/annotation/sql/DataSourceDefinitions.java
> +++ b/java/jakarta/annotation/sql/DataSourceDefinitions.java
> @@ -22,6 +22,10 @@ import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
>  /**
> + * Container annotation that holds multiple {@link DataSourceDefinition} annotations.
> + * This annotation is used to group several data source definitions when applied to
> + * the same type, following the standard Java annotation repetition pattern.
> + *
>   * @since Common Annotations 1.1
>   */
>  @Target(ElementType.TYPE)
> @@ -29,7 +33,9 @@ import java.lang.annotation.Target;
>  public @interface DataSourceDefinitions {
>
>      /**
> -     * @return a DataSourceDefinition[]
> +     * Specifies the array of data source definitions contained within this container annotation.
> +     *
> +     * @return the array of {@link DataSourceDefinition} annotations
>       */
>      DataSourceDefinition[] value();
>  }
> diff --git a/java/jakarta/ejb/EJB.java b/java/jakarta/ejb/EJB.java
> index cd5b24720c..94fab54075 100644
> --- a/java/jakarta/ejb/EJB.java
> +++ b/java/jakarta/ejb/EJB.java
> @@ -21,20 +21,56 @@ import java.lang.annotation.Retention;
>  import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
> +/**
> + * Declares a dependency on an enterprise bean. The EJB annotation can be applied to a field or method to inject
> + * a reference to an enterprise bean, or to a class to declare bean dependencies for the entire bean.
> + */
>  @Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD })
>  @Retention(RetentionPolicy.RUNTIME)
> -
>  public @interface EJB {
> +
> +    /**
> +     * The name element for the annotation. The name of an enterprise bean is relative to the javax.np.Context of
> +     * the bean. The name must be unique within the bean.
> +     *
> +     * @return the name of the enterprise bean
> +     */
>      String name() default "";
>
> +    /**
> +     * A description of the enterprise bean reference.
> +     *
> +     * @return the description
> +     */
>      String description() default "";
>
> +    /**
> +     * The interface of the enterprise bean.
> +     *
> +     * @return the bean interface class
> +     */
>      @SuppressWarnings("rawtypes") // Can't use Class<?> because API needs to match specification
>      Class beanInterface() default Object.class;
>
> +    /**
> +     * The name of the enterprise bean. The beanName is relative to the javax.naming.Context of the bean that
> +     * owns this reference.
> +     *
> +     * @return the name of the enterprise bean
> +     */
>      String beanName() default "";
>
> +    /**
> +     * A provider-specific name that this reference should be mapped to. The entire name is provider-specific.
> +     *
> +     * @return the provider-specific mapped name
> +     */
>      String mappedName() default "";
>
> +    /**
> +     * A JNDI name used to locate the enterprise bean. The lookup element overrides the default JNDI lookup name.
> +     *
> +     * @return the JNDI lookup string
> +     */
>      String lookup() default "";
>  }
> diff --git a/java/jakarta/ejb/EJBs.java b/java/jakarta/ejb/EJBs.java
> index 5f2647cb17..2457371609 100644
> --- a/java/jakarta/ejb/EJBs.java
> +++ b/java/jakarta/ejb/EJBs.java
> @@ -21,9 +21,18 @@ import java.lang.annotation.Retention;
>  import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
> +/**
> + * Groups multiple {@link EJB} annotations on a single declaration. Use this annotation when a class has dependencies
> + * on more than one enterprise bean.
> + */
>  @Target(ElementType.TYPE)
>  @Retention(RetentionPolicy.RUNTIME)
> -
>  public @interface EJBs {
> +
> +    /**
> +     * The array of EJB annotations.
> +     *
> +     * @return the EJB annotations
> +     */
>      EJB[] value();
>  }
> diff --git a/java/jakarta/el/BeanNameELResolver.java b/java/jakarta/el/BeanNameELResolver.java
> index 8331e310f4..248b08fe4f 100644
> --- a/java/jakarta/el/BeanNameELResolver.java
> +++ b/java/jakarta/el/BeanNameELResolver.java
> @@ -19,12 +19,20 @@ package jakarta.el;
>  import java.util.Objects;
>
>  /**
> + * ELResolver that resolves bean names to bean instances using a {@link BeanNameResolver}. This resolver handles
> + * expressions where the base is {@code null} and the property is a {@link String} representing a bean name.
> + *
>   * @since EL 3.0
>   */
>  public class BeanNameELResolver extends ELResolver {
>
>      private final BeanNameResolver beanNameResolver;
>
> +    /**
> +     * Constructs a BeanNameELResolver with the specified BeanNameResolver.
> +     *
> +     * @param beanNameResolver the resolver used to look up beans by name
> +     */
>      public BeanNameELResolver(BeanNameResolver beanNameResolver) {
>          this.beanNameResolver = beanNameResolver;
>      }
> diff --git a/java/jakarta/el/BeanNameResolver.java b/java/jakarta/el/BeanNameResolver.java
> index 17754a1553..c8ab3a8661 100644
> --- a/java/jakarta/el/BeanNameResolver.java
> +++ b/java/jakarta/el/BeanNameResolver.java
> @@ -18,12 +18,19 @@ package jakarta.el;
>
>  /**
>   * Base implementation that provides a minimal default implementation that is intended to be extended by application
> - * developers.
> + * developers. Subclasses define the logic for resolving bean names to bean instances, checking read-only status,
> + * and determining whether new beans can be created.
>   *
>   * @since EL 3.0
>   */
>  public abstract class BeanNameResolver {
>
> +    /**
> +     * Default constructor for subclasses.
> +     */
> +    public BeanNameResolver() {
> +    }
> +
>      /**
>       * Can this resolver resolve the given bean name?
>       *
> diff --git a/java/jakarta/el/CompositeELResolver.java b/java/jakarta/el/CompositeELResolver.java
> index 8c9c1fc335..4a73d13d72 100644
> --- a/java/jakarta/el/CompositeELResolver.java
> +++ b/java/jakarta/el/CompositeELResolver.java
> @@ -20,6 +20,11 @@ import java.util.HashSet;
>  import java.util.Objects;
>  import java.util.Set;
>
> +/**
> + * ELResolver that delegates to an ordered list of other ELResolvers. When a property operation is performed, each
> + * contained resolver is invoked in order until one resolves the property. This is the standard mechanism for
> + * building a resolver chain in an EL context.
> + */
>  public class CompositeELResolver extends ELResolver {
>
>      private static final Class<?> SCOPED_ATTRIBUTE_EL_RESOLVER;
> @@ -62,6 +67,9 @@ public class CompositeELResolver extends ELResolver {
>      private int typeConvertersSize;
>      private ELResolver[] typeConverters;
>
> +    /**
> +     * Constructs an empty CompositeELResolver. Use {@link #add(ELResolver)} to add resolvers to the chain.
> +     */
>      public CompositeELResolver() {
>          resolversSize = 0;
>          resolvers = new ELResolver[8];
> @@ -70,6 +78,13 @@ public class CompositeELResolver extends ELResolver {
>          typeConverters = new ELResolver[0];
>      }
>
> +    /**
> +     * Adds an ELResolver to the end of the resolver chain.
> +     *
> +     * @param elResolver the resolver to add
> +     *
> +     * @throws NullPointerException if elResolver is {@code null}
> +     */
>      public void add(ELResolver elResolver) {
>          Objects.requireNonNull(elResolver);
>
> diff --git a/java/jakarta/el/ELClass.java b/java/jakarta/el/ELClass.java
> index 0d003029ec..d72fd9bf0e 100644
> --- a/java/jakarta/el/ELClass.java
> +++ b/java/jakarta/el/ELClass.java
> @@ -17,16 +17,30 @@
>  package jakarta.el;
>
>  /**
> + * Wrapper for a {@link Class} object that enables access to static fields and methods from EL expressions. An
> + * ELClass instance is used as the base object when resolving static members, typically in conjunction with the
> + * {@link StaticFieldELResolver}.
> + *
>   * @since EL 3.0
>   */
>  public class ELClass {
>
>      private final Class<?> clazz;
>
> +    /**
> +     * Constructs an ELClass wrapping the specified Class.
> +     *
> +     * @param clazz the class to wrap
> +     */
>      public ELClass(Class<?> clazz) {
>          this.clazz = clazz;
>      }
>
> +    /**
> +     * Returns the wrapped Class.
> +     *
> +     * @return the wrapped Class
> +     */
>      public Class<?> getKlass() {
>          return clazz;
>      }
> diff --git a/java/jakarta/el/ELContext.java b/java/jakarta/el/ELContext.java
> index f99f82c0f7..d0f7e4adbe 100644
> --- a/java/jakarta/el/ELContext.java
> +++ b/java/jakarta/el/ELContext.java
> @@ -28,6 +28,11 @@ import java.util.Locale;
>  import java.util.Map;
>  import java.util.Objects;
>
> +/**
> + * Provides the context in which an EL expression is evaluated. An ELContext holds references to the
> + * {@link ELResolver}, {@link FunctionMapper}, {@link VariableMapper}, {@link ImportHandler}, locale, and other
> + * objects required for expression evaluation. Implementations include {@link StandardELContext}.
> + */
>  public abstract class ELContext {
>
>      private Locale locale;
> @@ -42,6 +47,9 @@ public abstract class ELContext {
>
>      private Deque<Map<String,Object>> lambdaArguments = null;
>
> +    /**
> +     * Constructs an ELContext with the resolved flag set to {@code false}.
> +     */
>      public ELContext() {
>          this.resolved = false;
>      }
> @@ -53,6 +61,13 @@ public abstract class ELContext {
>          return lambdaArguments;
>      }
>
> +    /**
> +     * Sets the internal flag indicating whether a property has been resolved during the current
> +     * evaluation step. This method is used by {@link ELResolver} implementations to signal that
> +     * they have handled the current base/property combination.
> +     *
> +     * @param resolved {@code true} if a property has been resolved, {@code false} otherwise
> +     */
>      public void setPropertyResolved(boolean resolved) {
>          this.resolved = resolved;
>      }
> @@ -70,6 +85,13 @@ public abstract class ELContext {
>          notifyPropertyResolved(base, property);
>      }
>
> +    /**
> +     * Returns whether a property has been resolved during the current evaluation step.
> +     * ELResolver implementations call {@link #setPropertyResolved(boolean)} to indicate resolution,
> +     * and the expression evaluator checks this flag to determine if resolution was successful.
> +     *
> +     * @return {@code true} if a property has been resolved, {@code false} otherwise
> +     */
>      public boolean isPropertyResolved() {
>          return this.resolved;
>      }
> @@ -110,6 +132,11 @@ public abstract class ELContext {
>          return this.map.get(key);
>      }
>
> +    /**
> +     * Returns the ELResolver used to resolve properties and method invocations during expression evaluation.
> +     *
> +     * @return the ELResolver for this context
> +     */
>      public abstract ELResolver getELResolver();
>
>      /**
> @@ -126,16 +153,39 @@ public abstract class ELContext {
>          return importHandler;
>      }
>
> +    /**
> +     * Returns the FunctionMapper used to resolve EL function names to Java methods during expression evaluation.
> +     *
> +     * @return the FunctionMapper for this context
> +     */
>      public abstract FunctionMapper getFunctionMapper();
>
> +    /**
> +     * Returns the locale associated with this EL context. The locale is used for type conversion
> +     * operations such as parsing numbers and dates during expression evaluation.
> +     *
> +     * @return the locale for this context, or {@code null} if not set
> +     */
>      public Locale getLocale() {
>          return this.locale;
>      }
>
> +    /**
> +     * Sets the locale for this EL context. The locale is used for type conversion operations
> +     * such as parsing numbers and dates during expression evaluation.
> +     *
> +     * @param locale the locale to use for this context
> +     */
>      public void setLocale(Locale locale) {
>          this.locale = locale;
>      }
>
> +    /**
> +     * Returns the VariableMapper used to resolve EL variable names to {@link ValueExpression}
> +     * instances during expression evaluation.
> +     *
> +     * @return the VariableMapper for this context
> +     */
>      public abstract VariableMapper getVariableMapper();
>
>      /**
> diff --git a/java/jakarta/el/ELContextEvent.java b/java/jakarta/el/ELContextEvent.java
> index b5bfda0e68..713e668b5e 100644
> --- a/java/jakarta/el/ELContextEvent.java
> +++ b/java/jakarta/el/ELContextEvent.java
> @@ -19,18 +19,31 @@ package jakarta.el;
>  import java.io.Serial;
>  import java.util.EventObject;
>
> +/**
> + * Event object passed to {@link ELContextListener} instances when an EL context is created or
> + * released. The source of this event is the {@link ELContext} that was created or released.
> + *
> + * @since EL 2.1
> + */
>  public class ELContextEvent extends EventObject {
>
>      @Serial
>      private static final long serialVersionUID = 1255131906285426769L;
>
>      /**
> +     * Constructs an ELContextEvent with the specified ELContext as its source.
> +     *
>       * @param source The EL context that was the source of this event
>       */
>      public ELContextEvent(ELContext source) {
>          super(source);
>      }
>
> +    /**
> +     * Returns the ELContext that is the source of this event.
> +     *
> +     * @return the ELContext associated with this event
> +     */
>      public ELContext getELContext() {
>          return (ELContext) this.getSource();
>      }
> diff --git a/java/jakarta/el/ELContextListener.java b/java/jakarta/el/ELContextListener.java
> index d161362da7..31fb003165 100644
> --- a/java/jakarta/el/ELContextListener.java
> +++ b/java/jakarta/el/ELContextListener.java
> @@ -16,8 +16,21 @@
>   */
>  package jakarta.el;
>
> +/**
> + * Listener interface for EL context lifecycle events. Implementations are notified when an
> + * {@link ELContext} is created or released, allowing them to perform initialization or
> + * cleanup operations on the context.
> + *
> + * @since EL 2.1
> + */
>  public interface ELContextListener extends java.util.EventListener {
>
> +    /**
> +     * Notification that an EL context has been created. Implementations can use this callback
> +     * to register resources, resolvers, or other objects with the newly created context.
> +     *
> +     * @param event the event containing the ELContext that was created
> +     */
>      void contextCreated(ELContextEvent event);
>
>  }
> diff --git a/java/jakarta/el/ELManager.java b/java/jakarta/el/ELManager.java
> index 4f552942cf..ae16a33909 100644
> --- a/java/jakarta/el/ELManager.java
> +++ b/java/jakarta/el/ELManager.java
> @@ -20,16 +20,38 @@ import java.lang.reflect.Method;
>  import java.util.Map;
>
>  /**
> + * Provides a simplified API for managing EL context, resolvers, functions, and variables. This class maintains a
> + * {@link StandardELContext} and provides convenience methods for adding resolvers, mapping functions, setting
> + * variables, and managing imports. It is used internally by {@link ELProcessor}.
> + *
>   * @since EL 3.0
>   */
>  public class ELManager {
>
>      private StandardELContext context = null;
>
> +    /**
> +     * Constructs an ELManager with a lazily initialized {@link StandardELContext}.
> +     */
> +    public ELManager() {
> +    }
> +
> +    /**
> +     * Returns the {@link ExpressionFactory} used to create and evaluate EL expressions.
> +     * The factory is obtained through the standard service discovery mechanism.
> +     *
> +     * @return the ExpressionFactory instance
> +     */
>      public static ExpressionFactory getExpressionFactory() {
>          return Util.getExpressionFactory();
>      }
>
> +    /**
> +     * Returns the {@link StandardELContext} managed by this ELManager, creating it on first access
> +     * if it does not already exist.
> +     *
> +     * @return the StandardELContext instance
> +     */
>      public StandardELContext getELContext() {
>          if (context == null) {
>              context = new StandardELContext(getExpressionFactory());
> @@ -38,40 +60,110 @@ public class ELManager {
>          return context;
>      }
>
> +    /**
> +     * Replaces the current EL context with a new {@link StandardELContext} initialized from the
> +     * given context. The new context copies the ELResolver chain, FunctionMapper, VariableMapper,
> +     * and other settings from the provided context.
> +     *
> +     * @param context the ELContext from which to initialize the new context
> +     *
> +     * @return the previous StandardELContext, or {@code null} if none existed
> +     */
>      public ELContext setELContext(ELContext context) {
>          StandardELContext oldContext = this.context;
>          this.context = new StandardELContext(context);
>          return oldContext;
>      }
>
> +    /**
> +     * Adds a {@link BeanNameELResolver} to the resolver chain that uses the given
> +     * {@link BeanNameResolver} to resolve top-level identifiers to managed beans.
> +     *
> +     * @param beanNameResolver the resolver for bean names
> +     */
>      public void addBeanNameResolver(BeanNameResolver beanNameResolver) {
>          getELContext().addELResolver(new BeanNameELResolver(beanNameResolver));
>      }
>
> +    /**
> +     * Adds an {@link ELResolver} to the front of the resolver chain in the managed EL context.
> +     * Resolvers added first have higher priority during property resolution.
> +     *
> +     * @param resolver the ELResolver to add
> +     */
>      public void addELResolver(ELResolver resolver) {
>          getELContext().addELResolver(resolver);
>      }
>
> +    /**
> +     * Maps a static method to an EL function name with the given prefix and local name.
> +     * The function can then be invoked in EL expressions as {@code prefix:function(args)}.
> +     *
> +     * @param prefix   the namespace prefix for the function
> +     * @param function the local function name
> +     * @param method   the static {@link java.lang.reflect.Method} to map
> +     */
>      public void mapFunction(String prefix, String function, Method method) {
>          getELContext().getFunctionMapper().mapFunction(prefix, function, method);
>      }
>
> +    /**
> +     * Registers a variable in the EL context's variable mapper. The variable can then be
> +     * referenced by name in EL expressions. Passing a {@code null} expression removes
> +     * the variable.
> +     *
> +     * @param variable   the variable name
> +     * @param expression the ValueExpression associated with the variable, or {@code null} to remove
> +     */
>      public void setVariable(String variable, ValueExpression expression) {
>          getELContext().getVariableMapper().setVariable(variable, expression);
>      }
>
> +    /**
> +     * Imports a static field or method so it can be referenced by its simple name in EL
> +     * expressions. The argument must be a fully qualified name in the form
> +     * {@code className.staticMemberName}.
> +     *
> +     * @param staticMemberName the fully qualified name of the static member to import
> +     *
> +     * @throws ELException if the static member cannot be found or is ambiguous
> +     */
>      public void importStatic(String staticMemberName) throws ELException {
>          getELContext().getImportHandler().importStatic(staticMemberName);
>      }
>
> +    /**
> +     * Imports a class so it can be referenced by its simple name in EL expressions.
> +     * The argument must be a fully qualified class name.
> +     *
> +     * @param className the fully qualified class name to import
> +     *
> +     * @throws ELException if the class name is invalid or conflicts with an existing import
> +     */
>      public void importClass(String className) throws ELException {
>          getELContext().getImportHandler().importClass(className);
>      }
>
> +    /**
> +     * Imports all classes from a package so they can be referenced by their simple names
> +     * in EL expressions.
> +     *
> +     * @param packageName the package name to import
> +     */
>      public void importPackage(String packageName) {
>          getELContext().getImportHandler().importPackage(packageName);
>      }
>
> +    /**
> +     * Defines or removes a bean accessible by name in EL expressions. When a non-null bean
> +     * is provided, it is stored under the given name. When {@code null} is provided, the
> +     * bean with the given name is removed.
> +     *
> +     * @param name  the bean name
> +     * @param bean  the bean object to define, or {@code null} to remove the bean
> +     *
> +     * @return the previous bean associated with the name, or {@code null} if there was none
> +     */
>      public Object defineBean(String name, Object bean) {
>          Map<String,Object> localBeans = getELContext().getLocalBeans();
>
> @@ -82,6 +174,12 @@ public class ELManager {
>          }
>      }
>
> +    /**
> +     * Registers an {@link EvaluationListener} with the managed EL context. The listener
> +     * will be notified before and after expression evaluation, and when properties are resolved.
> +     *
> +     * @param listener the EvaluationListener to register
> +     */
>      public void addEvaluationListener(EvaluationListener listener) {
>          getELContext().addEvaluationListener(listener);
>      }
> diff --git a/java/jakarta/el/ELProcessor.java b/java/jakarta/el/ELProcessor.java
> index d3f10f17b9..0b3795116e 100644
> --- a/java/jakarta/el/ELProcessor.java
> +++ b/java/jakarta/el/ELProcessor.java
> @@ -22,6 +22,10 @@ import java.util.HashSet;
>  import java.util.Set;
>
>  /**
> + * Provides a simple API for evaluating EL expressions in a standalone environment. This class wraps an
> + * {@link ELManager} and provides methods for evaluating expressions, defining beans and functions, and managing
> + * variables. It is the primary entry point for applications that use the EL API outside of a Jakarta EE container.
> + *
>   * @since EL 3.0
>   */
>  public class ELProcessor {
> @@ -44,31 +48,82 @@ public class ELProcessor {
>      private final ELContext context = manager.getELContext();
>      private final ExpressionFactory factory = ELManager.getExpressionFactory();
>
> +    /**
> +     * Constructs an ELProcessor with a default {@link ELManager} and {@link StandardELContext}.
> +     * The processor is ready to evaluate expressions immediately after construction.
> +     */
> +    public ELProcessor() {
> +    }
>
> +    /**
> +     * Returns the {@link ELManager} that manages the EL context, resolvers, functions, and
> +     * variables for this processor.
> +     *
> +     * @return the ELManager instance
> +     */
>      public ELManager getELManager() {
>          return manager;
>      }
>
> -
> +    /**
> +     * Evaluates the given EL expression and returns the result as the requested type.
> +     * The expression is automatically wrapped in {@literal ${}} delimiters before evaluation.
> +     *
> +     * @param <T>        the expected result type
> +     * @param expression the EL expression to evaluate
> +     *
> +     * @return the result of evaluating the expression, coerced to the requested type
> +     *
> +     * @throws ELException if the expression cannot be evaluated
> +     */
>      public <T> T eval(String expression) {
>          @SuppressWarnings("unchecked")
>          T result = (T) getValue(expression, Object.class);
>          return result;
>      }
>
> -
> +    /**
> +     * Evaluates the given EL expression and returns the result coerced to the expected type.
> +     * The expression is automatically wrapped in {@literal ${}} delimiters before evaluation.
> +     *
> +     * @param <T>            the expected result type
> +     * @param expression     the EL expression to evaluate
> +     * @param expectedType   the class of the expected result type
> +     *
> +     * @return the result of evaluating the expression, coerced to the expected type
> +     *
> +     * @throws ELException if the expression cannot be evaluated
> +     */
>      public <T> T getValue(String expression, Class<T> expectedType) {
>          ValueExpression ve = factory.createValueExpression(context, bracket(expression), expectedType);
>          return ve.getValue(context);
>      }
>
> -
> +    /**
> +     * Evaluates the given EL expression and sets the result to the specified value.
> +     * This is used for EL assignment expressions. The expression is automatically wrapped
> +     * in {@literal ${}} delimiters before evaluation.
> +     *
> +     * @param expression the EL expression to evaluate
> +     * @param value      the value to assign
> +     *
> +     * @throws ELException if the expression cannot be evaluated or the target is not writable
> +     */
>      public void setValue(String expression, Object value) {
>          ValueExpression ve = factory.createValueExpression(context, bracket(expression), Object.class);
>          ve.setValue(context, value);
>      }
>
> -
> +    /**
> +     * Registers a variable in the EL context. The variable is associated with the result
> +     * of evaluating the given expression. Passing a {@code null} expression removes the
> +     * variable from the context.
> +     *
> +     * @param variable   the variable name
> +     * @param expression the EL expression to associate with the variable, or {@code null} to remove
> +     *
> +     * @throws ELException if the expression cannot be evaluated
> +     */
>      public void setVariable(String variable, String expression) {
>          if (expression == null) {
>              manager.setVariable(variable, null);
> @@ -78,7 +133,20 @@ public class ELProcessor {
>          }
>      }
>
> -
> +    /**
> +     * Registers a function in the EL context by looking up the static method in the given class.
> +     * The method name may include a return type and parameter signature in the format
> +     * {@code returnType methodName(paramTypes)}. The function is then callable in EL expressions
> +     * as {@code prefix:function(args)}.
> +     *
> +     * @param prefix     the namespace prefix for the function
> +     * @param function   the local function name, or empty to use the method name
> +     * @param className  the fully qualified name of the class containing the static method
> +     * @param methodName the method name, optionally with return type and parameter signature
> +     *
> +     * @throws ClassNotFoundException  if the class cannot be found or is not public
> +     * @throws NoSuchMethodException   if the method cannot be found or is not a public static method
> +     */
>      public void defineFunction(String prefix, String function, String className, String methodName)
>              throws ClassNotFoundException, NoSuchMethodException {
>
> @@ -188,6 +256,14 @@ public class ELProcessor {
>      }
>
>
> +    /**
> +     * Defines or removes a bean accessible by name in EL expressions. When a non-null bean
> +     * is provided, it is stored under the given name. When {@code null} is provided, the
> +     * bean with the given name is removed.
> +     *
> +     * @param name the bean name
> +     * @param bean the bean object to define, or {@code null} to remove the bean
> +     */
>      public void defineBean(String name, Object bean) {
>          manager.defineBean(name, bean);
>      }
> diff --git a/java/jakarta/el/ELResolver.java b/java/jakarta/el/ELResolver.java
> index e7dad5afcd..deaef98f2a 100644
> --- a/java/jakarta/el/ELResolver.java
> +++ b/java/jakarta/el/ELResolver.java
> @@ -16,8 +16,25 @@
>   */
>  package jakarta.el;
>
> +/**
> + * Base class for resolvers that resolve property references during EL expression evaluation.
> + * An ELResolver is responsible for resolving a property on a base object, determining its type,
> + * setting its value, and reporting whether it is read-only. Resolvers are chained together in
> + * an {@link ELContext}, and each resolver in the chain attempts to resolve the property until
> + * one succeeds. Implementations include {@link ListELResolver}, {@link MapELResolver}, and
> + * custom resolvers for application-specific object models.
> + *
> + * @since EL 2.1
> + */
>  public abstract class ELResolver {
>
> +    /**
> +     * Constructs an ELResolver. Subclasses should invoke this constructor to initialize
> +     * the base resolver state.
> +     */
> +    public ELResolver() {
> +    }
> +
>      /**
>       * Obtain the value of the given property on the given object using the given context.
>       *
> diff --git a/java/jakarta/el/EvaluationListener.java b/java/jakarta/el/EvaluationListener.java
> index 68c30985e0..836fac9e75 100644
> --- a/java/jakarta/el/EvaluationListener.java
> +++ b/java/jakarta/el/EvaluationListener.java
> @@ -17,10 +17,20 @@
>  package jakarta.el;
>
>  /**
> + * Listener interface for monitoring EL expression evaluation events. Implementations can track when expressions are
> + * evaluated and when properties are resolved during evaluation. Register an instance with an {@link ELContext} using
> + * {@link ELContext#addEvaluationListener(EvaluationListener)}.
> + *
>   * @since EL 3.0
>   */
>  public abstract class EvaluationListener {
>
> +    /**
> +     * Constructs an EvaluationListener.
> +     */
> +    public EvaluationListener() {
> +    }
> +
>      /**
>       * Fired before the evaluation of the expression.
>       *
> diff --git a/java/jakarta/el/Expression.java b/java/jakarta/el/Expression.java
> index 9c833768d4..b241e37415 100644
> --- a/java/jakarta/el/Expression.java
> +++ b/java/jakarta/el/Expression.java
> @@ -20,13 +20,26 @@ import java.io.Serial;
>  import java.io.Serializable;
>
>  /**
> - *
> + * Base class for EL expression objects. An Expression represents a compiled EL expression that can be evaluated.
> + * Subclasses include {@link ValueExpression} and {@link MethodExpression}.
>   */
>  public abstract class Expression implements Serializable {
>
>      @Serial
>      private static final long serialVersionUID = -6663767980471823812L;
>
> +    /**
> +     * Constructs an Expression. Subclasses should invoke this constructor to initialize
> +     * the base expression state.
> +     */
> +    public Expression() {
> +    }
> +
> +    /**
> +     * Returns the original string representation of this EL expression as it was parsed.
> +     *
> +     * @return the string representation of this expression
> +     */
>      public abstract String getExpressionString();
>
>      @Override
> @@ -35,6 +48,12 @@ public abstract class Expression implements Serializable {
>      @Override
>      public abstract int hashCode();
>
> +    /**
> +     * Returns whether this expression is a literal text expression, meaning it does not
> +     * contain any variables, functions, or operators and evaluates to a constant value.
> +     *
> +     * @return {@code true} if this expression is a literal text, {@code false} otherwise
> +     */
>      public abstract boolean isLiteralText();
>
>  }
> diff --git a/java/jakarta/el/ExpressionFactory.java b/java/jakarta/el/ExpressionFactory.java
> index bda510cea1..e327f7338b 100644
> --- a/java/jakarta/el/ExpressionFactory.java
> +++ b/java/jakarta/el/ExpressionFactory.java
> @@ -35,10 +35,21 @@ import java.util.concurrent.locks.ReadWriteLock;
>  import java.util.concurrent.locks.ReentrantReadWriteLock;
>
>  /**
> - * @since 2.1
> + * Factory for creating {@link ValueExpression} and {@link MethodExpression} instances, and for coercing objects to
> + * specific types. Implementations parse and compile EL expressions. Use {@link #newInstance()} to obtain an instance
> + * using the standard discovery mechanism.
> + *
> + * @since EL 2.1
>   */
>  public abstract class ExpressionFactory {
>
> +    /**
> +     * Constructs an ExpressionFactory. Subclasses should invoke this constructor to initialize
> +     * the base factory state.
> +     */
> +    public ExpressionFactory() {
> +    }
> +
>      private static final String PROPERTY_NAME = "jakarta.el.ExpressionFactory";
>
>      private static final String PROPERTY_FILE =
> @@ -170,6 +181,16 @@ public abstract class ExpressionFactory {
>       */
>      public abstract ValueExpression createValueExpression(ELContext context, String expression, Class<?> expectedType);
>
> +    /**
> +     * Creates a {@link ValueExpression} that, when evaluated, returns the given instance
> +     * of the specified type. This is a convenience method for creating a constant value
> +     * expression without requiring an {@link ELContext}.
> +     *
> +     * @param instance     the constant value to wrap
> +     * @param expectedType the expected type of the value
> +     *
> +     * @return a ValueExpression that returns the given instance when evaluated
> +     */
>      public abstract ValueExpression createValueExpression(Object instance, Class<?> expectedType);
>
>      /**
> @@ -202,7 +223,11 @@ public abstract class ExpressionFactory {
>      public abstract <T> T coerceToType(Object obj, Class<T> expectedType);
>
>      /**
> -     * @return This default implementation returns null
> +     * Returns an {@link ELResolver} capable of resolving properties on {@link java.io.InputStream}
> +     * objects, enabling EL expressions to operate on stream types. This allows expressions to
> +     * read data from input streams using standard property navigation syntax.
> +     *
> +     * @return the StreamELResolver, or {@code null} if not supported by this implementation
>       *
>       * @since EL 3.0
>       */
> @@ -211,7 +236,11 @@ public abstract class ExpressionFactory {
>      }
>
>      /**
> -     * @return This default implementation returns null
> +     * Returns a map of function names to {@link java.lang.reflect.Method} objects representing
> +     * the standard EL functions that are available by default without explicit registration.
> +     * Implementations can override this method to provide a set of built-in functions.
> +     *
> +     * @return a map of function names to methods, or {@code null} if no default functions are provided
>       *
>       * @since EL 3.0
>       */
> diff --git a/java/jakarta/el/FunctionMapper.java b/java/jakarta/el/FunctionMapper.java
> index 036f12b7d2..fc3fc7c92a 100644
> --- a/java/jakarta/el/FunctionMapper.java
> +++ b/java/jakarta/el/FunctionMapper.java
> @@ -18,8 +18,32 @@ package jakarta.el;
>
>  import java.lang.reflect.Method;
>
> +/**
> + * Abstract base class for mapping EL function names to Java {@link java.lang.reflect.Method}
> + * objects. During expression evaluation, the EL implementation uses the FunctionMapper to
> + * resolve function references of the form {@code prefix:functionName} to the corresponding
> + * static Java methods. Implementations maintain a registry of function prefixes and names
> + * mapped to their underlying methods.
> + *
> + * @since EL 2.1
> + */
>  public abstract class FunctionMapper {
>
> +    /**
> +     * Constructs a FunctionMapper. Subclasses should invoke this constructor to initialize
> +     * the base mapper state.
> +     */
> +    public FunctionMapper() {
> +    }
> +
> +    /**
> +     * Resolves a function reference to its corresponding static {@link java.lang.reflect.Method}.
> +     *
> +     * @param prefix    the namespace prefix of the function
> +     * @param localName the local name of the function
> +     *
> +     * @return the {@link Method} object for the resolved function, or {@code null} if not found
> +     */
>      public abstract Method resolveFunction(String prefix, String localName);
>
>      /**
> diff --git a/java/jakarta/el/ImportHandler.java b/java/jakarta/el/ImportHandler.java
> index 2b0725b71e..5885f25730 100644
> --- a/java/jakarta/el/ImportHandler.java
> +++ b/java/jakarta/el/ImportHandler.java
> @@ -28,6 +28,10 @@ import java.util.Set;
>  import java.util.concurrent.ConcurrentHashMap;
>
>  /**
> + * Manages class and package imports for EL expressions, similar to Java import statements. The ImportHandler resolves
> + * unqualified class names to their fully qualified counterparts, supports static imports, and maintains a set of
> + * standard packages that are automatically available in EL expressions.
> + *
>   * @since EL 3.0
>   */
>  public class ImportHandler {
> @@ -289,11 +293,24 @@ public class ImportHandler {
>      private final Map<String,Class<?>> statics = new ConcurrentHashMap<>();
>
>
> +    /**
> +     * Constructs an ImportHandler with the {@code java.lang} package pre-imported.
> +     * The {@code java.lang} package is automatically available in all EL expressions.
> +     */
>      public ImportHandler() {
>          importPackage("java.lang");
>      }
>
> -
> +    /**
> +     * Imports a static field or method so it can be referenced by its simple name in EL
> +     * expressions. The argument must be a fully qualified name in the form
> +     * {@code className.staticMemberName}. The static member must be public.
> +     *
> +     * @param name the fully qualified name of the static member to import
> +     *
> +     * @throws ELException if the name is invalid, the class cannot be found, the static
> +     *                       member does not exist, or the import would be ambiguous
> +     */
>      public void importStatic(String name) throws ELException {
>          int lastPeriod = name.lastIndexOf('.');
>
> @@ -349,6 +366,15 @@ public class ImportHandler {
>      }
>
>
> +    /**
> +     * Imports a class so it can be referenced by its simple name in EL expressions.
> +     * The argument must be a fully qualified class name. If the simple name conflicts
> +     * with a previously imported class, an exception is thrown.
> +     *
> +     * @param name the fully qualified class name to import
> +     *
> +     * @throws ELException if the class name is invalid or conflicts with an existing import
> +     */
>      public void importClass(String name) throws ELException {
>          int lastPeriodIndex = name.lastIndexOf('.');
>
> @@ -366,6 +392,14 @@ public class ImportHandler {
>      }
>
>
> +    /**
> +     * Imports all classes from a package so they can be referenced by their simple names
> +     * in EL expressions. Classes from the imported package are resolved during expression
> +     * evaluation. If a simple name is ambiguous across multiple imported packages, an
> +     * {@link ELException} is thrown at resolution time.
> +     *
> +     * @param name the package name to import
> +     */
>      public void importPackage(String name) {
>          // Import ambiguity is handled at resolution, not at import
>          // Whether the package exists is not checked,
> @@ -377,6 +411,18 @@ public class ImportHandler {
>      }
>
>
> +    /**
> +     * Resolves an unqualified class name to a {@link Class} object by searching the
> +     * registered class imports and package imports. The name must not contain a dot.
> +     * Results are cached for performance. If the name is ambiguous across multiple
> +     * packages, an {@link ELException} is thrown.
> +     *
> +     * @param name the unqualified class name to resolve
> +     *
> +     * @return the resolved {@link Class}, or {@code null} if the class cannot be found
> +     *
> +     * @throws ELException if the class name is ambiguous across imported packages
> +     */
>      public Class<?> resolveClass(String name) {
>          if (name == null || name.contains(".")) {
>              return null;
> @@ -445,6 +491,15 @@ public class ImportHandler {
>      }
>
>
> +    /**
> +     * Resolves a statically imported member name to the {@link Class} that declares it.
> +     * The name is the simple name of the static field or method as registered by
> +     * {@link #importStatic(String)}.
> +     *
> +     * @param name the simple name of the static member
> +     *
> +     * @return the declaring {@link Class}, or {@code null} if not found
> +     */
>      public Class<?> resolveStatic(String name) {
>          return statics.get(name);
>      }
> diff --git a/java/jakarta/el/LambdaExpression.java b/java/jakarta/el/LambdaExpression.java
> index fe7d9ca233..757a47cf24 100644
> --- a/java/jakarta/el/LambdaExpression.java
> +++ b/java/jakarta/el/LambdaExpression.java
> @@ -21,6 +21,14 @@ import java.util.List;
>  import java.util.Map;
>  import java.util.Objects;
>
> +/**
> + * Represents a lambda expression in EL. A lambda expression has a list of formal parameters
> + * and a body expression. When invoked, the lambda binds the actual arguments to its formal
> + * parameters and evaluates the body expression within a scoped {@link ELContext}. Lambda
> + * expressions support nesting, with inner lambdas having access to outer lambda arguments.
> + *
> + * @since EL 3.0
> + */
>  public class LambdaExpression {
>
>      private final List<String> formalParameters;
> @@ -28,16 +36,42 @@ public class LambdaExpression {
>      private final Map<String,Object> nestedArguments = new HashMap<>();
>      private ELContext context = null;
>
> +    /**
> +     * Constructs a LambdaExpression with the given formal parameters and body expression.
> +     *
> +     * @param formalParameters the list of formal parameter names for the lambda
> +     * @param expression       the body expression to evaluate when the lambda is invoked
> +     */
>      public LambdaExpression(List<String> formalParameters, ValueExpression expression) {
>          this.formalParameters = formalParameters;
>          this.expression = expression;
>
>      }
>
> +    /**
> +     * Sets the {@link ELContext} to be used when this lambda is invoked without an explicit
> +     * context argument. This is called automatically when the lambda is coerced to a
> +     * functional interface type.
> +     *
> +     * @param context the ELContext to use for evaluation
> +     */
>      public void setELContext(ELContext context) {
>          this.context = context;
>      }
>
> +    /**
> +     * Invokes the lambda expression with the given arguments in the specified EL context.
> +     * The formal parameters are bound to the corresponding arguments, and the body
> +     * expression is evaluated within a lambda scope. If the result is another lambda,
> +     * the current arguments are made available to the nested lambda.
> +     *
> +     * @param context the ELContext in which to evaluate the lambda
> +     * @param args    the actual arguments to bind to the formal parameters
> +     *
> +     * @return the result of evaluating the lambda body expression
> +     *
> +     * @throws ELException if the number of arguments is less than the number of formal parameters
> +     */
>      @SuppressWarnings("null") // args[i] can't be null due to earlier checks
>      public Object invoke(ELContext context, Object... args) throws ELException {
>
> @@ -81,6 +115,17 @@ public class LambdaExpression {
>          }
>      }
>
> +    /**
> +     * Invokes the lambda expression with the given arguments using the EL context set by
> +     * {@link #setELContext(ELContext)}. This is a convenience method for use when the
> +     * lambda has been assigned to a functional interface variable.
> +     *
> +     * @param args the actual arguments to bind to the formal parameters
> +     *
> +     * @return the result of evaluating the lambda body expression
> +     *
> +     * @throws ELException if the number of arguments is less than the number of formal parameters
> +     */
>      public Object invoke(Object... args) {
>          return invoke(context, args);
>      }
> diff --git a/java/jakarta/el/ListELResolver.java b/java/jakarta/el/ListELResolver.java
> index 13c73e16f6..34b0b15267 100644
> --- a/java/jakarta/el/ListELResolver.java
> +++ b/java/jakarta/el/ListELResolver.java
> @@ -21,6 +21,14 @@ import java.util.Collections;
>  import java.util.List;
>  import java.util.Objects;
>
> +/**
> + * An {@link ELResolver} that resolves properties on {@link java.util.List} objects using
> + * integer indices. When the base object is a {@code List}, the property is coerced to an
> + * integer and used as the list index. This resolver supports read and write operations,
> + * and can be configured as read-only to prevent modification of list elements.
> + *
> + * @since EL 2.1
> + */
>  public class ListELResolver extends ELResolver {
>
>      private final boolean readOnly;
> @@ -29,10 +37,20 @@ public class ListELResolver extends ELResolver {
>      // classes. Java 9 + so a back-port would require JreCompat.
>      private static final Class<?> UNMODIFIABLE = Collections.unmodifiableList(new ArrayList<>()).getClass();
>
> +    /**
> +     * Constructs a ListELResolver that allows both read and write operations on lists.
> +     */
>      public ListELResolver() {
>          this.readOnly = false;
>      }
>
> +    /**
> +     * Constructs a ListELResolver with the specified read-only setting. When read-only
> +     * is {@code true}, attempts to set values on list elements will throw a
> +     * {@link PropertyNotWritableException}.
> +     *
> +     * @param readOnly {@code true} if this resolver should be read-only, {@code false} otherwise
> +     */
>      public ListELResolver(boolean readOnly) {
>          this.readOnly = readOnly;
>      }
> diff --git a/java/jakarta/el/MapELResolver.java b/java/jakarta/el/MapELResolver.java
> index 973d2ee35d..32272a8916 100644
> --- a/java/jakarta/el/MapELResolver.java
> +++ b/java/jakarta/el/MapELResolver.java
> @@ -21,16 +21,34 @@ import java.util.HashMap;
>  import java.util.Map;
>  import java.util.Objects;
>
> +/**
> + * An {@link ELResolver} that resolves properties on {@link java.util.Map} objects using
> + * the property as a map key. When the base object is a {@code Map}, the property is used
> + * directly as the key to look up or set values. This resolver supports read and write
> + * operations, and can be configured as read-only to prevent modification of map entries.
> + *
> + * @since EL 2.1
> + */
>  public class MapELResolver extends ELResolver {
>
>      private static final Class<?> UNMODIFIABLE = Collections.unmodifiableMap(new HashMap<>()).getClass();
>
>      private final boolean readOnly;
>
> +    /**
> +     * Constructs a MapELResolver that allows both read and write operations on maps.
> +     */
>      public MapELResolver() {
>          this.readOnly = false;
>      }
>
> +    /**
> +     * Constructs a MapELResolver with the specified read-only setting. When read-only
> +     * is {@code true}, attempts to set values on map entries will throw a
> +     * {@link PropertyNotWritableException}.
> +     *
> +     * @param readOnly {@code true} if this resolver should be read-only, {@code false} otherwise
> +     */
>      public MapELResolver(boolean readOnly) {
>          this.readOnly = readOnly;
>      }
> diff --git a/java/jakarta/el/MethodExpression.java b/java/jakarta/el/MethodExpression.java
> index 715cf43bb9..876619b07f 100644
> --- a/java/jakarta/el/MethodExpression.java
> +++ b/java/jakarta/el/MethodExpression.java
> @@ -18,12 +18,24 @@ package jakarta.el;
>
>  import java.io.Serial;
>
> +/**
> + * Represents a compiled EL method expression. A MethodExpression is the result of compiling an EL expression
> + * that resolves to a method, and can be invoked at a later time with a given set of parameters.
> + */
>  public abstract class MethodExpression extends Expression {
>
>      @Serial
>      private static final long serialVersionUID = 8163925562047324656L;
>
>      /**
> +     * Constructs a MethodExpression.
> +     */
> +    public MethodExpression() {
> +    }
> +
> +    /**
> +     * Returns information about the method that this expression resolves to.
> +     *
>       * @param context The EL context for this evaluation
>       *
>       * @return Information about the method that this expression resolves to
> @@ -37,6 +49,8 @@ public abstract class MethodExpression extends Expression {
>      public abstract MethodInfo getMethodInfo(ELContext context);
>
>      /**
> +     * Invokes the method that this expression resolves to with the given parameters.
> +     *
>       * @param context The EL context for this evaluation
>       * @param params  The parameters with which to invoke this method expression
>       *
> @@ -52,6 +66,8 @@ public abstract class MethodExpression extends Expression {
>      public abstract Object invoke(ELContext context, Object[] params);
>
>      /**
> +     * Returns whether the parameters for the method invocation are provided by the expression or by the container.
> +     *
>       * @return This default implementation always returns <code>false</code>
>       *
>       * @since EL 3.0
> diff --git a/java/jakarta/el/MethodInfo.java b/java/jakarta/el/MethodInfo.java
> index 3dbcfe75a1..034433d303 100644
> --- a/java/jakarta/el/MethodInfo.java
> +++ b/java/jakarta/el/MethodInfo.java
> @@ -18,28 +18,57 @@ package jakarta.el;
>
>  import java.util.Arrays;
>
> +/**
> + * Holds metadata about a method that an EL method expression resolves to, including the method name,
> + * return type, and parameter types.
> + */
>  public class MethodInfo {
>
> +    /** The name of the method. */
>      private final String name;
>
> +    /** The parameter types of the method. */
>      private final Class<?>[] paramTypes;
>
> +    /** The return type of the method. */
>      private final Class<?> returnType;
>
> +    /**
> +     * Constructs a MethodInfo with the given name, return type, and parameter types.
> +     *
> +     * @param name       The name of the method
> +     * @param returnType The return type of the method
> +     * @param paramTypes The parameter types of the method
> +     */
>      public MethodInfo(String name, Class<?> returnType, Class<?>[] paramTypes) {
>          this.name = name;
>          this.returnType = returnType;
>          this.paramTypes = paramTypes;
>      }
>
> +    /**
> +     * Returns the name of the method.
> +     *
> +     * @return the method name
> +     */
>      public String getName() {
>          return this.name;
>      }
>
> +    /**
> +     * Returns the return type of the method.
> +     *
> +     * @return the return type
> +     */
>      public Class<?> getReturnType() {
>          return this.returnType;
>      }
>
> +    /**
> +     * Returns the parameter types of the method.
> +     *
> +     * @return the parameter types
> +     */
>      public Class<?>[] getParamTypes() {
>          return this.paramTypes;
>      }
> diff --git a/java/jakarta/el/MethodNotFoundException.java b/java/jakarta/el/MethodNotFoundException.java
> index 8a92baf0f3..7232656c97 100644
> --- a/java/jakarta/el/MethodNotFoundException.java
> +++ b/java/jakarta/el/MethodNotFoundException.java
> @@ -18,23 +18,45 @@ package jakarta.el;
>
>  import java.io.Serial;
>
> +/**
> + * Thrown when a method referenced in an EL expression cannot be found on the target object.
> + */
>  public class MethodNotFoundException extends ELException {
>
>      @Serial
>      private static final long serialVersionUID = -3631968116081480328L;
>
> +    /**
> +     * Constructs a MethodNotFoundException with no detail message.
> +     */
>      public MethodNotFoundException() {
>          super();
>      }
>
> +    /**
> +     * Constructs a MethodNotFoundException with the specified detail message.
> +     *
> +     * @param message the detail message
> +     */
>      public MethodNotFoundException(String message) {
>          super(message);
>      }
>
> +    /**
> +     * Constructs a MethodNotFoundException with the specified cause.
> +     *
> +     * @param cause the cause of this exception
> +     */
>      public MethodNotFoundException(Throwable cause) {
>          super(cause);
>      }
>
> +    /**
> +     * Constructs a MethodNotFoundException with the specified detail message and cause.
> +     *
> +     * @param message the detail message
> +     * @param cause   the cause of this exception
> +     */
>      public MethodNotFoundException(String message, Throwable cause) {
>          super(message, cause);
>      }
> diff --git a/java/jakarta/el/MethodReference.java b/java/jakarta/el/MethodReference.java
> index 6f86ffcbea..86b008faac 100644
> --- a/java/jakarta/el/MethodReference.java
> +++ b/java/jakarta/el/MethodReference.java
> @@ -26,12 +26,24 @@ import java.util.Arrays;
>   */
>  public class MethodReference {
>
> +    /** The base object on which the method will be invoked. */
>      private final Object base;
> +    /** The method information. */
>      private final MethodInfo methodInfo;
> +    /** The annotations on the method. */
>      private final Annotation[] annotations;
> +    /** The evaluated parameter values for the method invocation. */
>      private final Object[] evaluatedParameters;
>
>
> +    /**
> +     * Constructs a MethodReference with the given base object, method info, annotations, and evaluated parameters.
> +     *
> +     * @param base                 The base object on which the method will be invoked
> +     * @param methodInfo           Information about the method
> +     * @param annotations          The annotations on the method
> +     * @param evaluatedParameters  The evaluated parameter values for the method invocation
> +     */
>      public MethodReference(Object base, MethodInfo methodInfo, Annotation[] annotations, Object[] evaluatedParameters) {
>          this.base = base;
>          this.methodInfo = methodInfo;
> diff --git a/java/jakarta/el/OptionalELResolver.java b/java/jakarta/el/OptionalELResolver.java
> index 9600e1abca..4b59e62d37 100644
> --- a/java/jakarta/el/OptionalELResolver.java
> +++ b/java/jakarta/el/OptionalELResolver.java
> @@ -30,6 +30,12 @@ import java.util.Optional;
>   */
>  public class OptionalELResolver extends ELResolver {
>
> +    /**
> +     * Constructs an OptionalELResolver.
> +     */
> +    public OptionalELResolver() {
> +    }
> +
>      /**
>       * {@inheritDoc}
>       *
> diff --git a/java/jakarta/el/PropertyNotFoundException.java b/java/jakarta/el/PropertyNotFoundException.java
> index 45aff2e48b..7f8aa90598 100644
> --- a/java/jakarta/el/PropertyNotFoundException.java
> +++ b/java/jakarta/el/PropertyNotFoundException.java
> @@ -18,23 +18,50 @@ package jakarta.el;
>
>  import java.io.Serial;
>
> +/**
> + * Exception thrown when a property is not found during EL evaluation.
> + * <p>
> + * This exception is raised when an expression attempts to access a property
> + * that does not exist on the target object.
> + *
> + * @since EL 2.1
> + */
>  public class PropertyNotFoundException extends ELException {
>
>      @Serial
>      private static final long serialVersionUID = -3799200961303506745L;
>
> +    /**
> +     * Constructs a new instance with no detail message or cause.
> +     */
>      public PropertyNotFoundException() {
>          super();
>      }
>
> +    /**
> +     * Constructs a new instance with the specified detail message and no cause.
> +     *
> +     * @param message the detail message
> +     */
>      public PropertyNotFoundException(String message) {
>          super(message);
>      }
>
> +    /**
> +     * Constructs a new instance with the specified cause and no detail message.
> +     *
> +     * @param cause the underlying cause
> +     */
>      public PropertyNotFoundException(Throwable cause) {
>          super(cause);
>      }
>
> +    /**
> +     * Constructs a new instance with the specified detail message and cause.
> +     *
> +     * @param message the detail message
> +     * @param cause   the underlying cause
> +     */
>      public PropertyNotFoundException(String message, Throwable cause) {
>          super(message, cause);
>      }
> diff --git a/java/jakarta/el/PropertyNotWritableException.java b/java/jakarta/el/PropertyNotWritableException.java
> index 58f28e9c34..14b53ba4ca 100644
> --- a/java/jakarta/el/PropertyNotWritableException.java
> +++ b/java/jakarta/el/PropertyNotWritableException.java
> @@ -18,23 +18,50 @@ package jakarta.el;
>
>  import java.io.Serial;
>
> +/**
> + * Exception thrown when an EL expression attempts to write to a read-only property.
> + * <p>
> + * This exception is raised during setValue operations when the target property
> + * exists but cannot be modified.
> + *
> + * @since EL 2.1
> + */
>  public class PropertyNotWritableException extends ELException {
>
>      @Serial
>      private static final long serialVersionUID = 827987155471214717L;
>
> +    /**
> +     * Constructs a new instance with no detail message or cause.
> +     */
>      public PropertyNotWritableException() {
>          super();
>      }
>
> +    /**
> +     * Constructs a new instance with the specified detail message and no cause.
> +     *
> +     * @param message the detail message
> +     */
>      public PropertyNotWritableException(String message) {
>          super(message);
>      }
>
> +    /**
> +     * Constructs a new instance with the specified cause and no detail message.
> +     *
> +     * @param cause the underlying cause
> +     */
>      public PropertyNotWritableException(Throwable cause) {
>          super(cause);
>      }
>
> +    /**
> +     * Constructs a new instance with the specified detail message and cause.
> +     *
> +     * @param message the detail message
> +     * @param cause   the underlying cause
> +     */
>      public PropertyNotWritableException(String message, Throwable cause) {
>          super(message, cause);
>      }
> diff --git a/java/jakarta/el/RecordELResolver.java b/java/jakarta/el/RecordELResolver.java
> index 37c0cc64a3..01b4dc6792 100644
> --- a/java/jakarta/el/RecordELResolver.java
> +++ b/java/jakarta/el/RecordELResolver.java
> @@ -35,6 +35,13 @@ import java.util.Objects;
>   */
>  public class RecordELResolver extends ELResolver {
>
> +    /**
> +     * Constructs a new instance of the resolver.
> +     */
> +    public RecordELResolver() {
> +        super();
> +    }
> +
>      /**
>       * If the base object is an instance of {@link Record}, returns the value of the given field of this {@link Record}.
>       * <p>
> diff --git a/java/jakarta/el/ResourceBundleELResolver.java b/java/jakarta/el/ResourceBundleELResolver.java
> index 62e9fd6729..2ae2ae054e 100644
> --- a/java/jakarta/el/ResourceBundleELResolver.java
> +++ b/java/jakarta/el/ResourceBundleELResolver.java
> @@ -20,8 +20,26 @@ import java.util.MissingResourceException;
>  import java.util.Objects;
>  import java.util.ResourceBundle;
>
> +/**
> + * EL resolver for resource bundle properties.
> + * <p>
> + * This resolver handles base objects of type {@link ResourceBundle}. It accepts
> + * any non-null object as a property, coerces it to a String, and uses it to
> + * look up the corresponding message in the resource bundle. If the key is not
> + * found, the resolver returns a placeholder string of the form {@code ???key???}.
> + * Resource bundles are always read-only.
> + * <p>
> + * {@code ELResolver}s are combined using {@link CompositeELResolver}s to define
> + * rich semantics for evaluating an expression. See the javadocs for
> + * {@link ELResolver} for details.
> + *
> + * @since EL 2.1
> + */
>  public class ResourceBundleELResolver extends ELResolver {
>
> +    /**
> +     * Constructs a new instance of the resolver.
> +     */
>      public ResourceBundleELResolver() {
>          super();
>      }
> diff --git a/java/jakarta/el/StandardELContext.java b/java/jakarta/el/StandardELContext.java
> index 17c5f44b3d..ce2ed86605 100644
> --- a/java/jakarta/el/StandardELContext.java
> +++ b/java/jakarta/el/StandardELContext.java
> @@ -21,6 +21,10 @@ import java.util.HashMap;
>  import java.util.Map;
>
>  /**
> + * Standard implementation of {@link ELContext} that provides a complete EL resolution environment. It maintains a
> + * composite resolver chain, variable mapper, function mapper, and supports custom resolvers and local beans. This is
> + * the default context implementation used by {@link ELProcessor}.
> + *
>   * @since EL 3.0
>   */
>  public class StandardELContext extends ELContext {
> @@ -33,6 +37,14 @@ public class StandardELContext extends ELContext {
>      private final Map<String,Object> localBeans = new HashMap<>();
>
>
> +    /**
> +     * Constructs a new instance backed by the given expression factory.
> +     * <p>
> +     * Initializes the standard resolver chain with built-in resolvers and
> +     * a function mapper populated from the factory's initial function map.
> +     *
> +     * @param factory the expression factory providing the initial resolver and function configuration
> +     */
>      public StandardELContext(ExpressionFactory factory) {
>          wrappedContext = null;
>          variableMapper = new StandardVariableMapper();
> @@ -57,6 +69,14 @@ public class StandardELContext extends ELContext {
>          standardResolver.add(new BeanELResolver());
>      }
>
> +    /**
> +     * Constructs a new instance that wraps the given context.
> +     * <p>
> +     * The variable mapper, function mapper, and EL resolver from the wrapped
> +     * context are used, with additional standard resolvers prepended.
> +     *
> +     * @param context the context to wrap
> +     */
>      public StandardELContext(ELContext context) {
>          wrappedContext = context;
>          variableMapper = context.getVariableMapper();
> @@ -94,6 +114,15 @@ public class StandardELContext extends ELContext {
>          return standardResolver;
>      }
>
> +    /**
> +     * Adds a custom EL resolver to the resolver chain.
> +     * <p>
> +     * Custom resolvers are inserted after the bean name resolver and before
> +     * the standard resolvers, allowing them to intercept resolution before
> +     * the built-in resolvers are consulted.
> +     *
> +     * @param resolver the resolver to add
> +     */
>      public void addELResolver(ELResolver resolver) {
>          customResolvers.add(resolver);
>      }
> diff --git a/java/jakarta/el/StaticFieldELResolver.java b/java/jakarta/el/StaticFieldELResolver.java
> index c69e306005..d77e0c733a 100644
> --- a/java/jakarta/el/StaticFieldELResolver.java
> +++ b/java/jakarta/el/StaticFieldELResolver.java
> @@ -24,10 +24,21 @@ import java.lang.reflect.Modifier;
>  import java.util.Objects;
>
>  /**
> + * ELResolver that resolves static fields and invokes static methods on classes. This resolver handles expressions
> + * where the base is an {@link ELClass} and the property is a {@link String} representing a field or method name.
> + * Static fields are read-only.
> + *
>   * @since EL 3.0
>   */
>  public class StaticFieldELResolver extends ELResolver {
>
> +    /**
> +     * Constructs a new instance of the resolver.
> +     */
> +    public StaticFieldELResolver() {
> +        super();
> +    }
> +
>      @Override
>      public Object getValue(ELContext context, Object base, Object property) {
>          Objects.requireNonNull(context);
> diff --git a/java/jakarta/el/TypeConverter.java b/java/jakarta/el/TypeConverter.java
> index 532543d3da..acc2acf370 100644
> --- a/java/jakarta/el/TypeConverter.java
> +++ b/java/jakarta/el/TypeConverter.java
> @@ -17,10 +17,21 @@
>  package jakarta.el;
>
>  /**
> + * Base class for ELResolvers that perform type conversion. A TypeConverter is an ELResolver that specializes in
> + * converting objects from one type to another via the {@link #convertToType} method. Standard property resolution
> + * methods return {@code null} or no-op, as this resolver is focused solely on type conversion.
> + *
>   * @since EL 3.0
>   */
>  public abstract class TypeConverter extends ELResolver {
>
> +    /**
> +     * Constructs a new instance of the type converter.
> +     */
> +    public TypeConverter() {
> +        super();
> +    }
> +
>      @Override
>      public Object getValue(ELContext context, Object base, Object property) {
>          return null;
> diff --git a/java/jakarta/el/ValueExpression.java b/java/jakarta/el/ValueExpression.java
> index 892c96128c..2db42cdbca 100644
> --- a/java/jakarta/el/ValueExpression.java
> +++ b/java/jakarta/el/ValueExpression.java
> @@ -18,12 +18,29 @@ package jakarta.el;
>
>  import java.io.Serial;
>
> +/**
> + * Represents a parsed EL expression that can be evaluated to produce a value.
> + * <p>
> + * A value expression is created by parsing an EL expression string and can be
> + * evaluated multiple times in different contexts. It supports reading values,
> + * writing values, and introspecting the expression's type and mutability.
> + *
> + * @since EL 2.1
> + */
>  public abstract class ValueExpression extends Expression {
>
>      @Serial
>      private static final long serialVersionUID = 8577809572381654673L;
>
>      /**
> +     * Constructs a new value expression.
> +     */
> +    public ValueExpression() {
> +    }
> +
> +    /**
> +     * Evaluates this expression and returns the result.
> +     *
>       * @param <T>     The expected type for the result of evaluating this value expression
>       * @param context The EL context for this evaluation
>       *
> @@ -37,6 +54,8 @@ public abstract class ValueExpression extends Expression {
>      public abstract <T> T getValue(ELContext context);
>
>      /**
> +     * Sets the value of the property referenced by this expression.
> +     *
>       * @param context The EL context for this evaluation
>       * @param value   The value to set the property to which this value expression refers
>       *
> @@ -49,6 +68,8 @@ public abstract class ValueExpression extends Expression {
>      public abstract void setValue(ELContext context, Object value);
>
>      /**
> +     * Determines whether the property referenced by this expression is read-only.
> +     *
>       * @param context The EL context for this evaluation
>       *
>       * @return <code>true</code> if this expression is read only otherwise <code>false</code>
> @@ -61,6 +82,8 @@ public abstract class ValueExpression extends Expression {
>      public abstract boolean isReadOnly(ELContext context);
>
>      /**
> +     * Returns the type of the result produced by evaluating this expression.
> +     *
>       * @param context The EL context for this evaluation
>       *
>       * @return The type of the result of this value expression
> @@ -72,9 +95,19 @@ public abstract class ValueExpression extends Expression {
>       */
>      public abstract Class<?> getType(ELContext context);
>
> +    /**
> +     * Returns the expected type of the result of this expression.
> +     *
> +     * @return The expected result type, or {@code Object.class} if no specific type is expected
> +     */
>      public abstract Class<?> getExpectedType();
>
>      /**
> +     * Returns a reference to the resolved property for this expression.
> +     * <p>
> +     * This default implementation always returns {@code null}. Subclasses should
> +     * override this method to provide the resolved base object and property.
> +     *
>       * @param context The EL context for this evaluation
>       *
>       * @return This default implementation always returns <code>null</code>
> diff --git a/java/jakarta/el/ValueReference.java b/java/jakarta/el/ValueReference.java
> index b7b2cee9ed..53090d7288 100644
> --- a/java/jakarta/el/ValueReference.java
> +++ b/java/jakarta/el/ValueReference.java
> @@ -20,6 +20,10 @@ import java.io.Serial;
>  import java.io.Serializable;
>
>  /**
> + * Holds a reference to a resolved property, consisting of a base object and a property identifier. This class is
> + * used to capture the result of property resolution during EL evaluation, allowing the caller to perform additional
> + * operations on the resolved property.
> + *
>   * @since EL 2.2
>   */
>  public class ValueReference implements Serializable {
> @@ -27,18 +31,37 @@ public class ValueReference implements Serializable {
>      @Serial
>      private static final long serialVersionUID = 1L;
>
> +    /** The base object on which the property was resolved. */
>      private final Object base;
> +
> +    /** The property identifier. */
>      private final Object property;
>
> +    /**
> +     * Constructs a new value reference with the given base object and property.
> +     *
> +     * @param base     The base object on which the property was resolved
> +     * @param property The property identifier
> +     */
>      public ValueReference(Object base, Object property) {
>          this.base = base;
>          this.property = property;
>      }
>
> +    /**
> +     * Returns the base object on which the property was resolved.
> +     *
> +     * @return The base object
> +     */
>      public Object getBase() {
>          return base;
>      }
>
> +    /**
> +     * Returns the property identifier.
> +     *
> +     * @return The property identifier
> +     */
>      public Object getProperty() {
>          return property;
>      }
> diff --git a/java/jakarta/el/VariableMapper.java b/java/jakarta/el/VariableMapper.java
> index 79018e0f0d..8d41c6b7e5 100644
> --- a/java/jakarta/el/VariableMapper.java
> +++ b/java/jakarta/el/VariableMapper.java
> @@ -17,11 +17,34 @@
>  package jakarta.el;
>
>  /**
> - *
> + * Manages the mapping between variable names and their corresponding {@link ValueExpression} instances within an
> + * {@link ELContext}. Variable mappings allow EL expressions to reference named variables that resolve to computed
> + * values.
>   */
>  public abstract class VariableMapper {
>
> +    /**
> +     * Default constructor for subclasses.
> +     */
> +    public VariableMapper() {
> +    }
> +
> +    /**
> +     * Resolves a variable name to its corresponding ValueExpression.
> +     *
> +     * @param variable the name of the variable to resolve
> +     *
> +     * @return the ValueExpression for the variable, or {@code null} if not found
> +     */
>      public abstract ValueExpression resolveVariable(String variable);
>
> +    /**
> +     * Sets or removes a variable mapping.
> +     *
> +     * @param variable   the name of the variable
> +     * @param expression the ValueExpression to associate with the variable, or {@code null} to remove the mapping
> +     *
> +     * @return the previous ValueExpression for the variable, or {@code null} if there was no mapping
> +     */
>      public abstract ValueExpression setVariable(String variable, ValueExpression expression);
>  }
> diff --git a/java/jakarta/mail/Authenticator.java b/java/jakarta/mail/Authenticator.java
> index 65866750ef..3896516877 100644
> --- a/java/jakarta/mail/Authenticator.java
> +++ b/java/jakarta/mail/Authenticator.java
> @@ -16,7 +16,25 @@
>   */
>  package jakarta.mail;
>
> +/**
> + * Abstract base class for providing user authentication when establishing network connections. Subclasses override
> + * {@link #getPasswordAuthentication} to return the appropriate credentials. This class is part of the Jakarta Mail
> + * API and follows the pattern defined by {@link java.net.Authenticator}.
> + */
>  public class Authenticator {
> +
> +    /**
> +     * Default constructor for subclasses.
> +     */
> +    public Authenticator() {
> +    }
> +
> +    /**
> +     * Returns the password authentication information for the current request. The default implementation returns
> +     * {@code null}. Subclasses should override this method to provide actual credentials.
> +     *
> +     * @return the PasswordAuthentication object, or {@code null} if no authentication is available
> +     */
>      protected PasswordAuthentication getPasswordAuthentication() {
>          return null;
>      }
> diff --git a/java/jakarta/mail/PasswordAuthentication.java b/java/jakarta/mail/PasswordAuthentication.java
> index 7be7b29e85..a76f8b7909 100644
> --- a/java/jakarta/mail/PasswordAuthentication.java
> +++ b/java/jakarta/mail/PasswordAuthentication.java
> @@ -16,8 +16,20 @@
>   */
>  package jakarta.mail;
>
> +/**
> + * Stores username and password credentials for mail authentication. This class follows the pattern defined by
> + * {@link java.net.PasswordAuthentication} and is used with {@link Authenticator} to provide credentials when
> + * establishing mail connections.
> + */
>  @SuppressWarnings("unused") // Dummy implementation
>  public class PasswordAuthentication {
> +
> +    /**
> +     * Constructs a PasswordAuthentication with the given user and password.
> +     *
> +     * @param user     the username
> +     * @param password the password
> +     */
>      public PasswordAuthentication(String user, String password) {
>          // Dummy implementation
>      }
> diff --git a/java/jakarta/mail/Session.java b/java/jakarta/mail/Session.java
> index 87ff869d3b..35f221afff 100644
> --- a/java/jakarta/mail/Session.java
> +++ b/java/jakarta/mail/Session.java
> @@ -18,12 +18,34 @@ package jakarta.mail;
>
>  import java.util.Properties;
>
> +/**
> + * Represents a mail session configuration.
> + */
>  @SuppressWarnings("unused") // Dummy implementation
>  public class Session {
> +    /**
> +     * Default constructor.
> +     */
> +    public Session() {
> +    }
> +
> +    /**
> +     * Returns a Session object with the given properties and authenticator.
> +     *
> +     * @param props the session properties
> +     * @param auth the authenticator
> +     * @return the mail session
> +     */
>      public static Session getInstance(Properties props, Authenticator auth) {
>          return null;
>      }
>
> +    /**
> +     * Returns a Session object with the given properties.
> +     *
> +     * @param props the session properties
> +     * @return the mail session
> +     */
>      public static Session getInstance(Properties props) {
>          return null;
>      }
> diff --git a/java/jakarta/mail/internet/InternetAddress.java b/java/jakarta/mail/internet/InternetAddress.java
> index aa1ce3859e..5d766f5e4d 100644
> --- a/java/jakarta/mail/internet/InternetAddress.java
> +++ b/java/jakarta/mail/internet/InternetAddress.java
> @@ -16,8 +16,19 @@
>   */
>  package jakarta.mail.internet;
>
> +/**
> + * Represents an Internet email address as defined by RFC 822.
> + * An Internet address consists of an optional personal name and
> + * an address string in the form of local-part@domain.
> + */
>  @SuppressWarnings("unused") // Dummy implementation
>  public class InternetAddress {
> +    /**
> +     * Constructs an InternetAddress from the specified address string.
> +     * The address string may optionally include a personal name portion.
> +     *
> +     * @param from the email address string to parse
> +     */
>      public InternetAddress(String from) {
>          // Dummy implementation
>      }
> diff --git a/java/jakarta/mail/internet/MimeMessage.java b/java/jakarta/mail/internet/MimeMessage.java
> index 39644f0509..3fae2b288c 100644
> --- a/java/jakarta/mail/internet/MimeMessage.java
> +++ b/java/jakarta/mail/internet/MimeMessage.java
> @@ -18,16 +18,35 @@ package jakarta.mail.internet;
>
>  import jakarta.mail.Session;
>
> +/**
> + * Represents a MIME message in the Jakarta Mail API.
> + * Provides methods for setting message headers such as sender and subject.
> + */
>  @SuppressWarnings("unused") // Dummy implementation
>  public class MimeMessage implements MimePart {
> +    /**
> +     * Constructs a MimeMessage with the given Session.
> +     *
> +     * @param session the mail session used to create this message
> +     */
>      public MimeMessage(Session session) {
>          // Dummy implementation
>      }
>
> +    /**
> +     * Sets the InternetAddress of the message sender.
> +     *
> +     * @param from the InternetAddress of the sender
> +     */
>      public void setFrom(InternetAddress from) {
>          // Dummy implementation
>      }
>
> +    /**
> +     * Sets the subject of the message.
> +     *
> +     * @param subject the subject string
> +     */
>      public void setSubject(String subject) {
>          // Dummy implementation
>      }
> diff --git a/java/jakarta/mail/internet/MimePart.java b/java/jakarta/mail/internet/MimePart.java
> index 7591634fae..0be69d33e6 100644
> --- a/java/jakarta/mail/internet/MimePart.java
> +++ b/java/jakarta/mail/internet/MimePart.java
> @@ -16,6 +16,10 @@
>   */
>  package jakarta.mail.internet;
>
> +/**
> + * Represents a part of a MIME message in the Jakarta Mail API.
> + * A MimePart can contain content and headers for a single MIME entity.
> + */
>  public interface MimePart {
>      // Dummy implementation
>  }
> diff --git a/java/jakarta/mail/internet/MimePartDataSource.java b/java/jakarta/mail/internet/MimePartDataSource.java
> index a86bae55ea..17b946b53a 100644
> --- a/java/jakarta/mail/internet/MimePartDataSource.java
> +++ b/java/jakarta/mail/internet/MimePartDataSource.java
> @@ -16,8 +16,17 @@
>   */
>  package jakarta.mail.internet;
>
> +/**
> + * Provides a DataSource representation for a MimePart.
> + * Wraps a MimePart so it can be used where a DataSource is required.
> + */
>  @SuppressWarnings("unused") // Dummy implementation
>  public class MimePartDataSource {
> +    /**
> +     * Constructs a MimePartDataSource wrapping the given MimePart.
> +     *
> +     * @param part the MimePart to wrap
> +     */
>      public MimePartDataSource(MimePart part) {
>          // Dummy implementation
>      }
> diff --git a/java/jakarta/persistence/PersistenceContext.java b/java/jakarta/persistence/PersistenceContext.java
> index 78ece9e615..c0963ab44c 100644
> --- a/java/jakarta/persistence/PersistenceContext.java
> +++ b/java/jakarta/persistence/PersistenceContext.java
> @@ -21,17 +21,45 @@ import java.lang.annotation.Retention;
>  import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
> +/**
> + * Specifies the entity manager for use with an entity bean or other managed class.
> + * Used to inject a persistence context into a Jakarta EE managed component.
> + */
>  @Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD })
>  @Retention(RetentionPolicy.RUNTIME)
> -
>  public @interface PersistenceContext {
> +    /**
> +     * The name used to look up the persistence context.
> +     *
> +     * @return the persistence context name
> +     */
>      String name() default "";
>
> +    /**
> +     * The unit name of the persistence unit to associate with the persistence context.
> +     *
> +     * @return the persistence unit name
> +     */
>      String unitName() default "";
>
> +    /**
> +     * The type of the persistence context.
> +     *
> +     * @return the persistence context type
> +     */
>      PersistenceContextType type() default PersistenceContextType.TRANSACTION;
>
> +    /**
> +     * Properties used to configure the persistence context.
> +     *
> +     * @return the configuration properties
> +     */
>      PersistenceProperty[] properties() default {};
>
> +    /**
> +     * The synchronization type of the persistence context with the transaction.
> +     *
> +     * @return the synchronization type
> +     */
>      SynchronizationType synchronization() default SynchronizationType.SYNCHRONIZED;
>  }
> diff --git a/java/jakarta/persistence/PersistenceContextType.java b/java/jakarta/persistence/PersistenceContextType.java
> index 0e54e3c1ad..9f4af89442 100644
> --- a/java/jakarta/persistence/PersistenceContextType.java
> +++ b/java/jakarta/persistence/PersistenceContextType.java
> @@ -16,7 +16,21 @@
>   */
>  package jakarta.persistence;
>
> +/**
> + * Defines the type of persistence context.
> + */
>  public enum PersistenceContextType {
> +    /**
> +     * The default persistence context type.
> +     * The entity manager is tied to the current transaction and is automatically
> +     * closed when the transaction completes.
> +     */
>      TRANSACTION,
> +
> +    /**
> +     * An extended persistence context type.
> +     * The entity manager spans multiple transactions and remains open
> +     * until explicitly closed by the application.
> +     */
>      EXTENDED
> -}
> \ No newline at end of file
> +}
> diff --git a/java/jakarta/persistence/PersistenceContexts.java b/java/jakarta/persistence/PersistenceContexts.java
> index 671d117c7c..ab3f2d49ce 100644
> --- a/java/jakarta/persistence/PersistenceContexts.java
> +++ b/java/jakarta/persistence/PersistenceContexts.java
> @@ -21,9 +21,16 @@ import java.lang.annotation.Retention;
>  import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
> +/**
> + * Groups multiple PersistenceContext annotations for injection into a single component.
> + */
>  @Target(ElementType.TYPE)
>  @Retention(RetentionPolicy.RUNTIME)
> -
>  public @interface PersistenceContexts {
> +    /**
> +     * The array of PersistenceContext annotations.
> +     *
> +     * @return the persistence contexts
> +     */
>      PersistenceContext[] value();
>  }
> diff --git a/java/jakarta/persistence/PersistenceProperty.java b/java/jakarta/persistence/PersistenceProperty.java
> index 3ed05e1982..8c39f8a41b 100644
> --- a/java/jakarta/persistence/PersistenceProperty.java
> +++ b/java/jakarta/persistence/PersistenceProperty.java
> @@ -20,11 +20,24 @@ import java.lang.annotation.Retention;
>  import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
> +/**
> + * Specifies a property for configuring a persistence context or persistence unit.
> + * Used within the properties element of PersistenceContext or PersistenceUnit annotations.
> + */
>  @Target({})
>  @Retention(RetentionPolicy.RUNTIME)
> -
>  public @interface PersistenceProperty {
> +    /**
> +     * The name of the property.
> +     *
> +     * @return the property name
> +     */
>      String name();
>
> +    /**
> +     * The value of the property.
> +     *
> +     * @return the property value
> +     */
>      String value();
>  }
> diff --git a/java/jakarta/persistence/PersistenceUnit.java b/java/jakarta/persistence/PersistenceUnit.java
> index 0580f11112..5d72ed565a 100644
> --- a/java/jakarta/persistence/PersistenceUnit.java
> +++ b/java/jakarta/persistence/PersistenceUnit.java
> @@ -21,11 +21,25 @@ import java.lang.annotation.Retention;
>  import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
> +/**
> + * Specifies a persistence unit for use with an entity bean or other managed class. Used to inject an
> + * EntityManagerFactory into a Jakarta EE managed component.
> + */
>  @Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD })
>  @Retention(RetentionPolicy.RUNTIME)
> -
>  public @interface PersistenceUnit {
> +
> +    /**
> +     * The name used to look up the EntityManagerFactory.
> +     *
> +     * @return the lookup name
> +     */
>      String name() default "";
>
> +    /**
> +     * The unit name of the persistence unit.
> +     *
> +     * @return the persistence unit name
> +     */
>      String unitName() default "";
>  }
> diff --git a/java/jakarta/persistence/PersistenceUnits.java b/java/jakarta/persistence/PersistenceUnits.java
> index 3da4da578e..d1260eb30a 100644
> --- a/java/jakarta/persistence/PersistenceUnits.java
> +++ b/java/jakarta/persistence/PersistenceUnits.java
> @@ -21,9 +21,16 @@ import java.lang.annotation.Retention;
>  import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
> +/**
> + * Groups multiple PersistenceUnit annotations for injection into a single component.
> + */
>  @Target(ElementType.TYPE)
>  @Retention(RetentionPolicy.RUNTIME)
> -
>  public @interface PersistenceUnits {
> +    /**
> +     * The array of PersistenceUnit annotations.
> +     *
> +     * @return the persistence units
> +     */
>      PersistenceUnit[] value();
>  }
> diff --git a/java/jakarta/persistence/SynchronizationType.java b/java/jakarta/persistence/SynchronizationType.java
> index b1d5c1acc5..40ad6bf5ac 100644
> --- a/java/jakarta/persistence/SynchronizationType.java
> +++ b/java/jakarta/persistence/SynchronizationType.java
> @@ -16,7 +16,16 @@
>   */
>  package jakarta.persistence;
>
> +/**
> + * Specifies the synchronization type of an entity manager with JTA transactions.
> + */
>  public enum SynchronizationType {
> +    /**
> +     * The entity manager participates in the current JTA transaction.
> +     */
>      SYNCHRONIZED,
> +    /**
> +     * The entity manager does not participate in the current JTA transaction.
> +     */
>      UNSYNCHRONIZED
>  }
> diff --git a/java/jakarta/security/auth/message/AuthException.java b/java/jakarta/security/auth/message/AuthException.java
> index f5a71e44fc..40cd5a47cd 100644
> --- a/java/jakarta/security/auth/message/AuthException.java
> +++ b/java/jakarta/security/auth/message/AuthException.java
> @@ -20,13 +20,25 @@ import java.io.Serial;
>
>  import javax.security.auth.login.LoginException;
>
> +/**
> + * Exception thrown when a JASPIC authentication operation fails. This exception is used by authentication modules
> + * and contexts to signal errors during the authentication process.
> + */
>  public class AuthException extends LoginException {
>      @Serial
>      private static final long serialVersionUID = -1156951780670243758L;
>
> +    /**
> +     * Constructs an AuthException with no detail message.
> +     */
>      public AuthException() {
>      }
>
> +    /**
> +     * Constructs an AuthException with the specified detail message.
> +     *
> +     * @param msg the detail message
> +     */
>      public AuthException(String msg) {
>          super(msg);
>      }
> diff --git a/java/jakarta/security/auth/message/AuthStatus.java b/java/jakarta/security/auth/message/AuthStatus.java
> index ec009c80b4..c927296493 100644
> --- a/java/jakarta/security/auth/message/AuthStatus.java
> +++ b/java/jakarta/security/auth/message/AuthStatus.java
> @@ -16,12 +16,35 @@
>   */
>  package jakarta.security.auth.message;
>
> +/**
> + * Represents the status returned by JASPIC authentication operations. The authentication status indicates whether
> + * authentication succeeded, failed, or requires further message exchange.
> + */
>  public class AuthStatus {
>
> +    /**
> +     * Authentication succeeded and no further message exchange is required.
> +     */
>      public static final AuthStatus SUCCESS = new AuthStatus("SUCCESS");
> +
> +    /**
> +     * Authentication failed and no further message exchange will change the outcome.
> +     */
>      public static final AuthStatus FAILURE = new AuthStatus("FAILURE");
> +
> +    /**
> +     * Authentication succeeded and the response should be sent to the peer.
> +     */
>      public static final AuthStatus SEND_SUCCESS = new AuthStatus("SEND_SUCCESS");
> +
> +    /**
> +     * Authentication failed and the failure response should be sent to the peer.
> +     */
>      public static final AuthStatus SEND_FAILURE = new AuthStatus("SEND_FAILURE");
> +
> +    /**
> +     * Authentication is in progress and further message exchange is required.
> +     */
>      public static final AuthStatus SEND_CONTINUE = new AuthStatus("SEND_CONTINUE");
>
>      private final String name;
> diff --git a/java/jakarta/security/auth/message/ClientAuth.java b/java/jakarta/security/auth/message/ClientAuth.java
> index 79bda35aff..a4937e06fb 100644
> --- a/java/jakarta/security/auth/message/ClientAuth.java
> +++ b/java/jakarta/security/auth/message/ClientAuth.java
> @@ -18,6 +18,10 @@ package jakarta.security.auth.message;
>
>  import javax.security.auth.Subject;
>
> +/**
> + * Defines the contract for client-side authentication in JASPIC. A ClientAuth implementation authenticates outbound
> + * requests and validates inbound responses in a client-to-server communication pattern.
> + */
>  public interface ClientAuth {
>
>      /**
> diff --git a/java/jakarta/security/auth/message/MessageInfo.java b/java/jakarta/security/auth/message/MessageInfo.java
> index 4fd1e18f21..cb9c760132 100644
> --- a/java/jakarta/security/auth/message/MessageInfo.java
> +++ b/java/jakarta/security/auth/message/MessageInfo.java
> @@ -18,15 +18,53 @@ package jakarta.security.auth.message;
>
>  import java.util.Map;
>
> +/**
> + * Represents the request and response messages associated with a
> + * message-based authentication exchange.  The {@code MessageInfo} object
> + * provides access to the request and response message objects, as well
> + * as a map of additional context information.  The types of the request
> + * and response message objects are protocol-specific.
> + */
>  public interface MessageInfo {
>
> +    /**
> +     * Returns the request message object associated with this
> +     * authentication exchange.  The type of the returned object is
> +     * protocol-specific.
> +     *
> +     * @return the request message object, or {@code null} if not available
> +     */
>      Object getRequestMessage();
>
> +    /**
> +     * Returns the response message object associated with this
> +     * authentication exchange.  The type of the returned object is
> +     * protocol-specific.
> +     *
> +     * @return the response message object, or {@code null} if not available
> +     */
>      Object getResponseMessage();
>
> +    /**
> +     * Sets the request message object for this authentication exchange.
> +     *
> +     * @param request the request message object
> +     */
>      void setRequestMessage(Object request);
>
> +    /**
> +     * Sets the response message object for this authentication exchange.
> +     *
> +     * @param response the response message object
> +     */
>      void setResponseMessage(Object response);
>
> +    /**
> +     * Returns a map of additional context information associated with
> +     * this authentication exchange.  The map may contain protocol-specific
> +     * attributes such as message headers.
> +     *
> +     * @return a {@code Map} of context information, or {@code null} if not available
> +     */
>      Map<String,Object> getMap();
>  }
> diff --git a/java/jakarta/security/auth/message/MessagePolicy.java b/java/jakarta/security/auth/message/MessagePolicy.java
> index 3237ab42d6..7f0f3b2d12 100644
> --- a/java/jakarta/security/auth/message/MessagePolicy.java
> +++ b/java/jakarta/security/auth/message/MessagePolicy.java
> @@ -16,11 +16,28 @@
>   */
>  package jakarta.security.auth.message;
>
> +/**
> + * Defines the security policy requirements for a message-based
> + * authentication module.  A {@code MessagePolicy} specifies the target
> + * policies that determine which messages require authentication and the
> + * level of protection required.
> + */
>  public class MessagePolicy {
>
>      private final TargetPolicy[] targetPolicies;
>      private final boolean mandatory;
>
> +    /**
> +     * Creates a new {@code MessagePolicy} with the specified target
> +     * policies and mandatory flag.
> +     *
> +     * @param targetPolicies the array of {@code TargetPolicy} objects
> +     *        defining the policy requirements; must not be {@code null}
> +     * @param mandatory {@code true} if the policy is mandatory and
> +     *        authentication must succeed; {@code false} if the policy
> +     *        is optional
> +     * @throws IllegalArgumentException if {@code targetPolicies} is {@code null}
> +     */
>      public MessagePolicy(TargetPolicy[] targetPolicies, boolean mandatory) {
>          if (targetPolicies == null) {
>              throw new IllegalArgumentException("targetPolicies is null");
> @@ -29,10 +46,23 @@ public class MessagePolicy {
>          this.mandatory = mandatory;
>      }
>
> +    /**
> +     * Indicates whether this policy is mandatory.  If mandatory, the
> +     * authentication module must enforce the policy and authentication
> +     * will fail if the policy cannot be satisfied.
> +     *
> +     * @return {@code true} if the policy is mandatory, {@code false} otherwise
> +     */
>      public boolean isMandatory() {
>          return mandatory;
>      }
>
> +    /**
> +     * Returns the target policies associated with this message policy.
> +     *
> +     * @return an array of {@code TargetPolicy} objects, or {@code null}
> +     *         if no target policies are defined
> +     */
>      public TargetPolicy[] getTargetPolicies() {
>          if (targetPolicies.length == 0) {
>              return null;
> @@ -40,29 +70,87 @@ public class MessagePolicy {
>          return targetPolicies;
>      }
>
> +    /**
> +     * Defines the level of protection to be applied to a message.
> +     * A protection policy specifies whether the sender, content,
> +     * or recipient of a message must be authenticated.
> +     */
>      public interface ProtectionPolicy {
>
> +        /**
> +         * Identifier for a policy that requires authentication of the sender.
> +         */
>          String AUTHENTICATE_SENDER = "#authenticateSender";
> +
> +        /**
> +         * Identifier for a policy that requires authentication of the message content.
> +         */
>          String AUTHENTICATE_CONTENT = "#authenticateContent";
> +
> +        /**
> +         * Identifier for a policy that requires authentication of the recipient.
> +         */
>          String AUTHENTICATE_RECIPIENT = "#authenticateRecipient";
>
> +        /**
> +         * Returns the unique identifier for this protection policy.
> +         *
> +         * @return the string identifier for this policy
> +         */
>          String getID();
>      }
>
> +    /**
> +     * Defines how to extract target information from a message for
> +     * policy evaluation.  A target determines which messages are
> +     * subject to a particular {@code TargetPolicy}.
> +     */
>      public interface Target {
>
> +        /**
> +         * Retrieves the target value from the given message.
> +         *
> +         * @param messageInfo the message containing the target information
> +         * @return the target value extracted from the message
> +         */
>          Object get(MessageInfo messageInfo);
>
> +        /**
> +         * Removes the target value from the given message.
> +         *
> +         * @param messageInfo the message from which to remove the target
> +         */
>          void remove(MessageInfo messageInfo);
>
> +        /**
> +         * Stores the target value in the given message.
> +         *
> +         * @param messageInfo the message in which to store the target
> +         * @param data the target value to store
> +         */
>          void put(MessageInfo messageInfo, Object data);
>      }
>
> +    /**
> +     * Associates a set of targets with a protection policy.  A
> +     * {@code TargetPolicy} defines the protection requirements for
> +     * messages that match the specified targets.
> +     */
>      public static class TargetPolicy {
>
>          private final Target[] targets;
>          private final ProtectionPolicy protectionPolicy;
>
> +        /**
> +         * Creates a new {@code TargetPolicy} with the specified targets
> +         * and protection policy.
> +         *
> +         * @param targets the array of {@code Target} objects, or {@code null}
> +         *        if not applicable
> +         * @param protectionPolicy the {@code ProtectionPolicy} to apply;
> +         *        must not be {@code null}
> +         * @throws IllegalArgumentException if {@code protectionPolicy} is {@code null}
> +         */
>          public TargetPolicy(Target[] targets, ProtectionPolicy protectionPolicy) {
>              if (protectionPolicy == null) {
>                  throw new IllegalArgumentException("protectionPolicy is null");
> @@ -71,6 +159,12 @@ public class MessagePolicy {
>              this.protectionPolicy = protectionPolicy;
>          }
>
> +        /**
> +         * Returns the targets associated with this target policy.
> +         *
> +         * @return an array of {@code Target} objects, or {@code null}
> +         *         if no targets are defined
> +         */
>          public Target[] getTargets() {
>              if (targets == null || targets.length == 0) {
>                  return null;
> @@ -78,6 +172,11 @@ public class MessagePolicy {
>              return targets;
>          }
>
> +        /**
> +         * Returns the protection policy associated with this target policy.
> +         *
> +         * @return the {@code ProtectionPolicy} for this target policy
> +         */
>          public ProtectionPolicy getProtectionPolicy() {
>              return protectionPolicy;
>          }
> diff --git a/java/jakarta/security/auth/message/ServerAuth.java b/java/jakarta/security/auth/message/ServerAuth.java
> index 8df08f055a..1508051b9d 100644
> --- a/java/jakarta/security/auth/message/ServerAuth.java
> +++ b/java/jakarta/security/auth/message/ServerAuth.java
> @@ -18,6 +18,13 @@ package jakarta.security.auth.message;
>
>  import javax.security.auth.Subject;
>
> +/**
> + * Provides server-side authentication of requests and response signing.
> + * <p>
> + * This interface defines the contract for authenticating incoming requests
> + * and optionally securing outgoing responses in a server-side context.
> + * Implementations are typically obtained through a {@link jakarta.security.auth.message.config.ServerAuthContext}.
> + */
>  public interface ServerAuth {
>
>      /**
> diff --git a/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java b/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java
> index c29fca9002..11aaf37c9e 100644
> --- a/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java
> +++ b/java/jakarta/security/auth/message/callback/CallerPrincipalCallback.java
> @@ -22,8 +22,9 @@ import javax.security.auth.Subject;
>  import javax.security.auth.callback.Callback;
>
>  /**
> - * Callback that enables an authentication module to inform the runtime of the call principal or name of the caller
> - * principal.
> + * Callback that enables an authentication module to inform the runtime of the caller principal or name of the
> + * caller principal. The callback handler populates the given Subject with the authenticated principal, or returns
> + * the principal/name that was provided.
>   */
>  public class CallerPrincipalCallback implements Callback {
>
> @@ -31,26 +32,55 @@ public class CallerPrincipalCallback implements Callback {
>      private final Principal principal;
>      private final String name;
>
> +    /**
> +     * Constructs a callback with a Subject and a Principal. The callback handler will add the principal to the
> +     * subject.
> +     *
> +     * @param subject   the subject to which the principal will be added
> +     * @param principal the principal representing the caller
> +     */
>      public CallerPrincipalCallback(Subject subject, Principal principal) {
>          this.subject = subject;
>          this.principal = principal;
>          this.name = null;
>      }
>
> +    /**
> +     * Constructs a callback with a Subject and a caller name. The callback handler will create a principal from
> +     * the name and add it to the subject.
> +     *
> +     * @param subject the subject to which the principal will be added
> +     * @param name    the name of the caller
> +     */
>      public CallerPrincipalCallback(Subject subject, String name) {
>          this.subject = subject;
>          this.principal = null;
>          this.name = name;
>      }
>
> +    /**
> +     * Returns the Subject associated with this callback.
> +     *
> +     * @return the Subject
> +     */
>      public Subject getSubject() {
>          return subject;
>      }
>
> +    /**
> +     * Returns the Principal associated with this callback, or {@code null} if a name was provided instead.
> +     *
> +     * @return the Principal, or {@code null}
> +     */
>      public Principal getPrincipal() {
>          return principal;
>      }
>
> +    /**
> +     * Returns the name associated with this callback, or {@code null} if a Principal was provided instead.
> +     *
> +     * @return the name, or {@code null}
> +     */
>      public String getName() {
>          return name;
>      }
> diff --git a/java/jakarta/security/auth/message/callback/CertStoreCallback.java b/java/jakarta/security/auth/message/callback/CertStoreCallback.java
> index d8aef96cb2..f30a9dbf95 100644
> --- a/java/jakarta/security/auth/message/callback/CertStoreCallback.java
> +++ b/java/jakarta/security/auth/message/callback/CertStoreCallback.java
> @@ -21,19 +21,33 @@ import java.security.cert.CertStore;
>  import javax.security.auth.callback.Callback;
>
>  /**
> - * Callback that enables a runtime to inform authentication modules of the CertStore to use.
> + * Callback that enables a runtime to inform authentication modules of the {@link CertStore} to use for certificate
> + * validation. The runtime populates the CertStore, and the authentication module retrieves it.
>   */
>  public class CertStoreCallback implements Callback {
>
>      private CertStore certStore;
>
> +    /**
> +     * Constructs an empty CertStoreCallback. The runtime will populate the CertStore via {@link #setCertStore}.
> +     */
>      public CertStoreCallback() {
>      }
>
> +    /**
> +     * Sets the CertStore to be used for certificate validation.
> +     *
> +     * @param certStore the CertStore
> +     */
>      public void setCertStore(CertStore certStore) {
>          this.certStore = certStore;
>      }
>
> +    /**
> +     * Returns the CertStore set by the runtime.
> +     *
> +     * @return the CertStore, or {@code null} if not yet set
> +     */
>      public CertStore getCertStore() {
>          return certStore;
>      }
> diff --git a/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java b/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java
> index f5b2e55ffe..4f053e22f0 100644
> --- a/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java
> +++ b/java/jakarta/security/auth/message/callback/GroupPrincipalCallback.java
> @@ -21,21 +21,40 @@ import javax.security.auth.callback.Callback;
>
>  /**
>   * Callback that enables an authentication module to inform the runtime of the groups a user is in.
> + * The callback handler populates the given Subject with the group principals, or returns the
> + * group names that were provided.
>   */
>  public class GroupPrincipalCallback implements Callback {
>
>      private final Subject subject;
>      private final String[] groups;
>
> +    /**
> +     * Constructs a callback with a Subject and an array of group names. The callback handler
> +     * will create principals for the group names and add them to the subject.
> +     *
> +     * @param subject the subject to which the group principals will be added
> +     * @param groups  the group names associated with the caller
> +     */
>      public GroupPrincipalCallback(Subject subject, String[] groups) {
>          this.subject = subject;
>          this.groups = groups;
>      }
>
> +    /**
> +     * Returns the Subject associated with this callback.
> +     *
> +     * @return the Subject
> +     */
>      public Subject getSubject() {
>          return subject;
>      }
>
> +    /**
> +     * Returns the group names associated with this callback.
> +     *
> +     * @return the group names
> +     */
>      public String[] getGroups() {
>          return groups;
>      }
> diff --git a/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java b/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java
> index ae9f6bdecc..d552255736 100644
> --- a/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java
> +++ b/java/jakarta/security/auth/message/callback/PasswordValidationCallback.java
> @@ -22,8 +22,10 @@ import javax.security.auth.Subject;
>  import javax.security.auth.callback.Callback;
>
>  /**
> - * Callback that enables an authentication module to supply a username and password (to a runtime?) and determine if the
> - * result of validation.
> + * A callback that enables an authentication module to supply a username
> + * and password to the runtime and obtain the result of password validation.
> + * The runtime validates the credentials and updates the {@code Subject}
> + * if authentication succeeds.
>   */
>  public class PasswordValidationCallback implements Callback {
>
> @@ -32,33 +34,76 @@ public class PasswordValidationCallback implements Callback {
>      private char[] password;
>      private boolean result;
>
> +    /**
> +     * Creates a new {@code PasswordValidationCallback} with the specified
> +     * subject, username, and password.
> +     *
> +     * @param subject the {@code Subject} to be populated upon successful
> +     *        authentication
> +     * @param username the username to validate
> +     * @param password the password to validate
> +     */
>      public PasswordValidationCallback(Subject subject, String username, char[] password) {
>          this.subject = subject;
>          this.username = username;
>          this.password = password;
>      }
>
> +    /**
> +     * Returns the {@code Subject} associated with this callback.  The
> +     * runtime populates this subject with authentication information
> +     * upon successful validation.
> +     *
> +     * @return the {@code Subject} for this callback
> +     */
>      public Subject getSubject() {
>          return subject;
>      }
>
> +    /**
> +     * Returns the username to be validated.
> +     *
> +     * @return the username
> +     */
>      public String getUsername() {
>          return username;
>      }
>
> +    /**
> +     * Returns the password to be validated.
> +     *
> +     * @return the password character array
> +     */
>      public char[] getPassword() {
>          return password;
>      }
>
> +    /**
> +     * Clears the password from memory for security purposes.  After
> +     * calling this method, {@link #getPassword()} will return an empty
> +     * character array.
> +     */
>      public void clearPassword() {
>          Arrays.fill(password, (char) 0);
>          password = new char[0];
>      }
>
> +    /**
> +     * Sets the result of the password validation performed by the runtime.
> +     *
> +     * @param result {@code true} if the password validation succeeded,
> +     *        {@code false} otherwise
> +     */
>      public void setResult(boolean result) {
>          this.result = result;
>      }
>
> +    /**
> +     * Returns the result of the password validation.
> +     *
> +     * @return {@code true} if the password was validated successfully,
> +     *         {@code false} otherwise
> +     */
>      public boolean getResult() {
>          return result;
>      }
> diff --git a/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java b/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java
> index 853ca02600..c3aab997d6 100644
> --- a/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java
> +++ b/java/jakarta/security/auth/message/callback/PrivateKeyCallback.java
> @@ -24,9 +24,11 @@ import javax.security.auth.callback.Callback;
>  import javax.security.auth.x500.X500Principal;
>
>  /**
> - * Callback that enables an authentication module to request a certificate chain and private key from the runtime. The
> - * information specifying the chain and key may be an alias, a digest, a subject key, or an issuer ID. Other request
> - * types may be supported.
> + * A callback that enables an authentication module to request a
> + * certificate chain and private key from the runtime.  The request
> + * identifies the desired key material using one of several {@link Request}
> + * subtypes, such as keystore alias, certificate digest, subject key
> + * identifier, or issuer and serial number.
>   */
>  public class PrivateKeyCallback implements Callback {
>
> @@ -34,87 +36,192 @@ public class PrivateKeyCallback implements Callback {
>      private Certificate[] chain;
>      private PrivateKey key;
>
> +    /**
> +     * Creates a new {@code PrivateKeyCallback} with the specified request.
> +     *
> +     * @param request the {@code Request} object identifying the desired
> +     *        certificate chain and private key
> +     */
>      public PrivateKeyCallback(Request request) {
>          this.request = request;
>      }
>
> +    /**
> +     * Returns the request associated with this callback.
> +     *
> +     * @return the {@code Request} object
> +     */
>      public Request getRequest() {
>          return request;
>      }
>
> +    /**
> +     * Sets the private key and certificate chain resolved by the runtime
> +     * in response to the request.
> +     *
> +     * @param key the resolved {@code PrivateKey}
> +     * @param chain the corresponding certificate chain
> +     */
>      public void setKey(PrivateKey key, Certificate[] chain) {
>          this.key = key;
>          this.chain = chain;
>      }
>
> +    /**
> +     * Returns the private key resolved by the runtime.
> +     *
> +     * @return the {@code PrivateKey}, or {@code null} if not yet resolved
> +     */
>      public PrivateKey getKey() {
>          return key;
>      }
>
> +    /**
> +     * Returns the certificate chain resolved by the runtime.
> +     *
> +     * @return the certificate chain, or {@code null} if not yet resolved
> +     */
>      public Certificate[] getChain() {
>          return chain;
>      }
>
> +    /**
> +     * Base interface for private key requests.  Implementations specify
> +     * the criteria by which the runtime should locate the desired
> +     * certificate chain and private key.
> +     */
>      public interface Request {
>      }
>
> +    /**
> +     * A request to retrieve a certificate chain and private key by
> +     * keystore alias.
> +     */
>      public static class AliasRequest implements Request {
>
>          private final String alias;
>
> +        /**
> +         * Creates a new {@code AliasRequest} with the specified keystore alias.
> +         *
> +         * @param alias the keystore alias identifying the desired key entry
> +         */
>          public AliasRequest(String alias) {
>              this.alias = alias;
>          }
>
> +        /**
> +         * Returns the keystore alias for this request.
> +         *
> +         * @return the keystore alias
> +         */
>          public String getAlias() {
>              return alias;
>          }
>      }
>
> +    /**
> +     * A request to retrieve a certificate chain and private key by
> +     * certificate digest value.
> +     */
>      public static class DigestRequest implements Request {
>          private final byte[] digest;
>          private final String algorithm;
>
> +        /**
> +         * Creates a new {@code DigestRequest} with the specified digest
> +         * value and digest algorithm.
> +         *
> +         * @param digest the digest value of the desired certificate
> +         * @param algorithm the digest algorithm used to produce the digest
> +         */
>          public DigestRequest(byte[] digest, String algorithm) {
>              this.digest = digest;
>              this.algorithm = algorithm;
>          }
>
> +        /**
> +         * Returns the digest value for this request.
> +         *
> +         * @return the digest byte array
> +         */
>          public byte[] getDigest() {
>              return digest;
>          }
>
> +        /**
> +         * Returns the digest algorithm used for this request.
> +         *
> +         * @return the algorithm name
> +         */
>          public String getAlgorithm() {
>              return algorithm;
>          }
>      }
>
> +    /**
> +     * A request to retrieve a certificate chain and private key by
> +     * the Subject Key Identifier extension value.
> +     */
>      public static class SubjectKeyIDRequest implements Request {
>
>          private final byte[] subjectKeyID;
>
> +        /**
> +         * Creates a new {@code SubjectKeyIDRequest} with the specified
> +         * subject key identifier.
> +         *
> +         * @param subjectKeyID the Subject Key Identifier extension value
> +         *        from the desired certificate
> +         */
>          public SubjectKeyIDRequest(byte[] subjectKeyID) {
>              this.subjectKeyID = subjectKeyID;
>          }
>
> +        /**
> +         * Returns the subject key identifier for this request.
> +         *
> +         * @return the Subject Key Identifier byte array
> +         */
>          public byte[] getSubjectKeyID() {
>              return subjectKeyID;
>          }
>      }
>
> +    /**
> +     * A request to retrieve a certificate chain and private key by
> +     * the issuer distinguished name and certificate serial number.
> +     */
>      public static class IssuerSerialNumRequest implements Request {
>          private final X500Principal issuer;
>          private final BigInteger serialNum;
>
> +        /**
> +         * Creates a new {@code IssuerSerialNumRequest} with the specified
> +         * issuer and serial number.
> +         *
> +         * @param issuer the issuer distinguished name of the desired certificate
> +         * @param serialNum the serial number of the desired certificate
> +         */
>          public IssuerSerialNumRequest(X500Principal issuer, BigInteger serialNum) {
>              this.issuer = issuer;
>              this.serialNum = serialNum;
>          }
>
> +        /**
> +         * Returns the issuer distinguished name for this request.
> +         *
> +         * @return the {@code X500Principal} representing the issuer
> +         */
>          public X500Principal getIssuer() {
>              return issuer;
>          }
>
> +        /**
> +         * Returns the certificate serial number for this request.
> +         *
> +         * @return the serial number as a {@code BigInteger}
> +         */
>          public BigInteger getSerialNum() {
>              return serialNum;
>          }
> diff --git a/java/jakarta/security/auth/message/callback/SecretKeyCallback.java b/java/jakarta/security/auth/message/callback/SecretKeyCallback.java
> index b3a02ad938..7cf47cdec8 100644
> --- a/java/jakarta/security/auth/message/callback/SecretKeyCallback.java
> +++ b/java/jakarta/security/auth/message/callback/SecretKeyCallback.java
> @@ -28,33 +28,70 @@ public class SecretKeyCallback implements Callback {
>      private final Request request;
>      private SecretKey key;
>
> +    /**
> +     * Constructs a SecretKeyCallback with the specified request.
> +     *
> +     * @param request The request describing the secret key to obtain
> +     */
>      public SecretKeyCallback(Request request) {
>          this.request = request;
>      }
>
> +    /**
> +     * Returns the request associated with this callback.
> +     *
> +     * @return The request describing the secret key to obtain
> +     */
>      public Request getRequest() {
>          return request;
>      }
>
> +    /**
> +     * Sets the secret key obtained by the runtime.
> +     *
> +     * @param key The secret key
> +     */
>      public void setKey(SecretKey key) {
>          this.key = key;
>      }
>
> +    /**
> +     * Returns the secret key.
> +     *
> +     * @return The secret key, or {@code null} if not set
> +     */
>      public SecretKey getKey() {
>          return key;
>      }
>
> +    /**
> +     * Represents a request for a secret key.
> +     * Implementations specify the criteria for locating the desired key.
> +     */
>      public interface Request {
>      }
>
> +    /**
> +     * A request for a secret key identified by its alias.
> +     */
>      public static class AliasRequest implements Request {
>
>          private final String alias;
>
> +        /**
> +         * Constructs an AliasRequest with the specified alias.
> +         *
> +         * @param alias The alias of the secret key to obtain
> +         */
>          public AliasRequest(String alias) {
>              this.alias = alias;
>          }
>
> +        /**
> +         * Returns the alias of the requested secret key.
> +         *
> +         * @return The alias string
> +         */
>          public String getAlias() {
>              return alias;
>          }
> diff --git a/java/jakarta/security/auth/message/callback/TrustStoreCallback.java b/java/jakarta/security/auth/message/callback/TrustStoreCallback.java
> index 9bafa9a26b..a6a367ba19 100644
> --- a/java/jakarta/security/auth/message/callback/TrustStoreCallback.java
> +++ b/java/jakarta/security/auth/message/callback/TrustStoreCallback.java
> @@ -27,10 +27,26 @@ public class TrustStoreCallback implements Callback {
>
>      private KeyStore trustStore;
>
> +    /**
> +     * Constructs a new TrustStoreCallback.
> +     */
> +    public TrustStoreCallback() {
> +    }
> +
> +    /**
> +     * Sets the trust store to be used for certificate validation.
> +     *
> +     * @param trustStore The trust store containing trusted certificates
> +     */
>      public void setTrustStore(KeyStore trustStore) {
>          this.trustStore = trustStore;
>      }
>
> +    /**
> +     * Returns the trust store.
> +     *
> +     * @return The trust store, or {@code null} if not set
> +     */
>      public KeyStore getTrustStore() {
>          return trustStore;
>      }
> diff --git a/java/jakarta/security/auth/message/config/AuthConfig.java b/java/jakarta/security/auth/message/config/AuthConfig.java
> index 099cccee8d..7e3e5e0572 100644
> --- a/java/jakarta/security/auth/message/config/AuthConfig.java
> +++ b/java/jakarta/security/auth/message/config/AuthConfig.java
> @@ -18,15 +18,46 @@ package jakarta.security.auth.message.config;
>
>  import jakarta.security.auth.message.MessageInfo;
>
> +/**
> + * Provides configuration information for a JASPIC authentication mechanism. An AuthConfig defines the message layer,
> + * application context, and authentication context ID for a given message, and indicates whether the mechanism is
> + * protected.
> + */
>  public interface AuthConfig {
>
> +    /**
> +     * Returns the message layer for which this configuration applies.
> +     *
> +     * @return the message layer
> +     */
>      String getMessageLayer();
>
> +    /**
> +     * Returns the application context for which this configuration applies.
> +     *
> +     * @return the application context
> +     */
>      String getAppContext();
>
> +    /**
> +     * Determines the authentication context ID for the given message.
> +     *
> +     * @param messageInfo the message information used to determine the context ID
> +     *
> +     * @return the authentication context ID, or {@code null} if no context applies
> +     */
>      String getAuthContextID(MessageInfo messageInfo);
>
> +    /**
> +     * Refreshes the configuration, reloading any changed settings.
> +     */
>      void refresh();
>
> +    /**
> +     * Indicates whether the authentication mechanism is protected, meaning that the configuration data is stored
> +     * securely.
> +     *
> +     * @return {@code true} if the mechanism is protected, {@code false} otherwise
> +     */
>      boolean isProtected();
>  }
> diff --git a/java/jakarta/security/auth/message/config/AuthConfigFactory.java b/java/jakarta/security/auth/message/config/AuthConfigFactory.java
> index e8f4938ad6..7d56046cf3 100644
> --- a/java/jakarta/security/auth/message/config/AuthConfigFactory.java
> +++ b/java/jakarta/security/auth/message/config/AuthConfigFactory.java
> @@ -21,8 +21,17 @@ import java.util.Map;
>
>  import jakarta.security.auth.message.module.ServerAuthModule;
>
> +/**
> + * Factory for obtaining and managing {@link AuthConfigProvider} instances. The AuthConfigFactory is responsible for
> + * discovering, registering, and providing configuration providers for JASPIC authentication modules. Use
> + * {@link #getFactory()} to obtain the singleton instance.
> + */
>  public abstract class AuthConfigFactory {
>
> +    /**
> +     * The name of the {@link java.security.Security} property used to specify the AuthConfigFactory implementation
> +     * class.
> +     */
>      public static final String DEFAULT_FACTORY_SECURITY_PROPERTY = "authconfigprovider.factory";
>
>      private static final String DEFAULT_JASPI_AUTHCONFIGFACTORYIMPL =
> @@ -30,9 +39,19 @@ public abstract class AuthConfigFactory {
>
>      private static volatile AuthConfigFactory factory;
>
> +    /**
> +     * Protected constructor for subclasses.
> +     */
>      public AuthConfigFactory() {
>      }
>
> +    /**
> +     * Returns the singleton AuthConfigFactory instance. If no instance has been set via {@link #setFactory}, the
> +     * factory class is discovered from the {@link java.security.Security} property
> +     * {@value #DEFAULT_FACTORY_SECURITY_PROPERTY}, or falls back to a default implementation.
> +     *
> +     * @return the AuthConfigFactory instance
> +     */
>      public static AuthConfigFactory getFactory() {
>          if (factory != null) {
>              return factory;
> @@ -61,27 +80,97 @@ public abstract class AuthConfigFactory {
>          return factory;
>      }
>
> +    /**
> +     * Programmatically sets the AuthConfigFactory instance. This method is typically used by containers to provide
> +     * their own implementation.
> +     *
> +     * @param factory the AuthConfigFactory instance to set
> +     */
>      public static synchronized void setFactory(AuthConfigFactory factory) {
>          AuthConfigFactory.factory = factory;
>      }
>
> +    /**
> +     * Returns the {@link AuthConfigProvider} for the specified message layer and application context.
> +     *
> +     * @param layer      the message layer
> +     * @param appContext the application context
> +     * @param listener   the registration listener to attach
> +     *
> +     * @return the AuthConfigProvider, or {@code null} if none is available
> +     */
>      public abstract AuthConfigProvider getConfigProvider(String layer, String appContext,
>              RegistrationListener listener);
>
> +    /**
> +     * Registers an AuthConfigProvider by class name with the given properties.
> +     *
> +     * @param className  the fully qualified class name of the AuthConfigProvider
> +     * @param properties the configuration properties
> +     * @param layer      the message layer
> +     * @param appContext the application context
> +     * @param description a description of the registration
> +     *
> +     * @return a unique registration ID
> +     */
>      public abstract String registerConfigProvider(String className, Map<String,String> properties, String layer,
>              String appContext, String description);
>
> +    /**
> +     * Registers an AuthConfigProvider instance.
> +     *
> +     * @param provider   the AuthConfigProvider to register
> +     * @param layer      the message layer
> +     * @param appContext the application context
> +     * @param description a description of the registration
> +     *
> +     * @return a unique registration ID
> +     */
>      public abstract String registerConfigProvider(AuthConfigProvider provider, String layer, String appContext,
>              String description);
>
> +    /**
> +     * Removes a registration by its ID.
> +     *
> +     * @param registrationID the registration ID to remove
> +     *
> +     * @return {@code true} if the registration was removed, {@code false} if it did not exist
> +     */
>      public abstract boolean removeRegistration(String registrationID);
>
> +    /**
> +     * Detaches a listener from all registrations matching the given layer and application context, returning the
> +     * affected registration IDs.
> +     *
> +     * @param listener   the listener to detach
> +     * @param layer      the message layer
> +     * @param appContext the application context
> +     *
> +     * @return an array of registration IDs from which the listener was detached
> +     */
>      public abstract String[] detachListener(RegistrationListener listener, String layer, String appContext);
>
> +    /**
> +     * Returns the registration IDs associated with the given AuthConfigProvider.
> +     *
> +     * @param provider the AuthConfigProvider
> +     *
> +     * @return an array of registration IDs
> +     */
>      public abstract String[] getRegistrationIDs(AuthConfigProvider provider);
>
> +    /**
> +     * Returns the {@link RegistrationContext} for the given registration ID.
> +     *
> +     * @param registrationID the registration ID
> +     *
> +     * @return the RegistrationContext, or {@code null} if the ID is not found
> +     */
>      public abstract RegistrationContext getRegistrationContext(String registrationID);
>
> +    /**
> +     * Refreshes all registered AuthConfigProviders, causing them to reload their configuration.
> +     */
>      public abstract void refresh();
>
>      /**
> @@ -118,14 +207,37 @@ public abstract class AuthConfigFactory {
>          return DEFAULT_JASPI_AUTHCONFIGFACTORYIMPL;
>      }
>
> +    /**
> +     * Provides information about a registered {@link AuthConfigProvider}.
> +     */
>      public interface RegistrationContext {
>
> +        /**
> +         * Returns the message layer for this registration.
> +         *
> +         * @return the message layer
> +         */
>          String getMessageLayer();
>
> +        /**
> +         * Returns the application context for this registration.
> +         *
> +         * @return the application context
> +         */
>          String getAppContext();
>
> +        /**
> +         * Returns the description of this registration.
> +         *
> +         * @return the description
> +         */
>          String getDescription();
>
> +        /**
> +         * Indicates whether this registration persists beyond the current container lifecycle.
> +         *
> +         * @return {@code true} if the registration is persistent, {@code false} otherwise
> +         */
>          boolean isPersistent();
>      }
>  }
> diff --git a/java/jakarta/security/auth/message/config/AuthConfigProvider.java b/java/jakarta/security/auth/message/config/AuthConfigProvider.java
> index 66410a7e13..9f42dafd06 100644
> --- a/java/jakarta/security/auth/message/config/AuthConfigProvider.java
> +++ b/java/jakarta/security/auth/message/config/AuthConfigProvider.java
> @@ -20,11 +20,41 @@ import javax.security.auth.callback.CallbackHandler;
>
>  import jakarta.security.auth.message.AuthException;
>
> +/**
> + * Provides {@link ClientAuthConfig} and {@link ServerAuthConfig} instances to JASPIC authentication modules. An
> + * AuthConfigProvider is responsible for loading authentication configuration from a source (e.g., a configuration
> + * file, database, or service) and making it available to the authentication modules.
> + */
>  public interface AuthConfigProvider {
>
> +    /**
> +     * Returns the client-side authentication configuration for the specified layer and application context.
> +     *
> +     * @param layer      the message layer
> +     * @param appContext the application context
> +     * @param handler    the callback handler for obtaining sensitive configuration data
> +     *
> +     * @return the ClientAuthConfig, or {@code null} if no configuration is available
> +     *
> +     * @throws AuthException if an error occurs while retrieving the configuration
> +     */
>      ClientAuthConfig getClientAuthConfig(String layer, String appContext, CallbackHandler handler) throws AuthException;
>
> +    /**
> +     * Returns the server-side authentication configuration for the specified layer and application context.
> +     *
> +     * @param layer      the message layer
> +     * @param appContext the application context
> +     * @param handler    the callback handler for obtaining sensitive configuration data
> +     *
> +     * @return the ServerAuthConfig, or {@code null} if no configuration is available
> +     *
> +     * @throws AuthException if an error occurs while retrieving the configuration
> +     */
>      ServerAuthConfig getServerAuthConfig(String layer, String appContext, CallbackHandler handler) throws AuthException;
>
> +    /**
> +     * Refreshes the configuration, reloading any changed settings from the underlying source.
> +     */
>      void refresh();
>  }
> diff --git a/java/jakarta/security/auth/message/config/ClientAuthConfig.java b/java/jakarta/security/auth/message/config/ClientAuthConfig.java
> index f332f0fea6..8c588bda46 100644
> --- a/java/jakarta/security/auth/message/config/ClientAuthConfig.java
> +++ b/java/jakarta/security/auth/message/config/ClientAuthConfig.java
> @@ -22,8 +22,23 @@ import javax.security.auth.Subject;
>
>  import jakarta.security.auth.message.AuthException;
>
> +/**
> + * Client-side authentication configuration obtained from an {@link AuthConfigProvider}. A ClientAuthConfig provides
> + * the configuration needed to create a {@link ClientAuthContext} for authenticating outbound requests.
> + */
>  public interface ClientAuthConfig extends AuthConfig {
>
> +    /**
> +     * Creates a {@link ClientAuthContext} for the specified authentication context ID.
> +     *
> +     * @param authContextID the authentication context ID
> +     * @param clientSubject the subject representing the client, to be populated upon successful authentication
> +     * @param properties    additional configuration properties
> +     *
> +     * @return the ClientAuthContext, or {@code null} if the authContextID is not recognized
> +     *
> +     * @throws AuthException if an error occurs while creating the context
> +     */
>      ClientAuthContext getAuthContext(String authContextID, Subject clientSubject, Map<String,Object> properties)
>              throws AuthException;
>  }
> diff --git a/java/jakarta/security/auth/message/config/ClientAuthContext.java b/java/jakarta/security/auth/message/config/ClientAuthContext.java
> index 53280c7822..1c7f95c53b 100644
> --- a/java/jakarta/security/auth/message/config/ClientAuthContext.java
> +++ b/java/jakarta/security/auth/message/config/ClientAuthContext.java
> @@ -18,5 +18,10 @@ package jakarta.security.auth.message.config;
>
>  import jakarta.security.auth.message.ClientAuth;
>
> +/**
> + * Runtime context for client-side JASPIC authentication. A ClientAuthContext is created by a
> + * {@link ClientAuthConfig} and performs the actual authentication of outbound requests and validation of inbound
> + * responses.
> + */
>  public interface ClientAuthContext extends ClientAuth {
>  }
> diff --git a/java/jakarta/security/auth/message/config/RegistrationListener.java b/java/jakarta/security/auth/message/config/RegistrationListener.java
> index 05bec1c163..9c3053660b 100644
> --- a/java/jakarta/security/auth/message/config/RegistrationListener.java
> +++ b/java/jakarta/security/auth/message/config/RegistrationListener.java
> @@ -16,7 +16,16 @@
>   */
>  package jakarta.security.auth.message.config;
>
> +/**
> + * Listener interface for JASPIC registration events.
> + */
>  public interface RegistrationListener {
>
> +    /**
> +     * Notifies the listener of a registration event.
> +     *
> +     * @param layer the authentication layer
> +     * @param appContext the application context
> +     */
>      void notify(String layer, String appContext);
>  }
> diff --git a/java/jakarta/security/auth/message/config/ServerAuthConfig.java b/java/jakarta/security/auth/message/config/ServerAuthConfig.java
> index a8bc9c728c..f970ea5466 100644
> --- a/java/jakarta/security/auth/message/config/ServerAuthConfig.java
> +++ b/java/jakarta/security/auth/message/config/ServerAuthConfig.java
> @@ -22,8 +22,20 @@ import javax.security.auth.Subject;
>
>  import jakarta.security.auth.message.AuthException;
>
> +/**
> + * Server-side authentication configuration obtained from an {@link AuthConfigProvider}.
> + */
>  public interface ServerAuthConfig extends AuthConfig {
>
> +    /**
> +     * Returns the {@link ServerAuthContext} for the given authentication context ID.
> +     *
> +     * @param authContextID the authentication context identifier
> +     * @param serviceSubject the service subject
> +     * @param properties the configuration properties
> +     * @return the server authentication context
> +     * @throws AuthException if an error occurs during authentication context creation
> +     */
>      ServerAuthContext getAuthContext(String authContextID, Subject serviceSubject, Map<String,Object> properties)
>              throws AuthException;
>  }
> diff --git a/java/jakarta/security/auth/message/config/ServerAuthContext.java b/java/jakarta/security/auth/message/config/ServerAuthContext.java
> index bbff396988..4c668f7ba5 100644
> --- a/java/jakarta/security/auth/message/config/ServerAuthContext.java
> +++ b/java/jakarta/security/auth/message/config/ServerAuthContext.java
> @@ -18,5 +18,12 @@ package jakarta.security.auth.message.config;
>
>  import jakarta.security.auth.message.ServerAuth;
>
> +/**
> + * Provides server-side authentication of requests and response signing.
> + * <p>
> + * This interface extends {@link ServerAuth} and is obtained from a
> + * {@link ServerAuthConfig}. It is used by the container to authenticate
> + * incoming requests and secure outgoing responses.
> + */
>  public interface ServerAuthContext extends ServerAuth {
>  }
> diff --git a/java/jakarta/security/auth/message/module/ClientAuthModule.java b/java/jakarta/security/auth/message/module/ClientAuthModule.java
> index b0569a462c..ef0d8be7a4 100644
> --- a/java/jakarta/security/auth/message/module/ClientAuthModule.java
> +++ b/java/jakarta/security/auth/message/module/ClientAuthModule.java
> @@ -24,10 +24,31 @@ import jakarta.security.auth.message.AuthException;
>  import jakarta.security.auth.message.ClientAuth;
>  import jakarta.security.auth.message.MessagePolicy;
>
> +/**
> + * A pluggable client-side authentication module in JASPIC. A ClientAuthModule implements the authentication logic
> + * for client-side operations and is initialized with message policies, a callback handler, and configuration
> + * options.
> + */
>  public interface ClientAuthModule extends ClientAuth {
>
> +    /**
> +     * Initializes the authentication module with the given policies, callback handler, and options. This method is
> +     * called once when the module is created.
> +     *
> +     * @param requestPolicy  the message policy for requests
> +     * @param responsePolicy the message policy for responses
> +     * @param handler        the callback handler for obtaining sensitive data
> +     * @param options        configuration options for the module
> +     *
> +     * @throws AuthException if initialization fails
> +     */
>      void initialize(MessagePolicy requestPolicy, MessagePolicy responsePolicy, CallbackHandler handler,
>              Map<String,Object> options) throws AuthException;
>
> +    /**
> +     * Returns the array of MessageInfo implementation classes supported by this module.
> +     *
> +     * @return an array of supported MessageInfo classes
> +     */
>      Class<?>[] getSupportedMessageTypes();
>  }
> diff --git a/java/jakarta/security/auth/message/module/ServerAuthModule.java b/java/jakarta/security/auth/message/module/ServerAuthModule.java
> index 3518bea61d..66e7297fbb 100644
> --- a/java/jakarta/security/auth/message/module/ServerAuthModule.java
> +++ b/java/jakarta/security/auth/message/module/ServerAuthModule.java
> @@ -24,10 +24,35 @@ import jakarta.security.auth.message.AuthException;
>  import jakarta.security.auth.message.MessagePolicy;
>  import jakarta.security.auth.message.ServerAuth;
>
> +/**
> + * Provides server-side authentication of requests and response signing.
> + * <p>
> + * This interface extends {@link ServerAuth} and is implemented by authentication
> + * module providers. It is initialized by the container and provides the actual
> + * authentication logic for server-side message authentication.
> + */
>  public interface ServerAuthModule extends ServerAuth {
>
> +    /**
> +     * Initialize the authentication module.
> +     * <p>
> +     * This method is called by the container to initialize the module with the
> +     * request and response policies, a callback handler, and a set of options.
> +     *
> +     * @param requestPolicy  The policy for the request message
> +     * @param responsePolicy The policy for the response message
> +     * @param handler        The callback handler used to obtain credentials
> +     * @param options        The options provided to the module
> +     *
> +     * @throws AuthException If an error occurs during initialization
> +     */
>      void initialize(MessagePolicy requestPolicy, MessagePolicy responsePolicy, CallbackHandler handler,
>              Map<String,Object> options) throws AuthException;
>
> +    /**
> +     * Returns the array of message types supported by the module.
> +     *
> +     * @return The array of supported message type classes
> +     */
>      Class<?>[] getSupportedMessageTypes();
>  }
> diff --git a/java/jakarta/servlet/AsyncContext.java b/java/jakarta/servlet/AsyncContext.java
> index 7b952e6394..5ba0e7eb53 100644
> --- a/java/jakarta/servlet/AsyncContext.java
> +++ b/java/jakarta/servlet/AsyncContext.java
> @@ -54,21 +54,32 @@ public interface AsyncContext {
>      String ASYNC_QUERY_STRING = "jakarta.servlet.async.query_string";
>
>      /**
> -     * @return a reference to the ServletRequest object
> +     * Returns the {@link ServletRequest} associated with this asynchronous operation.
> +     *
> +     * @return the ServletRequest object
>       */
>      ServletRequest getRequest();
>
>      /**
> -     * @return a reference to the ServletResponse object
> +     * Returns the {@link ServletResponse} associated with this asynchronous operation.
> +     *
> +     * @return the ServletResponse object
>       */
>      ServletResponse getResponse();
>
>      /**
> -     * @return true if the Request and Response are the original ones
> +     * Determines whether the request and response objects are the original ones passed to
> +     * {@link jakarta.servlet.http.HttpServletRequest#startAsync()}, or if they are new objects created by the
> +     * container.
> +     *
> +     * @return {@code true} if the request and response are the original objects, {@code false} otherwise
>       */
>      boolean hasOriginalRequestAndResponse();
>
>      /**
> +     * Dispatches the request to the resource at the original request URI, as specified in the original request. After
> +     * the dispatch, the async request processing is complete and the response is committed.
> +     *
>       * @throws IllegalStateException if this method is called when the request is not in asynchronous mode. The request
>       *                                   is in asynchronous mode after
>       *                                   {@link jakarta.servlet.http.HttpServletRequest#startAsync()} or
> @@ -79,8 +90,12 @@ public interface AsyncContext {
>      void dispatch();
>
>      /**
> -     * @param path The path to which the request/response should be dispatched relative to the {@link ServletContext}
> -     *                 from which this async request was started.
> +     * Dispatches the request to the resource at the specified path relative to the {@link ServletContext} from which
> +     * this async request was started. After the dispatch, the async request processing is complete and the response
> +     * is committed.
> +     *
> +     * @param path the path to which the request/response should be dispatched relative to the {@link ServletContext}
> +     *                 from which this async request was started
>       *
>       * @throws IllegalStateException if this method is called when the request is not in asynchronous mode. The request
>       *                                   is in asynchronous mode after
> @@ -92,9 +107,12 @@ public interface AsyncContext {
>      void dispatch(String path);
>
>      /**
> -     * @param path    The path to which the request/response should be dispatched relative to the specified
> -     *                    {@link ServletContext}.
> -     * @param context The {@link ServletContext} to which the request/response should be dispatched.
> +     * Dispatches the request to the resource at the specified path relative to the given {@link ServletContext}.
> +     * After the dispatch, the async request processing is complete and the response is committed.
> +     *
> +     * @param path    the path to which the request/response should be dispatched relative to the specified
> +     *                    {@link ServletContext}
> +     * @param context the {@link ServletContext} to which the request/response should be dispatched
>       *
>       * @throws IllegalStateException if this method is called when the request is not in asynchronous mode. The request
>       *                                   is in asynchronous mode after
> diff --git a/java/jakarta/servlet/GenericFilter.java b/java/jakarta/servlet/GenericFilter.java
> index 67b7962d79..ef6b8fb901 100644
> --- a/java/jakarta/servlet/GenericFilter.java
> +++ b/java/jakarta/servlet/GenericFilter.java
> @@ -34,11 +34,18 @@ public abstract class GenericFilter implements Filter, FilterConfig, Serializabl
>      @Serial
>      private static final long serialVersionUID = 1L;
>
> -    /**
> -     * The filter configuration.
> -     */
> +   /**
> +      * The filter configuration.
> +      */
>      private volatile FilterConfig filterConfig;
>
> +    /**
> +      * Constructs a new GenericFilter.
> +      */
> +    public GenericFilter() {
> +        // NO-OP
> +    }
> +
>
>      @Override
>      public String getInitParameter(String name) {
> diff --git a/java/jakarta/servlet/HttpConstraintElement.java b/java/jakarta/servlet/HttpConstraintElement.java
> index 90e310295c..51b3c41a50 100644
> --- a/java/jakarta/servlet/HttpConstraintElement.java
> +++ b/java/jakarta/servlet/HttpConstraintElement.java
> @@ -89,27 +89,27 @@ public class HttpConstraintElement {
>      }
>
>      /**
> -     * TODO
> +     * Returns the empty role semantic for this constraint.
>       *
> -     * @return TODO
> +     * @return The empty role semantic for this constraint
>       */
>      public EmptyRoleSemantic getEmptyRoleSemantic() {
>          return emptyRoleSemantic;
>      }
>
>      /**
> -     * TODO
> +     * Returns the transport guarantee for this constraint.
>       *
> -     * @return TODO
> +     * @return The transport guarantee for this constraint
>       */
>      public TransportGuarantee getTransportGuarantee() {
>          return transportGuarantee;
>      }
>
>      /**
> -     * TODO
> +     * Returns the roles allowed for this constraint.
>       *
> -     * @return TODO
> +     * @return The roles allowed for this constraint
>       */
>      public String[] getRolesAllowed() {
>          return rolesAllowed;
> diff --git a/java/jakarta/servlet/ServletContext.java b/java/jakarta/servlet/ServletContext.java
> index 15eba5a3a5..adf8ececdf 100644
> --- a/java/jakarta/servlet/ServletContext.java
> +++ b/java/jakarta/servlet/ServletContext.java
> @@ -551,7 +551,7 @@ public interface ServletContext {
>       *
>       * @since Servlet 3.0
>       */
> -    Map<String,? extends ServletRegistration> getServletRegistrations();
> +    Map<String, ? extends ServletRegistration> getServletRegistrations();
>
>      /**
>       * Add filter to context.
> @@ -644,11 +644,11 @@ public interface ServletContext {
>      <T extends Filter> T createFilter(Class<T> c) throws ServletException;
>
>      /**
> -     * TODO SERVLET3 - Add comments
> +     * Returns the {@link FilterRegistration} for the given filter, or <code>null</code> if no such filter exists.
>       *
> -     * @param filterName TODO
> +     * @param filterName The name of the filter for which to return the registration
>       *
> -     * @return TODO
> +     * @return The {@link FilterRegistration} for the given filter, or <code>null</code> if no such filter exists
>       *
>       * @throws UnsupportedOperationException If called from a
>       *                                           {@link ServletContextListener#contextInitialized(ServletContextEvent)}
> @@ -663,7 +663,10 @@ public interface ServletContext {
>      FilterRegistration getFilterRegistration(String filterName);
>
>      /**
> -     * @return TODO
> +     * Returns an immutable Map of all the filter registrations for this web application, where the key is the filter
> +     * name and the value is the {@link FilterRegistration} object.
> +     *
> +     * @return An immutable Map of all the filter registrations for this web application
>       *
>       * @throws UnsupportedOperationException If called from a
>       *                                           {@link ServletContextListener#contextInitialized(ServletContextEvent)}
> @@ -673,12 +676,15 @@ public interface ServletContext {
>       *                                           {@link ServletContextListener} defined in a TLD would not be able to
>       *                                           use this method.
>       *
> -     * @since Servlet 3.0 TODO SERVLET3 - Add comments
> +     * @since Servlet 3.0
>       */
> -    Map<String,? extends FilterRegistration> getFilterRegistrations();
> +    Map<String, ? extends FilterRegistration> getFilterRegistrations();
>
>      /**
> -     * @return TODO
> +     * Returns the {@link SessionCookieConfig} object for this web application, which can be used to configure the
> +     * session tracking cookie.
> +     *
> +     * @return The {@link SessionCookieConfig} object for this web application
>       *
>       * @throws UnsupportedOperationException If called from a
>       *                                           {@link ServletContextListener#contextInitialized(ServletContextEvent)}
> @@ -688,7 +694,7 @@ public interface ServletContext {
>       *                                           {@link ServletContextListener} defined in a TLD would not be able to
>       *                                           use this method.
>       *
> -     * @since Servlet 3.0 TODO SERVLET3 - Add comments
> +     * @since Servlet 3.0
>       */
>      SessionCookieConfig getSessionCookieConfig();
>
> @@ -735,10 +741,20 @@ public interface ServletContext {
>      Set<SessionTrackingMode> getEffectiveSessionTrackingModes();
>
>      /**
> -     * TODO SERVLET3 - Add comments
> +     * Adds a listener to this web application. The listener instance will be created by the container using the
> +     * no-argument constructor of the given class.
>       *
> -     * @param className TODO
> +     * @param className The fully qualified class name of the listener to add
>       *
> +     * @throws ClassCastException            If the class name does not implement {@link EventListener} or a
> +     *                                           subinterface recognized by the servlet container, or if a non-standard
> +     *                                           listener type is not packaged in a JAR file with a
> +     *                                           <code>listener</code> element in the <code>META-INF/services</code>
> +     *                                           directory
> +     * @throws IllegalArgumentException      If the lifecycle of a listener prohibits addition at runtime, or if the
> +     *                                           class has a {@link jakarta.servlet.annotation.WebListener} annotation
> +     *                                           that conflicts with the programmatic addition
> +     * @throws IllegalStateException         If the context has already been initialised
>       * @throws UnsupportedOperationException If called from a
>       *                                           {@link ServletContextListener#contextInitialized(ServletContextEvent)}
>       *                                           method of a {@link ServletContextListener} that was not defined in a
> @@ -752,11 +768,20 @@ public interface ServletContext {
>      void addListener(String className);
>
>      /**
> -     * TODO SERVLET3 - Add comments
> +     * Adds the given listener instance to this web application.
>       *
> -     * @param <T> TODO
> -     * @param t   TODO
> +     * @param <T> The type of listener being added
> +     * @param t   The listener instance to add
>       *
> +     * @throws ClassCastException            If the class of the listener instance does not implement
> +     *                                           {@link EventListener} or a subinterface recognized by the servlet
> +     *                                           container, or if a non-standard listener type is not packaged in a JAR
> +     *                                           file with a <code>listener</code> element in the
> +     *                                           <code>META-INF/services</code> directory
> +     * @throws IllegalArgumentException      If the lifecycle of a listener prohibits addition at runtime, or if the
> +     *                                           class has a {@link jakarta.servlet.annotation.WebListener} annotation
> +     *                                           that conflicts with the programmatic addition
> +     * @throws IllegalStateException         If the context has already been initialised
>       * @throws UnsupportedOperationException If called from a
>       *                                           {@link ServletContextListener#contextInitialized(ServletContextEvent)}
>       *                                           method of a {@link ServletContextListener} that was not defined in a
> @@ -770,10 +795,19 @@ public interface ServletContext {
>      <T extends EventListener> void addListener(T t);
>
>      /**
> -     * TODO SERVLET3 - Add comments
> +     * Adds a listener to this web application. The listener instance will be created by the container using the
> +     * no-argument constructor of the given class.
>       *
> -     * @param listenerClass TODO
> +     * @param listenerClass The class of the listener to add
>       *
> +     * @throws ClassCastException            If the class does not implement {@link EventListener} or a subinterface
> +     *                                           recognized by the servlet container, or if a non-standard listener type
> +     *                                           is not packaged in a JAR file with a <code>listener</code> element in
> +     *                                           the <code>META-INF/services</code> directory
> +     * @throws IllegalArgumentException      If the lifecycle of a listener prohibits addition at runtime, or if the
> +     *                                           class has a {@link jakarta.servlet.annotation.WebListener} annotation
> +     *                                           that conflicts with the programmatic addition
> +     * @throws IllegalStateException         If the context has already been initialised
>       * @throws UnsupportedOperationException If called from a
>       *                                           {@link ServletContextListener#contextInitialized(ServletContextEvent)}
>       *                                           method of a {@link ServletContextListener} that was not defined in a
> @@ -787,14 +821,15 @@ public interface ServletContext {
>      void addListener(Class<? extends EventListener> listenerClass);
>
>      /**
> -     * TODO SERVLET3 - Add comments
> +     * Creates a new instance of the given listener class, using the web application class loader.
>       *
> -     * @param <T> TODO
> -     * @param c   TODO
> +     * @param <T> The type of listener being created
> +     * @param c   The class of the listener to create
>       *
> -     * @return TODO
> +     * @return The new listener instance
>       *
> -     * @throws ServletException              TODO
> +     * @throws ServletException              If the listener cannot be instantiated, e.g., if the class does not have a
> +     *                                           no-argument constructor, or if instantiation fails for any other reason
>       * @throws UnsupportedOperationException If called from a
>       *                                           {@link ServletContextListener#contextInitialized(ServletContextEvent)}
>       *                                           method of a {@link ServletContextListener} that was not defined in a
> @@ -808,9 +843,12 @@ public interface ServletContext {
>      <T extends EventListener> T createListener(Class<T> c) throws ServletException;
>
>      /**
> -     * @return TODO
> +     * Returns the {@link JspConfigDescriptor} for this web application, which provides access to the JSP configuration
> +     * elements such as taglib and jsp-property-group declarations.
>       *
> -     * @since Servlet 3.0 TODO SERVLET3 - Add comments
> +     * @return The {@link JspConfigDescriptor} for this web application
> +     *
> +     * @since Servlet 3.0
>       */
>      JspConfigDescriptor getJspConfigDescriptor();
>
> diff --git a/java/jakarta/servlet/ServletRequest.java b/java/jakarta/servlet/ServletRequest.java
> index 749a9fc567..dea5715bd0 100644
> --- a/java/jakarta/servlet/ServletRequest.java
> +++ b/java/jakarta/servlet/ServletRequest.java
> @@ -441,54 +441,66 @@ public interface ServletRequest {
>      int getLocalPort();
>
>      /**
> -     * @return TODO
> +     * Returns the {@link ServletContext} to which this servlet belongs.
>       *
> -     * @since Servlet 3.0 TODO SERVLET3 - Add comments
> +     * @return the ServletContext associated with this request
> +     *
> +     * @since Servlet 3.0
>       */
>      ServletContext getServletContext();
>
>      /**
> -     * @return TODO
> +     * Initiates asynchronous processing for this request. The asynchronous processing is performed using the current
> +     * request and response objects.
> +     *
> +     * @return an {@link AsyncContext} instance for managing the asynchronous processing
>       *
> -     * @throws IllegalStateException If async is not supported for this request
> +     * @throws IllegalStateException if async is not supported for this request
>       *
> -     * @since Servlet 3.0 TODO SERVLET3 - Add comments
> +     * @since Servlet 3.0
>       */
>      AsyncContext startAsync() throws IllegalStateException;
>
>      /**
> -     * @param servletRequest  The ServletRequest with which to initialise the asynchronous context
> -     * @param servletResponse The ServletResponse with which to initialise the asynchronous context
> +     * Initiates asynchronous processing for this request using the specified request and response objects.
> +     *
> +     * @param servletRequest  the ServletRequest with which to initialise the asynchronous context
> +     * @param servletResponse the ServletResponse with which to initialise the asynchronous context
>       *
> -     * @return TODO
> +     * @return an {@link AsyncContext} instance for managing the asynchronous processing
>       *
> -     * @throws IllegalStateException If async is not supported for this request
> +     * @throws IllegalStateException if async is not supported for this request
>       *
> -     * @since Servlet 3.0 TODO SERVLET3 - Add comments
> +     * @since Servlet 3.0
>       */
>      AsyncContext startAsync(ServletRequest servletRequest, ServletResponse servletResponse)
>              throws IllegalStateException;
>
>      /**
> -     * @return TODO
> +     * Returns whether asynchronous processing has been started for this request.
>       *
> -     * @since Servlet 3.0 TODO SERVLET3 - Add comments
> +     * @return {@code true} if asynchronous processing has been started, {@code false} otherwise
> +     *
> +     * @since Servlet 3.0
>       */
>      boolean isAsyncStarted();
>
>      /**
> -     * @return TODO
> +     * Returns whether asynchronous processing is supported for this request and has not already been started.
> +     *
> +     * @return {@code true} if asynchronous processing is supported and has not yet been started, {@code false}
> +     *             otherwise
>       *
> -     * @since Servlet 3.0 TODO SERVLET3 - Add comments
> +     * @since Servlet 3.0
>       */
>      boolean isAsyncSupported();
>
>      /**
> -     * Get the current AsyncContext.
> +     * Returns the current {@link AsyncContext} associated with this request.
>       *
> -     * @return The current AsyncContext
> +     * @return the current AsyncContext
>       *
> -     * @throws IllegalStateException if the request is not in asynchronous mode (i.e. @link #isAsyncStarted() is
> +     * @throws IllegalStateException if the request is not in asynchronous mode (i.e. {@link #isAsyncStarted()} is
>       *                                   {@code false})
>       *
>       * @since Servlet 3.0
> @@ -496,9 +508,12 @@ public interface ServletRequest {
>      AsyncContext getAsyncContext();
>
>      /**
> -     * @return TODO
> +     * Returns the {@link DispatcherType} that represents the type of dispatch (REQUEST, FORWARD, INCLUDE, ERROR, or
> +     * ASYNC) through which this request was initiated.
> +     *
> +     * @return the DispatcherType for this request
>       *
> -     * @since Servlet 3.0 TODO SERVLET3 - Add comments
> +     * @since Servlet 3.0
>       */
>      DispatcherType getDispatcherType();
>
> diff --git a/java/jakarta/servlet/ServletRequestWrapper.java b/java/jakarta/servlet/ServletRequestWrapper.java
> index af003a0cc7..769aa13e3e 100644
> --- a/java/jakarta/servlet/ServletRequestWrapper.java
> +++ b/java/jakarta/servlet/ServletRequestWrapper.java
> @@ -164,7 +164,7 @@ public class ServletRequestWrapper implements ServletRequest {
>       * The default behavior of this method is to return getParameterMap() on the wrapped request object.
>       */
>      @Override
> -    public Map<String,String[]> getParameterMap() {
> +    public Map<String, String[]> getParameterMap() {
>          return this.request.getParameterMap();
>      }
>
> @@ -400,7 +400,8 @@ public class ServletRequestWrapper implements ServletRequest {
>      }
>
>      /**
> -     * TODO SERVLET3 - Add comments
> +     * If the request wrapped by this wrapper, or a wrapper used in the construction of this wrapper, instances the
> +     * given request, then return <code>true</code>. Otherwise return <code>false</code>.
>       *
>       * @param wrapped The request to compare to the wrapped request
>       *
> @@ -420,7 +421,8 @@ public class ServletRequestWrapper implements ServletRequest {
>      }
>
>      /**
> -     * TODO SERVLET3 - Add comments
> +     * If the request wrapped by this wrapper, or a wrapper used in the construction of this wrapper, is an instance of
> +     * the type given, then return <code>true</code>. Otherwise return <code>false</code>.
>       *
>       * @param wrappedType The class to compare to the class of the wrapped request
>       *
> diff --git a/java/jakarta/servlet/ServletResponseWrapper.java b/java/jakarta/servlet/ServletResponseWrapper.java
> index 94c4e5ac01..4f9b2b5c4f 100644
> --- a/java/jakarta/servlet/ServletResponseWrapper.java
> +++ b/java/jakarta/servlet/ServletResponseWrapper.java
> @@ -221,7 +221,8 @@ public class ServletResponseWrapper implements ServletResponse {
>      }
>
>      /**
> -     * TODO SERVLET3 - Add comments
> +     * If the response wrapped by this wrapper, or a wrapper used in the construction of this wrapper, instances the
> +     * given response, then return <code>true</code>. Otherwise return <code>false</code>.
>       *
>       * @param wrapped The response to compare to the wrapped response
>       *
> @@ -241,7 +242,8 @@ public class ServletResponseWrapper implements ServletResponse {
>      }
>
>      /**
> -     * TODO SERVLET3 - Add comments
> +     * If the response wrapped by this wrapper, or a wrapper used in the construction of this wrapper, is an instance of
> +     * the type given, then return <code>true</code>. Otherwise return <code>false</code>.
>       *
>       * @param wrappedType The class to compare to the class of the wrapped response
>       *
> diff --git a/java/jakarta/servlet/annotation/HandlesTypes.java b/java/jakarta/servlet/annotation/HandlesTypes.java
> index 7dd52b165c..203340c8b9 100644
> --- a/java/jakarta/servlet/annotation/HandlesTypes.java
> +++ b/java/jakarta/servlet/annotation/HandlesTypes.java
> @@ -31,9 +31,11 @@ import java.lang.annotation.Target;
>  @Retention(RetentionPolicy.RUNTIME)
>  public @interface HandlesTypes {
>
> -    /**
> -     * @return array of classes
> -     */
> +   /**
> +      * Declares the classes handled by the {@link jakarta.servlet.ServletContainerInitializer}.
> +      *
> +      * @return array of classes
> +      */
>      Class<?>[] value();
>
>  }
> diff --git a/java/jakarta/servlet/annotation/MultipartConfig.java b/java/jakarta/servlet/annotation/MultipartConfig.java
> index 0558b7dfd4..d0538bf954 100644
> --- a/java/jakarta/servlet/annotation/MultipartConfig.java
> +++ b/java/jakarta/servlet/annotation/MultipartConfig.java
> @@ -41,22 +41,31 @@ import java.lang.annotation.Target;
>  public @interface MultipartConfig {
>
>      /**
> +     * Specifies the location in which the Container stores temporary files.
> +     *
>       * @return location in which the Container stores temporary files
>       */
>      String location() default "";
>
>      /**
> +     * Specifies the maximum size allowed for uploaded files.
> +     *
>       * @return the maximum size allowed for uploaded files (in bytes)
>       */
>      long maxFileSize() default -1L;
>
>      /**
> +     * Specifies the maximum size of the request allowed for {@code
> +     * multipart/form-data}.
> +     *
>       * @return the maximum size of the request allowed for {@code
>       *         multipart/form-data}
>       */
>      long maxRequestSize() default -1L;
>
>      /**
> +     * Specifies the size threshold in bytes after which the file will be written to disk.
> +     *
>       * @return the size threshold at which the file will be written to the disk
>       */
>      int fileSizeThreshold() default 0;
> diff --git a/java/jakarta/servlet/annotation/WebFilter.java b/java/jakarta/servlet/annotation/WebFilter.java
> index a277d43788..d23d9f2b0e 100644
> --- a/java/jakarta/servlet/annotation/WebFilter.java
> +++ b/java/jakarta/servlet/annotation/WebFilter.java
> @@ -50,36 +50,50 @@ import jakarta.servlet.DispatcherType;
>  public @interface WebFilter {
>
>      /**
> +     * Provides a description of the Filter.
> +     *
>       * @return description of the Filter, if present
>       */
>      String description() default "";
>
>      /**
> +     * Provides a display name for the Filter.
> +     *
>       * @return display name of the Filter, if present
>       */
>      String displayName() default "";
>
>      /**
> +     * Declares initialization parameters for the Filter.
> +     *
>       * @return array of initialization params for this Filter
>       */
>      WebInitParam[] initParams() default {};
>
>      /**
> +     * Declares the name of the Filter.
> +     *
>       * @return name of the Filter, if present
>       */
>      String filterName() default "";
>
>      /**
> +     * Provides a small icon for the Filter.
> +     *
>       * @return small icon for this Filter, if present
>       */
>      String smallIcon() default "";
>
>      /**
> +     * Provides a large icon for the Filter.
> +     *
>       * @return the large icon for this Filter, if present
>       */
>      String largeIcon() default "";
>
>      /**
> +     * Declares the servlet names to which this Filter applies.
> +     *
>       * @return array of Servlet names to which this Filter applies
>       */
>      String[] servletNames() default {};
> @@ -94,17 +108,23 @@ public @interface WebFilter {
>      String[] value() default {};
>
>      /**
> +     * Declares the URL patterns to which this Filter applies.
> +     *
>       * @return array of URL patterns to which this Filter applies
>       */
>      String[] urlPatterns() default {};
>
>      /**
> +     * Declares the dispatcher types to which this Filter applies.
> +     *
>       * @return array of DispatcherTypes to which this filter applies
>       */
>      DispatcherType[] dispatcherTypes() default { DispatcherType.REQUEST };
>
>      /**
> -     * @return asynchronous operation supported by this Filter
> +     * Declares whether asynchronous operation is supported by this Filter.
> +     *
> +     * @return {@code true} if asynchronous operation is supported, {@code false} otherwise
>       */
>      boolean asyncSupported() default false;
>  }
> diff --git a/java/jakarta/servlet/annotation/WebInitParam.java b/java/jakarta/servlet/annotation/WebInitParam.java
> index feb4bf901b..d541fa7cff 100644
> --- a/java/jakarta/servlet/annotation/WebInitParam.java
> +++ b/java/jakarta/servlet/annotation/WebInitParam.java
> @@ -39,16 +39,22 @@ import java.lang.annotation.Target;
>  public @interface WebInitParam {
>
>      /**
> +     * The name of the initialization parameter.
> +     *
>       * @return name of the initialization parameter
>       */
>      String name();
>
>      /**
> +     * The value of the initialization parameter.
> +     *
>       * @return value of the initialization parameter
>       */
>      String value();
>
>      /**
> +     * A description of the initialization parameter.
> +     *
>       * @return description of the initialization parameter
>       */
>      String description() default "";
> diff --git a/java/jakarta/servlet/annotation/WebListener.java b/java/jakarta/servlet/annotation/WebListener.java
> index aee671b4fa..d01a2d658d 100644
> --- a/java/jakarta/servlet/annotation/WebListener.java
> +++ b/java/jakarta/servlet/annotation/WebListener.java
> @@ -41,6 +41,8 @@ import java.lang.annotation.Target;
>  public @interface WebListener {
>
>      /**
> +     * Provides a description of the listener.
> +     *
>       * @return description of the listener, if present
>       */
>      String value() default "";
> diff --git a/java/jakarta/servlet/annotation/WebServlet.java b/java/jakarta/servlet/annotation/WebServlet.java
> index 5e1334bd1e..ed12b5b1a3 100644
> --- a/java/jakarta/servlet/annotation/WebServlet.java
> +++ b/java/jakarta/servlet/annotation/WebServlet.java
> @@ -46,57 +46,75 @@ import java.lang.annotation.Target;
>  @Documented
>  public @interface WebServlet {
>
> -    /**
> -     * @return name of the Servlet
> -     */
> +   /**
> +      * Provides the name of this servlet.
> +      *
> +      * @return name of the Servlet
> +      */
>      String name() default "";
>
> -    /**
> -     * A convenience method, to allow extremely simple annotation of a class.
> -     *
> -     * @return array of URL patterns
> -     *
> -     * @see #urlPatterns()
> -     */
> +      /**
> +       * A convenience method, to allow extremely simple annotation of a class.
> +       *
> +       * @return array of URL patterns
> +       *
> +       * @see #urlPatterns()
> +       */
>      String[] value() default {};
>
> -    /**
> -     * @return array of URL patterns to which this Filter applies
> -     */
> +      /**
> +       * Declares the URL patterns for this servlet.
> +       *
> +       * @return array of URL patterns to which this Servlet applies
> +       */
>      String[] urlPatterns() default {};
>
> -    /**
> -     * @return load on startup ordering hint
> -     */
> +      /**
> +       * Provides a load-on-startup ordering hint for this servlet.
> +       *
> +       * @return load on startup ordering hint
> +       */
>      int loadOnStartup() default -1;
>
> -    /**
> -     * @return array of initialization params for this Servlet
> -     */
> +      /**
> +       * Declares initialization parameters for this servlet.
> +       *
> +       * @return array of initialization params for this Servlet
> +       */
>      WebInitParam[] initParams() default {};
>
> -    /**
> -     * @return asynchronous operation supported by this Servlet
> -     */
> +      /**
> +       * Indicates whether this servlet supports asynchronous operation.
> +       *
> +       * @return asynchronous operation supported by this Servlet
> +       */
>      boolean asyncSupported() default false;
>
> -    /**
> -     * @return small icon for this Servlet, if present
> -     */
> +      /**
> +       * Provides the URL of a small icon for this servlet.
> +       *
> +       * @return small icon for this Servlet, if present
> +       */
>      String smallIcon() default "";
>
> -    /**
> -     * @return large icon for this Servlet, if present
> -     */
> +      /**
> +       * Provides the URL of a large icon for this servlet.
> +       *
> +       * @return large icon for this Servlet, if present
> +       */
>      String largeIcon() default "";
>
> -    /**
> -     * @return description of this Servlet, if present
> -     */
> +      /**
> +       * Provides a description of this servlet.
> +       *
> +       * @return description of this Servlet, if present
> +       */
>      String description() default "";
>
> -    /**
> -     * @return display name of this Servlet, if present
> -     */
> +      /**
> +       * Provides a display name for this servlet.
> +       *
> +       * @return display name of this Servlet, if present
> +       */
>      String displayName() default "";
>  }
> diff --git a/java/jakarta/servlet/http/HttpFilter.java b/java/jakarta/servlet/http/HttpFilter.java
> index a4cbf8208a..85070f9f58 100644
> --- a/java/jakarta/servlet/http/HttpFilter.java
> +++ b/java/jakarta/servlet/http/HttpFilter.java
> @@ -34,6 +34,13 @@ public abstract class HttpFilter extends GenericFilter {
>      @Serial
>      private static final long serialVersionUID = 1L;
>
> +    /**
> +      * Constructs a new HttpFilter.
> +      */
> +    public HttpFilter() {
> +        // NO-OP
> +    }
> +
>      /**
>       * {@inheritDoc} This implementation tests the request and response to see if they are instances of
>       * {@link HttpServletRequest} and {@link HttpServletResponse} respectively. If they are then they are passed to
> diff --git a/java/jakarta/servlet/http/HttpServletMapping.java b/java/jakarta/servlet/http/HttpServletMapping.java
> index ae88d321de..aece46c8e8 100644
> --- a/java/jakarta/servlet/http/HttpServletMapping.java
> +++ b/java/jakarta/servlet/http/HttpServletMapping.java
> @@ -25,25 +25,33 @@ import jakarta.servlet.annotation.WebServlet;
>   */
>  public interface HttpServletMapping {
>
> -    /**
> -     * @return The value that was matched or the empty String if not known.
> -     */
> +   /**
> +      * Returns the value that was matched when mapping the request to the servlet.
> +      *
> +      * @return The value that was matched or the empty String if not known.
> +      */
>      String getMatchValue();
>
> -    /**
> -     * @return The {@code url-pattern} that matched this request or the empty String if not known.
> -     */
> +      /**
> +       * Returns the URL pattern that matched this request.
> +       *
> +       * @return The {@code url-pattern} that matched this request or the empty String if not known.
> +       */
>      String getPattern();
>
> -    /**
> -     * @return The name of the servlet (as specified in web.xml, {@link WebServlet#name()},
> -     *             {@link jakarta.servlet.ServletContext#addServlet(String, Class)} or one of the other
> -     *             <code>addServlet()</code> methods) that the request was mapped to.
> -     */
> +      /**
> +       * Returns the name of the servlet to which the request was mapped.
> +       *
> +       * @return The name of the servlet (as specified in web.xml, {@link WebServlet#name()},
> +       *             {@link jakarta.servlet.ServletContext#addServlet(String, Class)} or one of the other
> +       *             <code>addServlet()</code> methods) that the request was mapped to.
> +       */
>      String getServletName();
>
> -    /**
> -     * @return The type of match ({@code null} if not known)
> -     */
> +      /**
> +       * Returns the type of match used to map the request to the servlet.
> +       *
> +       * @return The type of match ({@code null} if not known)
> +       */
>      MappingMatch getMappingMatch();
>  }
> diff --git a/java/jakarta/servlet/http/PushBuilder.java b/java/jakarta/servlet/http/PushBuilder.java
> index 46c6ed72bc..0adbda4a69 100644
> --- a/java/jakarta/servlet/http/PushBuilder.java
> +++ b/java/jakarta/servlet/http/PushBuilder.java
> @@ -156,12 +156,16 @@ public interface PushBuilder {
>      String getSessionId();
>
>      /**
> +     * Returns the set of names of HTTP headers that will be used the next time {@code push()} is called.
> +     *
>       * @return The current set of names of HTTP headers to be used the next time {@code push()} is called.
>       */
>      Set<String> getHeaderNames();
>
>      /**
> -     * Obtain a value for the given HTTP header. TODO Servlet 4.0 Clarify the behaviour of this method
> +     * Obtain a value for the given HTTP header. If the push builder has not had this header set, the return value is
> +     * <code>null</code>. If the push builder has had this header set multiple times, the value returned is
> +     * implementation-specific.
>       *
>       * @param name The name of the header whose value is to be returned
>       *
> diff --git a/java/jakarta/transaction/HeuristicCommitException.java b/java/jakarta/transaction/HeuristicCommitException.java
> index 1c56f380d8..8f1e2e63a6 100644
> --- a/java/jakarta/transaction/HeuristicCommitException.java
> +++ b/java/jakarta/transaction/HeuristicCommitException.java
> @@ -18,15 +18,29 @@ package jakarta.transaction;
>
>  import java.io.Serial;
>
> +/**
> + * Thrown when a transaction has been heuristically committed. A heuristic
> + * commit indicates that the transaction manager has committed the transaction
> + * without full agreement from all resource managers, typically as a result of
> + * a failure during the commit process.
> + */
>  public class HeuristicCommitException extends Exception {
>
>      @Serial
>      private static final long serialVersionUID = -3977609782149921760L;
>
> +    /**
> +     * Constructs a {@code HeuristicCommitException} with no detail message.
> +     */
>      public HeuristicCommitException() {
>          super();
>      }
>
> +    /**
> +     * Constructs a {@code HeuristicCommitException} with the specified detail message.
> +     *
> +     * @param msg the detail message
> +     */
>      public HeuristicCommitException(String msg) {
>          super(msg);
>      }
> diff --git a/java/jakarta/transaction/HeuristicMixedException.java b/java/jakarta/transaction/HeuristicMixedException.java
> index 50b86867a3..fbc2a93eff 100644
> --- a/java/jakarta/transaction/HeuristicMixedException.java
> +++ b/java/jakarta/transaction/HeuristicMixedException.java
> @@ -18,15 +18,29 @@ package jakarta.transaction;
>
>  import java.io.Serial;
>
> +/**
> + * Thrown when a transaction has been heuristically committed in part and
> + * heuristically rolled back in part. A heuristic mixed result indicates that
> + * some resource managers committed the transaction while others rolled it
> + * back, typically as a result of a failure during the commit process.
> + */
>  public class HeuristicMixedException extends Exception {
>
>      @Serial
>      private static final long serialVersionUID = 2345014349685956666L;
>
> +    /**
> +     * Constructs a {@code HeuristicMixedException} with no detail message.
> +     */
>      public HeuristicMixedException() {
>          super();
>      }
>
> +    /**
> +     * Constructs a {@code HeuristicMixedException} with the specified detail message.
> +     *
> +     * @param msg the detail message
> +     */
>      public HeuristicMixedException(String msg) {
>          super(msg);
>      }
> diff --git a/java/jakarta/transaction/HeuristicRollbackException.java b/java/jakarta/transaction/HeuristicRollbackException.java
> index 2ee7cc6bf5..0aa897539b 100644
> --- a/java/jakarta/transaction/HeuristicRollbackException.java
> +++ b/java/jakarta/transaction/HeuristicRollbackException.java
> @@ -18,15 +18,29 @@ package jakarta.transaction;
>
>  import java.io.Serial;
>
> +/**
> + * Thrown when a transaction has been heuristically rolled back. A heuristic
> + * rollback indicates that the transaction manager has rolled back the
> + * transaction without full agreement from all resource managers, typically
> + * as a result of a failure during the commit process.
> + */
>  public class HeuristicRollbackException extends Exception {
>
>      @Serial
>      private static final long serialVersionUID = -3483618944556408897L;
>
> +    /**
> +     * Constructs a {@code HeuristicRollbackException} with no detail message.
> +     */
>      public HeuristicRollbackException() {
>          super();
>      }
>
> +    /**
> +     * Constructs a {@code HeuristicRollbackException} with the specified detail message.
> +     *
> +     * @param msg the detail message
> +     */
>      public HeuristicRollbackException(String msg) {
>          super(msg);
>      }
> diff --git a/java/jakarta/transaction/InvalidTransactionException.java b/java/jakarta/transaction/InvalidTransactionException.java
> index 97e0476ab1..d8b1e12ce6 100644
> --- a/java/jakarta/transaction/InvalidTransactionException.java
> +++ b/java/jakarta/transaction/InvalidTransactionException.java
> @@ -18,15 +18,28 @@ package jakarta.transaction;
>
>  import java.io.Serial;
>
> +/**
> + * Thrown when a transaction is invalid. This exception indicates that the
> + * transaction on which an operation was attempted is no longer valid, for
> + * example because it has already completed or been rolled back.
> + */
>  public class InvalidTransactionException extends java.rmi.RemoteException {
>
>      @Serial
>      private static final long serialVersionUID = 3597320220337691496L;
>
> +    /**
> +     * Constructs an {@code InvalidTransactionException} with no detail message.
> +     */
>      public InvalidTransactionException() {
>          super();
>      }
>
> +    /**
> +     * Constructs an {@code InvalidTransactionException} with the specified detail message.
> +     *
> +     * @param msg the detail message
> +     */
>      public InvalidTransactionException(String msg) {
>          super(msg);
>      }
> diff --git a/java/jakarta/transaction/NotSupportedException.java b/java/jakarta/transaction/NotSupportedException.java
> index 073ce36240..263a44f852 100644
> --- a/java/jakarta/transaction/NotSupportedException.java
> +++ b/java/jakarta/transaction/NotSupportedException.java
> @@ -18,15 +18,26 @@ package jakarta.transaction;
>
>  import java.io.Serial;
>
> +/**
> + * Thrown when a requested operation is not supported.
> + */
>  public class NotSupportedException extends Exception {
>
>      @Serial
>      private static final long serialVersionUID = 56870312332816390L;
>
> +    /**
> +     * Constructs a {@code NotSupportedException} with no detail message.
> +     */
>      public NotSupportedException() {
>          super();
>      }
>
> +    /**
> +     * Constructs a {@code NotSupportedException} with the specified detail message.
> +     *
> +     * @param msg the detail message
> +     */
>      public NotSupportedException(String msg) {
>          super(msg);
>      }
> diff --git a/java/jakarta/transaction/RollbackException.java b/java/jakarta/transaction/RollbackException.java
> index f0b1d0b887..7b6beb84be 100644
> --- a/java/jakarta/transaction/RollbackException.java
> +++ b/java/jakarta/transaction/RollbackException.java
> @@ -18,15 +18,26 @@ package jakarta.transaction;
>
>  import java.io.Serial;
>
> +/**
> + * Thrown when a transaction must be rolled back.
> + */
>  public class RollbackException extends Exception {
>
>      @Serial
>      private static final long serialVersionUID = 4151607774785285395L;
>
> +    /**
> +     * Constructs a {@code RollbackException} with no detail message.
> +     */
>      public RollbackException() {
>          super();
>      }
>
> +    /**
> +     * Constructs a {@code RollbackException} with the specified detail message.
> +     *
> +     * @param msg the detail message
> +     */
>      public RollbackException(String msg) {
>          super(msg);
>      }
> diff --git a/java/jakarta/transaction/Status.java b/java/jakarta/transaction/Status.java
> index 9b113fc406..d05176b77f 100644
> --- a/java/jakarta/transaction/Status.java
> +++ b/java/jakarta/transaction/Status.java
> @@ -16,15 +16,48 @@
>   */
>  package jakarta.transaction;
>
> +/**
> + * Defines the set of status constants for a transaction.
> + */
>  public interface Status {
> +    /**
> +     * The transaction is active and work is in progress.
> +     */
>      int STATUS_ACTIVE = 0;
> +    /**
> +     * The transaction has been marked for rollback only.
> +     */
>      int STATUS_MARKED_ROLLBACK = 1;
> +    /**
> +     * The transaction resources have been prepared and are awaiting completion.
> +     */
>      int STATUS_PREPARED = 2;
> +    /**
> +     * The transaction has been committed successfully.
> +     */
>      int STATUS_COMMITTED = 3;
> +    /**
> +     * The transaction has been rolled back.
> +     */
>      int STATUS_ROLLEDBACK = 4;
> +    /**
> +     * The transaction status is unknown.
> +     */
>      int STATUS_UNKNOWN = 5;
> +    /**
> +     * There is no active transaction for the current thread.
> +     */
>      int STATUS_NO_TRANSACTION = 6;
> +    /**
> +     * The transaction manager is in the process of preparing the transaction resources.
> +     */
>      int STATUS_PREPARING = 7;
> +    /**
> +     * The transaction manager is in the process of committing the transaction.
> +     */
>      int STATUS_COMMITTING = 8;
> +    /**
> +     * The transaction manager is in the process of rolling back the transaction.
> +     */
>      int STATUS_ROLLING_BACK = 9;
>  }
> diff --git a/java/jakarta/transaction/Synchronization.java b/java/jakarta/transaction/Synchronization.java
> index b188911cda..c9b20d0555 100644
> --- a/java/jakarta/transaction/Synchronization.java
> +++ b/java/jakarta/transaction/Synchronization.java
> @@ -16,8 +16,25 @@
>   */
>  package jakarta.transaction;
>
> +/**
> + * Callback interface for notification of transaction completion.
> + * Registered with a transaction so that the implementing object is
> + * notified when the transaction is about to complete and when it has
> + * completed.
> + */
>  public interface Synchronization {
> +    /**
> +     * Called before the transaction is committed or rolled back.
> +     * This method is invoked after all work on the transaction has
> +     * been completed but before the commit or rollback is performed.
> +     */
>      void beforeCompletion();
>
> +    /**
> +     * Called after the transaction has completed.
> +     *
> +     * @param status the status of the transaction, one of the
> +     *               {@link Status} constants
> +     */
>      void afterCompletion(int status);
>  }
> diff --git a/java/jakarta/transaction/SystemException.java b/java/jakarta/transaction/SystemException.java
> index 5c3bd33492..9b9a71d424 100644
> --- a/java/jakarta/transaction/SystemException.java
> +++ b/java/jakarta/transaction/SystemException.java
> @@ -18,21 +18,42 @@ package jakarta.transaction;
>
>  import java.io.Serial;
>
> +/**
> + * Thrown to indicate a system error during transaction processing.
> + * When this exception is thrown, the state of the transaction is
> + * unknown and may need to be rolled back.
> + */
>  public class SystemException extends Exception {
>
>      @Serial
>      private static final long serialVersionUID = 8615483418828223571L;
>
> +    /**
> +     * The error code associated with this exception.
> +     */
>      public int errorCode;
>
> +    /**
> +     * Constructs a {@code SystemException} with no detail message.
> +     */
>      public SystemException() {
>          super();
>      }
>
> +    /**
> +     * Constructs a {@code SystemException} with the specified detail message.
> +     *
> +     * @param s the detail message
> +     */
>      public SystemException(String s) {
>          super(s);
>      }
>
> +    /**
> +     * Constructs a {@code SystemException} with the specified error code.
> +     *
> +     * @param errcode the error code
> +     */
>      public SystemException(int errcode) {
>          super();
>          errorCode = errcode;
> diff --git a/java/jakarta/transaction/Transaction.java b/java/jakarta/transaction/Transaction.java
> index 1f031d2a8b..626786afa8 100644
> --- a/java/jakarta/transaction/Transaction.java
> +++ b/java/jakarta/transaction/Transaction.java
> @@ -18,21 +18,84 @@ package jakarta.transaction;
>
>  import javax.transaction.xa.XAResource;
>
> +/**
> + * Represents an active transaction.
> + * Provides methods for committing, rolling back, and managing
> + * resources enlisted in the transaction.
> + */
>  public interface Transaction {
>
> +    /**
> +     * Commits the transaction.
> +     *
> +     * @throws RollbackException if the transaction has been marked for rollback only
> +     * @throws HeuristicMixedException if the transaction was heuristically
> +     *         partitioned, with some resources committed and others rolled back
> +     * @throws HeuristicRollbackException if the transaction was heuristically rolled back
> +     * @throws SecurityException if the caller is not authorized to commit
> +     * @throws IllegalStateException if the transaction is not active
> +     * @throws SystemException if a system error occurred
> +     */
>      void commit() throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SecurityException,
>              IllegalStateException, SystemException;
>
> +    /**
> +     * Delists the specified XA resource from this transaction.
> +     *
> +     * @param xaRes the XA resource to delist
> +     * @param flag one of {@code TMSUCCESS}, {@code TMFAIL}, or {@code TMSTARTEPOCH}
> +     * @return {@code true} if the resource was delisted, {@code false} otherwise
> +     * @throws IllegalStateException if the transaction is not active
> +     * @throws SystemException if a system error occurred
> +     */
>      boolean delistResource(XAResource xaRes, int flag) throws IllegalStateException, SystemException;
>
> +    /**
> +     * Enlists the specified XA resource with this transaction.
> +     *
> +     * @param xaRes the XA resource to enlist
> +     *
> +     * @return {@code true} if the resource was enlisted, {@code false} otherwise
> +     *
> +     * @throws RollbackException if the transaction has been marked for rollback only
> +     * @throws IllegalStateException if the transaction is not active or the
> +     *         resource is already enlisted
> +     * @throws SystemException if a system error occurred
> +     */
>      boolean enlistResource(XAResource xaRes) throws RollbackException, IllegalStateException, SystemException;
>
> +    /**
> +     * Returns the status of this transaction.
> +     *
> +     * @return the transaction status, one of the {@link Status} constants
> +     * @throws SystemException if a system error occurred
> +     */
>      int getStatus() throws SystemException;
>
> +    /**
> +     * Registers a synchronization callback with this transaction.
> +     *
> +     * @param sync the synchronization callback to register
> +     * @throws RollbackException if the transaction has been marked for rollback only
> +     * @throws IllegalStateException if the transaction is not active
> +     * @throws SystemException if a system error occurred
> +     */
>      void registerSynchronization(Synchronization sync) throws RollbackException, IllegalStateException, SystemException;
>
> +    /**
> +     * Rolls back the transaction.
> +     *
> +     * @throws IllegalStateException if the transaction is not active
> +     * @throws SystemException if a system error occurred
> +     */
>      void rollback() throws IllegalStateException, SystemException;
>
> +    /**
> +     * Marks this transaction so that the only valid outcome is a rollback.
> +     *
> +     * @throws IllegalStateException if the transaction is not active
> +     * @throws SystemException if a system error occurred
> +     */
>      void setRollbackOnly() throws IllegalStateException, SystemException;
>
>  }
> diff --git a/java/jakarta/transaction/TransactionManager.java b/java/jakarta/transaction/TransactionManager.java
> index 2bd58e16c8..633b3775ca 100644
> --- a/java/jakarta/transaction/TransactionManager.java
> +++ b/java/jakarta/transaction/TransactionManager.java
> @@ -16,23 +16,91 @@
>   */
>  package jakarta.transaction;
>
> +/**
> + * Provides methods for managing transactions.
> + * Used by the transaction manager to begin, commit, and roll back
> + * transactions, and to suspend and resume them.
> + */
>  public interface TransactionManager {
> +    /**
> +     * Begins a new transaction for the current thread.
> +     *
> +     * @throws NotSupportedException if the transaction manager does not
> +     *         support transactions
> +     * @throws SystemException if a system error occurred
> +     */
>      void begin() throws NotSupportedException, SystemException;
>
> +    /**
> +     * Commits the transaction associated with the current thread.
> +     *
> +     * @throws RollbackException if the transaction has been marked for rollback only
> +     * @throws HeuristicMixedException if the transaction was heuristically
> +     *         partitioned
> +     * @throws HeuristicRollbackException if the transaction was heuristically rolled back
> +     * @throws SecurityException if the caller is not authorized to commit
> +     * @throws IllegalStateException if no transaction is active
> +     * @throws SystemException if a system error occurred
> +     */
>      void commit() throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SecurityException,
>              IllegalStateException, SystemException;
>
> +    /**
> +     * Returns the status of the transaction associated with the current thread.
> +     *
> +     * @return the transaction status, one of the {@link Status} constants
> +     * @throws SystemException if a system error occurred
> +     */
>      int getStatus() throws SystemException;
>
> +    /**
> +     * Returns the {@link Transaction} object associated with the current thread.
> +     *
> +     * @return the current transaction, or {@code null} if there is no active transaction
> +     * @throws SystemException if a system error occurred
> +     */
>      Transaction getTransaction() throws SystemException;
>
> +    /**
> +     * Resumes a previously suspended transaction for the current thread.
> +     *
> +     * @param tobj the transaction to resume
> +     * @throws InvalidTransactionException if the transaction is no longer valid
> +     * @throws IllegalStateException if there is already an active transaction
> +     * @throws SystemException if a system error occurred
> +     */
>      void resume(Transaction tobj) throws InvalidTransactionException, IllegalStateException, SystemException;
>
> +    /**
> +     * Rolls back the transaction associated with the current thread.
> +     *
> +     * @throws IllegalStateException if no transaction is active
> +     * @throws SecurityException if the caller is not authorized to roll back
> +     * @throws SystemException if a system error occurred
> +     */
>      void rollback() throws IllegalStateException, SecurityException, SystemException;
>
> +    /**
> +     * Marks the current transaction so that the only valid outcome is a rollback.
> +     *
> +     * @throws IllegalStateException if no transaction is active
> +     * @throws SystemException if a system error occurred
> +     */
>      void setRollbackOnly() throws IllegalStateException, SystemException;
>
> +    /**
> +     * Sets the default transaction timeout.
> +     *
> +     * @param seconds the timeout value in seconds
> +     * @throws SystemException if a system error occurred
> +     */
>      void setTransactionTimeout(int seconds) throws SystemException;
>
> +    /**
> +     * Suspends the transaction associated with the current thread.
> +     *
> +     * @return the suspended transaction, or {@code null} if there was no active transaction
> +     * @throws SystemException if a system error occurred
> +     */
>      Transaction suspend() throws SystemException;
>  }
> diff --git a/java/jakarta/transaction/TransactionRequiredException.java b/java/jakarta/transaction/TransactionRequiredException.java
> index 32d7aef467..be6a2a6c1c 100644
> --- a/java/jakarta/transaction/TransactionRequiredException.java
> +++ b/java/jakarta/transaction/TransactionRequiredException.java
> @@ -18,15 +18,26 @@ package jakarta.transaction;
>
>  import java.io.Serial;
>
> +/**
> + * Thrown when an operation requires an active transaction but none exists.
> + */
>  public class TransactionRequiredException extends java.rmi.RemoteException {
>
>      @Serial
>      private static final long serialVersionUID = -1898806419937446439L;
>
> +    /**
> +     * Constructs a {@code TransactionRequiredException} with no detail message.
> +     */
>      public TransactionRequiredException() {
>          super();
>      }
>
> +    /**
> +     * Constructs a {@code TransactionRequiredException} with the specified detail message.
> +     *
> +     * @param msg the detail message
> +     */
>      public TransactionRequiredException(String msg) {
>          super(msg);
>      }
> diff --git a/java/jakarta/transaction/TransactionRolledbackException.java b/java/jakarta/transaction/TransactionRolledbackException.java
> index 3195c429e1..12bf91627a 100644
> --- a/java/jakarta/transaction/TransactionRolledbackException.java
> +++ b/java/jakarta/transaction/TransactionRolledbackException.java
> @@ -18,15 +18,26 @@ package jakarta.transaction;
>
>  import java.io.Serial;
>
> +/**
> + * Thrown when an operation is attempted on a transaction that has been rolled back.
> + */
>  public class TransactionRolledbackException extends java.rmi.RemoteException {
>
>      @Serial
>      private static final long serialVersionUID = -3142798139623020577L;
>
> +    /**
> +     * Constructs a {@code TransactionRolledbackException} with no detail message.
> +     */
>      public TransactionRolledbackException() {
>          super();
>      }
>
> +    /**
> +     * Constructs a {@code TransactionRolledbackException} with the specified detail message.
> +     *
> +     * @param msg the detail message
> +     */
>      public TransactionRolledbackException(String msg) {
>          super(msg);
>      }
> diff --git a/java/jakarta/transaction/TransactionSynchronizationRegistry.java b/java/jakarta/transaction/TransactionSynchronizationRegistry.java
> index b2ac98f3e2..1332cb07f0 100644
> --- a/java/jakarta/transaction/TransactionSynchronizationRegistry.java
> +++ b/java/jakarta/transaction/TransactionSynchronizationRegistry.java
> @@ -16,18 +16,58 @@
>   */
>  package jakarta.transaction;
>
> +/**
> + * Provides a resource and transaction registry for resource managers.
> + * Allows resource managers to associate resources with the current
> + * transaction and register synchronization callbacks.
> + */
>  public interface TransactionSynchronizationRegistry {
> +    /**
> +     * Returns the unique key identifying the current transaction.
> +     *
> +     * @return the transaction key, or {@code null} if there is no active transaction
> +     */
>      Object getTransactionKey();
>
> +    /**
> +     * Associates a resource with the given key in the current transaction context.
> +     *
> +     * @param key the key to associate with the resource
> +     * @param value the resource object to associate
> +     */
>      void putResource(Object key, Object value);
>
> +    /**
> +     * Returns the resource associated with the given key in the current transaction context.
> +     *
> +     * @param key the key of the resource to retrieve
> +     * @return the associated resource, or {@code null} if no resource is found
> +     */
>      Object getResource(Object key);
>
> +    /**
> +     * Registers an interposed synchronization callback with the current transaction.
> +     *
> +     * @param sync the synchronization callback to register
> +     */
>      void registerInterposedSynchronization(Synchronization sync);
>
> +    /**
> +     * Returns the status of the current transaction.
> +     *
> +     * @return the transaction status, one of the {@link Status} constants
> +     */
>      int getTransactionStatus();
>
> +    /**
> +     * Marks the current transaction so that the only valid outcome is a rollback.
> +     */
>      void setRollbackOnly();
>
> +    /**
> +     * Returns whether the current transaction has been marked for rollback only.
> +     *
> +     * @return {@code true} if the transaction is marked for rollback only
> +     */
>      boolean getRollbackOnly();
>  }
> diff --git a/java/jakarta/transaction/UserTransaction.java b/java/jakarta/transaction/UserTransaction.java
> index 0506c9c102..04c558c0a4 100644
> --- a/java/jakarta/transaction/UserTransaction.java
> +++ b/java/jakarta/transaction/UserTransaction.java
> @@ -16,17 +16,64 @@
>   */
>  package jakarta.transaction;
>
> +/**
> + * Provides methods for managing user transactions.
> + * Allows application code to demarcate transaction boundaries explicitly.
> + */
>  public interface UserTransaction {
> +    /**
> +     * Begins a new transaction for the current thread.
> +     *
> +     * @throws NotSupportedException if the transaction manager does not
> +     *         support transactions
> +     * @throws SystemException if a system error occurred
> +     */
>      void begin() throws NotSupportedException, SystemException;
>
> +    /**
> +     * Commits the transaction associated with the current thread.
> +     *
> +     * @throws RollbackException if the transaction has been marked for rollback only
> +     * @throws HeuristicMixedException if the transaction was heuristically
> +     *         partitioned
> +     * @throws HeuristicRollbackException if the transaction was heuristically rolled back
> +     * @throws SecurityException if the caller is not authorized to commit
> +     * @throws IllegalStateException if no transaction is active
> +     * @throws SystemException if a system error occurred
> +     */
>      void commit() throws RollbackException, HeuristicMixedException, HeuristicRollbackException, SecurityException,
>              IllegalStateException, SystemException;
>
> +    /**
> +     * Rolls back the transaction associated with the current thread.
> +     *
> +     * @throws IllegalStateException if no transaction is active
> +     * @throws SecurityException if the caller is not authorized to roll back
> +     * @throws SystemException if a system error occurred
> +     */
>      void rollback() throws IllegalStateException, SecurityException, SystemException;
>
> +    /**
> +     * Marks the current transaction so that the only valid outcome is a rollback.
> +     *
> +     * @throws IllegalStateException if no transaction is active
> +     * @throws SystemException if a system error occurred
> +     */
>      void setRollbackOnly() throws IllegalStateException, SystemException;
>
> +    /**
> +     * Returns the status of the transaction associated with the current thread.
> +     *
> +     * @return the transaction status, one of the {@link Status} constants
> +     * @throws SystemException if a system error occurred
> +     */
>      int getStatus() throws SystemException;
>
> +    /**
> +     * Sets the default transaction timeout.
> +     *
> +     * @param seconds the timeout value in seconds
> +     * @throws SystemException if a system error occurred
> +     */
>      void setTransactionTimeout(int seconds) throws SystemException;
>  }
> diff --git a/java/jakarta/websocket/ClientEndpoint.java b/java/jakarta/websocket/ClientEndpoint.java
> index acaa160cc8..6cfa8cbaa6 100644
> --- a/java/jakarta/websocket/ClientEndpoint.java
> +++ b/java/jakarta/websocket/ClientEndpoint.java
> @@ -23,14 +23,39 @@ import java.lang.annotation.Target;
>
>  import jakarta.websocket.ClientEndpointConfig.Configurator;
>
> +/**
> + * Annotates a class as a WebSocket client endpoint. The annotation provides configuration
> + * information about the endpoint such as subprotocols, encoders, decoders, and configurator.
> + */
>  @Retention(RetentionPolicy.RUNTIME)
>  @Target(ElementType.TYPE)
>  public @interface ClientEndpoint {
> +
> +    /**
> +     * The sub-protocols that this client endpoint supports, in order of preference.
> +     *
> +     * @return The list of preferred sub-protocols
> +     */
>      String[] subprotocols() default {};
>
> +    /**
> +     * The decoder classes that this client endpoint uses.
> +     *
> +     * @return The list of decoder classes
> +     */
>      Class<? extends Decoder>[] decoders() default {};
>
> +    /**
> +     * The encoder classes that this client endpoint uses.
> +     *
> +     * @return The list of encoder classes
> +     */
>      Class<? extends Encoder>[] encoders() default {};
>
> +    /**
> +     * The configurator class used to customize the WebSocket handshake.
> +     *
> +     * @return The configurator class
> +     */
>      Class<? extends Configurator> configurator() default Configurator.class;
>  }
> diff --git a/java/jakarta/websocket/ClientEndpointConfig.java b/java/jakarta/websocket/ClientEndpointConfig.java
> index 2af1f41575..05216b11e9 100644
> --- a/java/jakarta/websocket/ClientEndpointConfig.java
> +++ b/java/jakarta/websocket/ClientEndpointConfig.java
> @@ -22,22 +22,53 @@ import java.util.Map;
>
>  import javax.net.ssl.SSLContext;
>
> +/**
> + * Provides configuration information for WebSocket client endpoints.
> + */
>  public interface ClientEndpointConfig extends EndpointConfig {
>
> +    /**
> +     * Returns the list of sub-protocols that this client endpoint supports, in order of preference.
> +     *
> +     * @return The list of preferred sub-protocols
> +     */
>      List<String> getPreferredSubprotocols();
>
> +    /**
> +     * Returns the list of extensions that this client endpoint supports.
> +     *
> +     * @return The list of supported extensions
> +     */
>      List<Extension> getExtensions();
>
> +    /**
> +     * Returns the SSL context to use for secure WebSocket connections.
> +     *
> +     * @return The SSL context, or {@code null} if no custom SSL context is configured
> +     */
>      SSLContext getSSLContext();
>
> +    /**
> +     * Returns the configurator used to customize the WebSocket handshake.
> +     *
> +     * @return The configurator for this client endpoint
> +     */
>      Configurator getConfigurator();
>
> +    /**
> +     * Builder for creating {@link ClientEndpointConfig} instances.
> +     */
>      final class Builder {
>
>          private static final Configurator DEFAULT_CONFIGURATOR = new Configurator() {
>          };
>
>
> +        /**
> +         * Creates a new {@link Builder} instance for building a {@link ClientEndpointConfig}.
> +         *
> +         * @return A new builder instance
> +         */
>          public static Builder create() {
>              return new Builder();
>          }
> @@ -54,12 +85,23 @@ public interface ClientEndpointConfig extends EndpointConfig {
>          private List<Class<? extends Decoder>> decoders = Collections.emptyList();
>          private SSLContext sslContext = null;
>
> +        /**
> +         * Builds and returns a {@link ClientEndpointConfig} with the configured settings.
> +         *
> +         * @return The configured client endpoint configuration
> +         */
>          public ClientEndpointConfig build() {
>              return new DefaultClientEndpointConfig(preferredSubprotocols, extensions, encoders, decoders, sslContext,
>                      configurator);
>          }
>
>
> +        /**
> +         * Sets the configurator to use for the WebSocket handshake.
> +         *
> +         * @param configurator The configurator, or {@code null} to use the default
> +         * @return This builder instance
> +         */
>          public Builder configurator(Configurator configurator) {
>              if (configurator == null) {
>                  this.configurator = DEFAULT_CONFIGURATOR;
> @@ -70,6 +112,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
>          }
>
>
> +        /**
> +         * Sets the list of preferred sub-protocols for the WebSocket connection.
> +         *
> +         * @param preferredSubprotocols The list of sub-protocols in order of preference
> +         * @return This builder instance
> +         */
>          public Builder preferredSubprotocols(List<String> preferredSubprotocols) {
>              if (preferredSubprotocols == null || preferredSubprotocols.isEmpty()) {
>                  this.preferredSubprotocols = Collections.emptyList();
> @@ -80,6 +128,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
>          }
>
>
> +        /**
> +         * Sets the list of extensions to use for the WebSocket connection.
> +         *
> +         * @param extensions The list of extensions
> +         * @return This builder instance
> +         */
>          public Builder extensions(List<Extension> extensions) {
>              if (extensions == null || extensions.isEmpty()) {
>                  this.extensions = Collections.emptyList();
> @@ -90,6 +144,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
>          }
>
>
> +        /**
> +         * Sets the list of encoder classes to use for the WebSocket connection.
> +         *
> +         * @param encoders The list of encoder classes
> +         * @return This builder instance
> +         */
>          public Builder encoders(List<Class<? extends Encoder>> encoders) {
>              if (encoders == null || encoders.isEmpty()) {
>                  this.encoders = Collections.emptyList();
> @@ -100,6 +160,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
>          }
>
>
> +        /**
> +         * Sets the list of decoder classes to use for the WebSocket connection.
> +         *
> +         * @param decoders The list of decoder classes
> +         * @return This builder instance
> +         */
>          public Builder decoders(List<Class<? extends Decoder>> decoders) {
>              if (decoders == null || decoders.isEmpty()) {
>                  this.decoders = Collections.emptyList();
> @@ -110,6 +176,12 @@ public interface ClientEndpointConfig extends EndpointConfig {
>          }
>
>
> +        /**
> +         * Sets the SSL context to use for secure WebSocket connections.
> +         *
> +         * @param sslContext The SSL context, or {@code null} for default SSL behavior
> +         * @return This builder instance
> +         */
>          public Builder sslContext(SSLContext sslContext) {
>              this.sslContext = sslContext;
>              return this;
> @@ -117,8 +189,18 @@ public interface ClientEndpointConfig extends EndpointConfig {
>      }
>
>
> +    /**
> +     * Provides a mechanism to customize the WebSocket handshake for client endpoints.
> +     * Applications may subclass this to inspect or modify the handshake.
> +     */
>      class Configurator {
>
> +        /**
> +         * Creates a new instance of the default Configurator.
> +         */
> +        public Configurator() {
> +        }
> +
>          /**
>           * Provides the client with a mechanism to inspect and/or modify the headers that are sent to the server to
>           * start the WebSocket handshake.
> diff --git a/java/jakarta/websocket/CloseReason.java b/java/jakarta/websocket/CloseReason.java
> index b7aef11305..7108dc6784 100644
> --- a/java/jakarta/websocket/CloseReason.java
> +++ b/java/jakarta/websocket/CloseReason.java
> @@ -16,20 +16,40 @@
>   */
>  package jakarta.websocket;
>
> +/**
> + * Represents the reason for the closure of a WebSocket connection, including a close code
> + * and an optional reason phrase.
> + */
>  public class CloseReason {
>
>      private final CloseCode closeCode;
>      private final String reasonPhrase;
>
> +    /**
> +     * Creates a new CloseReason with the given close code and reason phrase.
> +     *
> +     * @param closeCode    The close code
> +     * @param reasonPhrase The reason phrase explaining the closure
> +     */
>      public CloseReason(CloseReason.CloseCode closeCode, String reasonPhrase) {
>          this.closeCode = closeCode;
>          this.reasonPhrase = reasonPhrase;
>      }
>
> +    /**
> +     * Returns the close code.
> +     *
> +     * @return The close code
> +     */
>      public CloseCode getCloseCode() {
>          return closeCode;
>      }
>
> +    /**
> +     * Returns the reason phrase.
> +     *
> +     * @return The reason phrase
> +     */
>      public String getReasonPhrase() {
>          return reasonPhrase;
>      }
> @@ -39,34 +59,115 @@ public class CloseReason {
>          return "CloseReason: code [" + closeCode.getCode() + "], reason [" + reasonPhrase + "]";
>      }
>
> +    /**
> +     * Represents a WebSocket close code.
> +     */
>      public interface CloseCode {
> +        /**
> +         * Returns the numeric value of the close code.
> +         *
> +         * @return The numeric close code value
> +         */
>          int getCode();
>      }
>
> +    /**
> +     * Standard WebSocket close codes as defined by RFC 6455 and related specifications.
> +     */
>      public enum CloseCodes implements CloseReason.CloseCode {
>
> +        /**
> +         * Indicates a normal closure, meaning that the purpose for which the connection was
> +         * established has been fulfilled.
> +         */
>          NORMAL_CLOSURE(1000),
> +        /**
> +         * Indicates that the endpoint is going away, either because the browser is navigating
> +         * away from the page, or because the server is shutting down.
> +         */
>          GOING_AWAY(1001),
> +        /**
> +         * Indicates that the endpoint is terminating the connection due to a protocol error.
> +         */
>          PROTOCOL_ERROR(1002),
> +        /**
> +         * Indicates that the endpoint is terminating the connection because it has received a
> +         * type of data it cannot accept.
> +         */
>          CANNOT_ACCEPT(1003),
> +        /**
> +         * Reserved. The specific meaning might be defined in the future.
> +         */
>          RESERVED(1004),
> +        /**
> +         * Indicates that no status code was included in the closing frame. This value is
> +         * reserved and must not be set as a status code in a Close control frame.
> +         */
>          NO_STATUS_CODE(1005),
> +        /**
> +         * Indicates that the connection was closed abnormally without receiving a close frame.
> +         * This value is reserved and must not be set as a status code in a Close control frame.
> +         */
>          CLOSED_ABNORMALLY(1006),
> +        /**
> +         * Indicates that the endpoint is terminating the connection because it has received a
> +         * message that contains data that is not consistent with the type of the message.
> +         */
>          NOT_CONSISTENT(1007),
> +        /**
> +         * Indicates that the endpoint is terminating the connection because it has received a
> +         * message that violates its policy.
> +         */
>          VIOLATED_POLICY(1008),
> +        /**
> +         * Indicates that the endpoint is terminating the connection because it has received a
> +         * message that is too big to process.
> +         */
>          TOO_BIG(1009),
> +        /**
> +         * Indicates that the client is terminating the connection because it expected the
> +         * server to negotiate one or more extension, but the server didn't return them in the
> +         * handshake response.
> +         */
>          NO_EXTENSION(1010),
> +        /**
> +         * Indicates that the server is terminating the connection because it encountered an
> +         * unexpected condition that prevented it from fulfilling the request.
> +         */
>          UNEXPECTED_CONDITION(1011),
> +        /**
> +         * Indicates that the server is restarting. A client may choose to reconnect.
> +         */
>          SERVICE_RESTART(1012),
> +        /**
> +         * Indicates that the server is experiencing a temporary condition and the client should
> +         * try to connect again later.
> +         */
>          TRY_AGAIN_LATER(1013),
> +        /**
> +         * Indicates that the connection was closed due to a failure to perform a TLS handshake.
> +         * This value is reserved and must not be set as a status code in a Close control frame.
> +         */
>          TLS_HANDSHAKE_FAILURE(1015);
>
>          private final int code;
>
> +        /**
> +         * Creates a close code with the given numeric value.
> +         *
> +         * @param code The numeric close code value
> +         */
>          CloseCodes(int code) {
>              this.code = code;
>          }
>
> +        /**
> +         * Returns the {@link CloseCode} for the given numeric code value.
> +         *
> +         * @param code The numeric close code value
> +         * @return The corresponding {@link CloseCode}
> +         * @throws IllegalArgumentException if the code is not a valid close code
> +         */
>          public static CloseCode getCloseCode(final int code) {
>              if (code > 2999 && code < 5000) {
>                  return () -> code;
> @@ -91,6 +192,11 @@ public class CloseReason {
>              };
>          }
>
> +        /**
> +         * Returns the numeric value of this close code.
> +         *
> +         * @return The numeric close code value
> +         */
>          @Override
>          public int getCode() {
>              return code;
> diff --git a/java/jakarta/websocket/ContainerProvider.java b/java/jakarta/websocket/ContainerProvider.java
> index 56381d0dde..f79f7f8ed3 100644
> --- a/java/jakarta/websocket/ContainerProvider.java
> +++ b/java/jakarta/websocket/ContainerProvider.java
> @@ -24,6 +24,12 @@ import java.util.ServiceLoader;
>   */
>  public abstract class ContainerProvider {
>
> +    /**
> +     * Creates a new ContainerProvider instance.
> +     */
> +    protected ContainerProvider() {
> +    }
> +
>      private static final String DEFAULT_PROVIDER_CLASS_NAME = "org.apache.tomcat.websocket.WsWebSocketContainer";
>
>      /**
> @@ -54,5 +60,10 @@ public abstract class ContainerProvider {
>          return result;
>      }
>
> +    /**
> +     * Returns the WebSocket container provided by this provider.
> +     *
> +     * @return The WebSocket container
> +     */
>      protected abstract WebSocketContainer getContainer();
>  }
> diff --git a/java/jakarta/websocket/DecodeException.java b/java/jakarta/websocket/DecodeException.java
> index e6a9279094..d40fb4870f 100644
> --- a/java/jakarta/websocket/DecodeException.java
> +++ b/java/jakarta/websocket/DecodeException.java
> @@ -19,38 +19,83 @@ package jakarta.websocket;
>  import java.io.Serial;
>  import java.nio.ByteBuffer;
>
> +/**
> + * Exception thrown when a decoder fails to decode a WebSocket message.
> + */
>  public class DecodeException extends Exception {
>
>      @Serial
>      private static final long serialVersionUID = 1L;
>
> +    /**
> +     * The binary data that could not be decoded.
> +     */
>      private ByteBuffer bb;
> +    /**
> +     * The text data that could not be decoded.
> +     */
>      private String encodedString;
>
> +    /**
> +     * Creates a DecodeException for binary data with the specified detail message and cause.
> +     *
> +     * @param bb      The binary data that could not be decoded
> +     * @param message The detail message
> +     * @param cause   The underlying cause of the exception
> +     */
>      public DecodeException(ByteBuffer bb, String message, Throwable cause) {
>          super(message, cause);
>          this.bb = bb;
>      }
>
> +    /**
> +     * Creates a DecodeException for text data with the specified detail message and cause.
> +     *
> +     * @param encodedString The text data that could not be decoded
> +     * @param message       The detail message
> +     * @param cause         The underlying cause of the exception
> +     */
>      public DecodeException(String encodedString, String message, Throwable cause) {
>          super(message, cause);
>          this.encodedString = encodedString;
>      }
>
> +    /**
> +     * Creates a DecodeException for binary data with the specified detail message.
> +     *
> +     * @param bb      The binary data that could not be decoded
> +     * @param message The detail message
> +     */
>      public DecodeException(ByteBuffer bb, String message) {
>          super(message);
>          this.bb = bb;
>      }
>
> +    /**
> +     * Creates a DecodeException for text data with the specified detail message.
> +     *
> +     * @param encodedString The text data that could not be decoded
> +     * @param message       The detail message
> +     */
>      public DecodeException(String encodedString, String message) {
>          super(message);
>          this.encodedString = encodedString;
>      }
>
> +    /**
> +     * Returns the binary data that could not be decoded.
> +     *
> +     * @return The binary data, or {@code null} if the exception was for text data
> +     */
>      public ByteBuffer getBytes() {
>          return bb;
>      }
>
> +    /**
> +     * Returns the text data that could not be decoded.
> +     *
> +     * @return The text data, or {@code null} if the exception was for binary data
> +     */
>      public String getText() {
>          return encodedString;
>      }
> diff --git a/java/jakarta/websocket/Decoder.java b/java/jakarta/websocket/Decoder.java
> index 4f0a4e4c04..03db069e6a 100644
> --- a/java/jakarta/websocket/Decoder.java
> +++ b/java/jakarta/websocket/Decoder.java
> @@ -21,6 +21,10 @@ import java.io.InputStream;
>  import java.io.Reader;
>  import java.nio.ByteBuffer;
>
> +/**
> + * Base interface for WebSocket message decoders. Decoders convert incoming WebSocket messages
> + * from their raw form (text or binary) into application-specific objects.
> + */
>  public interface Decoder {
>
>      /**
> @@ -37,27 +41,91 @@ public interface Decoder {
>      default void destroy() {
>      }
>
> +    /**
> +     * A decoder that decodes entire binary WebSocket messages into an object of type T.
> +     *
> +     * @param <T> The type of object produced by the decoder
> +     */
>      interface Binary<T> extends Decoder {
>
> +        /**
> +         * Decodes the binary data into an object.
> +         *
> +         * @param bytes The binary data to decode
> +         * @return The decoded object
> +         * @throws DecodeException If the data cannot be decoded
> +         */
>          T decode(ByteBuffer bytes) throws DecodeException;
>
> +        /**
> +         * Determines whether this decoder can decode the given binary data.
> +         *
> +         * @param bytes The binary data to check
> +         * @return {@code true} if this decoder can decode the data
> +         */
>          boolean willDecode(ByteBuffer bytes);
>      }
>
> +    /**
> +     * A decoder that decodes entire binary WebSocket messages from an input stream into an
> +     * object of type T.
> +     *
> +     * @param <T> The type of object produced by the decoder
> +     */
>      interface BinaryStream<T> extends Decoder {
>
> +        /**
> +         * Decodes the binary data from the input stream into an object.
> +         *
> +         * @param is The input stream containing the binary data
> +         * @return The decoded object
> +         * @throws DecodeException If the data cannot be decoded
> +         * @throws IOException     If an I/O error occurs
> +         */
>          T decode(InputStream is) throws DecodeException, IOException;
>      }
>
> +    /**
> +     * A decoder that decodes entire text WebSocket messages into an object of type T.
> +     *
> +     * @param <T> The type of object produced by the decoder
> +     */
>      interface Text<T> extends Decoder {
>
> +        /**
> +         * Decodes the text data into an object.
> +         *
> +         * @param s The text data to decode
> +         * @return The decoded object
> +         * @throws DecodeException If the data cannot be decoded
> +         */
>          T decode(String s) throws DecodeException;
>
> +        /**
> +         * Determines whether this decoder can decode the given text data.
> +         *
> +         * @param s The text data to check
> +         * @return {@code true} if this decoder can decode the data
> +         */
>          boolean willDecode(String s);
>      }
>
> +    /**
> +     * A decoder that decodes entire text WebSocket messages from a reader into an object of
> +     * type T.
> +     *
> +     * @param <T> The type of object produced by the decoder
> +     */
>      interface TextStream<T> extends Decoder {
>
> +        /**
> +         * Decodes the text data from the reader into an object.
> +         *
> +         * @param reader The reader containing the text data
> +         * @return The decoded object
> +         * @throws DecodeException If the data cannot be decoded
> +         * @throws IOException     If an I/O error occurs
> +         */
>          T decode(Reader reader) throws DecodeException, IOException;
>      }
>  }
> diff --git a/java/jakarta/websocket/DeploymentException.java b/java/jakarta/websocket/DeploymentException.java
> index d12f62680b..1bc0202cbd 100644
> --- a/java/jakarta/websocket/DeploymentException.java
> +++ b/java/jakarta/websocket/DeploymentException.java
> @@ -18,15 +18,29 @@ package jakarta.websocket;
>
>  import java.io.Serial;
>
> +/**
> + * Exception thrown when a WebSocket endpoint cannot be deployed due to a configuration error.
> + */
>  public class DeploymentException extends Exception {
>
>      @Serial
>      private static final long serialVersionUID = 1L;
>
> +    /**
> +     * Creates a DeploymentException with the specified detail message.
> +     *
> +     * @param message The detail message
> +     */
>      public DeploymentException(String message) {
>          super(message);
>      }
>
> +    /**
> +     * Creates a DeploymentException with the specified detail message and cause.
> +     *
> +     * @param message The detail message
> +     * @param cause   The underlying cause of the exception
> +     */
>      public DeploymentException(String message, Throwable cause) {
>          super(message, cause);
>      }
> diff --git a/java/jakarta/websocket/EncodeException.java b/java/jakarta/websocket/EncodeException.java
> index 406b0ffee1..86b78c29d1 100644
> --- a/java/jakarta/websocket/EncodeException.java
> +++ b/java/jakarta/websocket/EncodeException.java
> @@ -18,23 +18,47 @@ package jakarta.websocket;
>
>  import java.io.Serial;
>
> +/**
> + * Exception thrown when an encoder fails to encode an object as a WebSocket message.
> + */
>  public class EncodeException extends Exception {
>
>      @Serial
>      private static final long serialVersionUID = 1L;
>
> +    /**
> +     * The object that could not be encoded.
> +     */
>      private final Object object;
>
> +    /**
> +     * Creates an EncodeException with the specified object and detail message.
> +     *
> +     * @param object  The object that could not be encoded
> +     * @param message The detail message
> +     */
>      public EncodeException(Object object, String message) {
>          super(message);
>          this.object = object;
>      }
>
> +    /**
> +     * Creates an EncodeException with the specified object, detail message, and cause.
> +     *
> +     * @param object  The object that could not be encoded
> +     * @param message The detail message
> +     * @param cause   The underlying cause of the exception
> +     */
>      public EncodeException(Object object, String message, Throwable cause) {
>          super(message, cause);
>          this.object = object;
>      }
>
> +    /**
> +     * Returns the object that could not be encoded.
> +     *
> +     * @return The object that could not be encoded
> +     */
>      public Object getObject() {
>          return this.object;
>      }
> diff --git a/java/jakarta/websocket/Encoder.java b/java/jakarta/websocket/Encoder.java
> index 808cf3d79b..a1268268dd 100644
> --- a/java/jakarta/websocket/Encoder.java
> +++ b/java/jakarta/websocket/Encoder.java
> @@ -21,6 +21,10 @@ import java.io.OutputStream;
>  import java.io.Writer;
>  import java.nio.ByteBuffer;
>
> +/**
> + * Base interface for WebSocket message encoders. Encoders convert application-specific objects
> + * into WebSocket messages in text or binary form.
> + */
>  public interface Encoder {
>
>      /**
> @@ -32,28 +36,80 @@ public interface Encoder {
>      }
>
>      /**
> -     * Destroy the decoder. The default implementation is a NO-OP.
> +     * Destroy the encoder. The default implementation is a NO-OP.
>       */
>      default void destroy() {
>      }
>
> +    /**
> +     * An encoder that encodes an object of type T into a text WebSocket message.
> +     *
> +     * @param <T> The type of object accepted by the encoder
> +     */
>      interface Text<T> extends Encoder {
>
> +        /**
> +         * Encodes the given object into a text string.
> +         *
> +         * @param object The object to encode
> +         * @return The encoded text string
> +         * @throws EncodeException If the object cannot be encoded
> +         */
>          String encode(T object) throws EncodeException;
>      }
>
> +    /**
> +     * An encoder that encodes an object of type T into a text WebSocket message written to
> +     * a {@link Writer}.
> +     *
> +     * @param <T> The type of object accepted by the encoder
> +     */
>      interface TextStream<T> extends Encoder {
>
> +        /**
> +         * Encodes the given object and writes the result to the writer.
> +         *
> +         * @param object The object to encode
> +         * @param writer The writer to write the encoded data to
> +         * @throws EncodeException If the object cannot be encoded
> +         * @throws IOException     If an I/O error occurs
> +         */
>          void encode(T object, Writer writer) throws EncodeException, IOException;
>      }
>
> +    /**
> +     * An encoder that encodes an object of type T into a binary WebSocket message.
> +     *
> +     * @param <T> The type of object accepted by the encoder
> +     */
>      interface Binary<T> extends Encoder {
>
> +        /**
> +         * Encodes the given object into a ByteBuffer.
> +         *
> +         * @param object The object to encode
> +         * @return The encoded binary data
> +         * @throws EncodeException If the object cannot be encoded
> +         */
>          ByteBuffer encode(T object) throws EncodeException;
>      }
>
> +    /**
> +     * An encoder that encodes an object of type T into a binary WebSocket message written to
> +     * an {@link OutputStream}.
> +     *
> +     * @param <T> The type of object accepted by the encoder
> +     */
>      interface BinaryStream<T> extends Encoder {
>
> +        /**
> +         * Encodes the given object and writes the result to the output stream.
> +         *
> +         * @param object The object to encode
> +         * @param os     The output stream to write the encoded data to
> +         * @throws EncodeException If the object cannot be encoded
> +         * @throws IOException     If an I/O error occurs
> +         */
>          void encode(T object, OutputStream os) throws EncodeException, IOException;
>      }
>  }
> diff --git a/java/jakarta/websocket/Endpoint.java b/java/jakarta/websocket/Endpoint.java
> index 059430d25e..a832ac9538 100644
> --- a/java/jakarta/websocket/Endpoint.java
> +++ b/java/jakarta/websocket/Endpoint.java
> @@ -16,8 +16,18 @@
>   */
>  package jakarta.websocket;
>
> +/**
> + * Base class for programmatic WebSocket endpoints. Subclasses must implement the
> + * {@link #onOpen(Session, EndpointConfig)} method to handle new connections.
> + */
>  public abstract class Endpoint {
>
> +    /**
> +     * Creates a new Endpoint instance.
> +     */
> +    public Endpoint() {
> +    }
> +
>      /**
>       * Event that is triggered when a new session starts.
>       *
> diff --git a/java/jakarta/websocket/EndpointConfig.java b/java/jakarta/websocket/EndpointConfig.java
> index ed2d423610..7e85ca55c0 100644
> --- a/java/jakarta/websocket/EndpointConfig.java
> +++ b/java/jakarta/websocket/EndpointConfig.java
> @@ -19,11 +19,30 @@ package jakarta.websocket;
>  import java.util.List;
>  import java.util.Map;
>
> +/**
> + * Provides configuration information for a WebSocket endpoint, including encoders, decoders,
> + * and user properties.
> + */
>  public interface EndpointConfig {
>
> +    /**
> +     * Returns the list of encoder classes for this endpoint.
> +     *
> +     * @return The list of encoder classes
> +     */
>      List<Class<? extends Encoder>> getEncoders();
>
> +    /**
> +     * Returns the list of decoder classes for this endpoint.
> +     *
> +     * @return The list of decoder classes
> +     */
>      List<Class<? extends Decoder>> getDecoders();
>
> +    /**
> +     * Returns a map of user properties associated with this endpoint configuration.
> +     *
> +     * @return The user properties map
> +     */
>      Map<String,Object> getUserProperties();
>  }
> diff --git a/java/jakarta/websocket/Extension.java b/java/jakarta/websocket/Extension.java
> index a4cbca8f62..61a261c307 100644
> --- a/java/jakarta/websocket/Extension.java
> +++ b/java/jakarta/websocket/Extension.java
> @@ -18,14 +18,42 @@ package jakarta.websocket;
>
>  import java.util.List;
>
> +/**
> + * Represents a WebSocket extension that can be negotiated during the handshake.
> + */
>  public interface Extension {
> +
> +    /**
> +     * Returns the name of this extension.
> +     *
> +     * @return The extension name
> +     */
>      String getName();
>
> +    /**
> +     * Returns the parameters associated with this extension.
> +     *
> +     * @return The list of extension parameters
> +     */
>      List<Parameter> getParameters();
>
> +    /**
> +     * Represents a parameter of a WebSocket extension.
> +     */
>      interface Parameter {
> +
> +        /**
> +         * Returns the name of this parameter.
> +         *
> +         * @return The parameter name
> +         */
>          String getName();
>
> +        /**
> +         * Returns the value of this parameter.
> +         *
> +         * @return The parameter value
> +         */
>          String getValue();
>      }
>  }
> diff --git a/java/jakarta/websocket/HandshakeResponse.java b/java/jakarta/websocket/HandshakeResponse.java
> index e5faf9d801..900551f880 100644
> --- a/java/jakarta/websocket/HandshakeResponse.java
> +++ b/java/jakarta/websocket/HandshakeResponse.java
> @@ -19,6 +19,9 @@ package jakarta.websocket;
>  import java.util.List;
>  import java.util.Map;
>
> +/**
> + * Represents the HTTP response returned by the server during a WebSocket handshake.
> + */
>  public interface HandshakeResponse {
>
>      /**
> @@ -26,5 +29,10 @@ public interface HandshakeResponse {
>       */
>      String SEC_WEBSOCKET_ACCEPT = "Sec-WebSocket-Accept";
>
> +    /**
> +     * Returns the HTTP headers from the handshake response.
> +     *
> +     * @return The HTTP headers
> +     */
>      Map<String,List<String>> getHeaders();
>  }
> diff --git a/java/jakarta/websocket/MessageHandler.java b/java/jakarta/websocket/MessageHandler.java
> index 748dd76776..ace7c96702 100644
> --- a/java/jakarta/websocket/MessageHandler.java
> +++ b/java/jakarta/websocket/MessageHandler.java
> @@ -16,8 +16,18 @@
>   */
>  package jakarta.websocket;
>
> +/**
> + * Base interface for WebSocket message handlers. Use {@link Whole} for handling complete
> + * messages and {@link Partial} for handling messages that may arrive in fragments.
> + */
>  public interface MessageHandler {
>
> +    /**
> +     * A message handler that receives partial (fragmented) messages. The handler is called
> +     * multiple times for a single WebSocket message if it arrives in fragments.
> +     *
> +     * @param <T> The type of message data
> +     */
>      interface Partial<T> extends MessageHandler {
>
>          /**
> @@ -29,6 +39,12 @@ public interface MessageHandler {
>          void onMessage(T messagePart, boolean last);
>      }
>
> +   /**
> +     * A message handler that receives whole (complete) messages. The handler is called once
> +     * per WebSocket message.
> +     *
> +     * @param <T> The type of message data
> +     */
>      interface Whole<T> extends MessageHandler {
>
>          /**
> diff --git a/java/jakarta/websocket/OnClose.java b/java/jakarta/websocket/OnClose.java
> index 31291165bc..8c071d1f85 100644
> --- a/java/jakarta/websocket/OnClose.java
> +++ b/java/jakarta/websocket/OnClose.java
> @@ -21,6 +21,10 @@ import java.lang.annotation.Retention;
>  import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
> +/**
> + * Annotates a method on a POJO endpoint to handle the close event. The annotated method
> + * will be called when the WebSocket session is closed.
> + */
>  @Retention(RetentionPolicy.RUNTIME)
>  @Target(ElementType.METHOD)
>  public @interface OnClose {
> diff --git a/java/jakarta/websocket/OnError.java b/java/jakarta/websocket/OnError.java
> index a09a5bde28..cba6abd9ac 100644
> --- a/java/jakarta/websocket/OnError.java
> +++ b/java/jakarta/websocket/OnError.java
> @@ -21,6 +21,10 @@ import java.lang.annotation.Retention;
>  import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
> +/**
> + * Annotates a method on a POJO endpoint to handle error events. The annotated method
> + * will be called when an error occurs on the WebSocket session.
> + */
>  @Retention(RetentionPolicy.RUNTIME)
>  @Target(ElementType.METHOD)
>  public @interface OnError {
> diff --git a/java/jakarta/websocket/OnMessage.java b/java/jakarta/websocket/OnMessage.java
> index 34cfcfa18e..49d95b8c74 100644
> --- a/java/jakarta/websocket/OnMessage.java
> +++ b/java/jakarta/websocket/OnMessage.java
> @@ -21,8 +21,19 @@ import java.lang.annotation.Retention;
>  import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
> +/**
> + * Annotates a method on a POJO endpoint to handle incoming WebSocket messages. The annotated
> + * method will be called when a message is received.
> + */
>  @Retention(RetentionPolicy.RUNTIME)
>  @Target(ElementType.METHOD)
>  public @interface OnMessage {
> +
> +    /**
> +     * The maximum message size in bytes that this handler will accept. Messages larger than
> +     * this size will be discarded. A value of -1 indicates no limit.
> +     *
> +     * @return The maximum message size in bytes
> +     */
>      long maxMessageSize() default -1;
>  }
> diff --git a/java/jakarta/websocket/OnOpen.java b/java/jakarta/websocket/OnOpen.java
> index 26b8e9d1e0..48f98d7bbd 100644
> --- a/java/jakarta/websocket/OnOpen.java
> +++ b/java/jakarta/websocket/OnOpen.java
> @@ -21,6 +21,10 @@ import java.lang.annotation.Retention;
>  import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
> +/**
> + * Annotates a method on a POJO endpoint to handle the open event. The annotated method
> + * will be called when a new WebSocket session is established.
> + */
>  @Retention(RetentionPolicy.RUNTIME)
>  @Target(ElementType.METHOD)
>  public @interface OnOpen {
> diff --git a/java/jakarta/websocket/RemoteEndpoint.java b/java/jakarta/websocket/RemoteEndpoint.java
> index 9826d98cc0..a485581c65 100644
> --- a/java/jakarta/websocket/RemoteEndpoint.java
> +++ b/java/jakarta/websocket/RemoteEndpoint.java
> @@ -23,8 +23,15 @@ import java.nio.ByteBuffer;
>  import java.util.concurrent.Future;
>
>
> +/**
> + * Interface for sending messages to the remote endpoint of a WebSocket session.
> + * Provides both synchronous ({@link Basic}) and asynchronous ({@link Async}) sending capabilities.
> + */
>  public interface RemoteEndpoint {
>
> +    /**
> +     * Asynchronous API for sending messages to the remote endpoint.
> +     */
>      interface Async extends RemoteEndpoint {
>
>          /**
> @@ -109,6 +116,9 @@ public interface RemoteEndpoint {
>
>      }
>
> +   /**
> +     * Synchronous (blocking) API for sending messages to the remote endpoint.
> +     */
>      interface Basic extends RemoteEndpoint {
>
>          /**
> @@ -155,8 +165,20 @@ public interface RemoteEndpoint {
>           */
>          void sendBinary(ByteBuffer partialByte, boolean isLast) throws IOException;
>
> +        /**
> +         * Returns an {@link OutputStream} for sending a binary message to the remote endpoint.
> +         *
> +         * @return An output stream for sending binary data
> +         * @throws IOException if an I/O error occurs
> +         */
>          OutputStream getSendStream() throws IOException;
>
> +        /**
> +         * Returns a {@link Writer} for sending a text message to the remote endpoint.
> +         *
> +         * @return A writer for sending text data
> +         * @throws IOException if an I/O error occurs
> +         */
>          Writer getSendWriter() throws IOException;
>
>          /**
> diff --git a/java/jakarta/websocket/SendHandler.java b/java/jakarta/websocket/SendHandler.java
> index 9e8317c5b5..ee34f7a25c 100644
> --- a/java/jakarta/websocket/SendHandler.java
> +++ b/java/jakarta/websocket/SendHandler.java
> @@ -16,7 +16,15 @@
>   */
>  package jakarta.websocket;
>
> +/**
> + * Callback interface for handling the result of an asynchronous WebSocket message send operation.
> + */
>  public interface SendHandler {
>
> +    /**
> +     * Called when the asynchronous send operation completes.
> +     *
> +     * @param result The result of the send operation
> +     */
>      void onResult(SendResult result);
>  }
> diff --git a/java/jakarta/websocket/SendResult.java b/java/jakarta/websocket/SendResult.java
> index f506c881af..b7a6842f37 100644
> --- a/java/jakarta/websocket/SendResult.java
> +++ b/java/jakarta/websocket/SendResult.java
> @@ -16,6 +16,9 @@
>   */
>  package jakarta.websocket;
>
> +/**
> + * Represents the result of an asynchronous WebSocket message send operation.
> + */
>  public final class SendResult {
>      private final Session session;
>      private final Throwable exception;
> @@ -66,10 +69,21 @@ public final class SendResult {
>          this(null, null);
>      }
>
> +    /**
> +     * Returns the exception that occurred during the send operation, or {@code null} if the
> +     * operation was successful.
> +     *
> +     * @return The exception, or {@code null} if successful
> +     */
>      public Throwable getException() {
>          return exception;
>      }
>
> +    /**
> +     * Returns whether the send operation was successful.
> +     *
> +     * @return {@code true} if the send was successful, {@code false} otherwise
> +     */
>      public boolean isOK() {
>          return ok;
>      }
> diff --git a/java/jakarta/websocket/Session.java b/java/jakarta/websocket/Session.java
> index 21e20ea086..eb439795a4 100644
> --- a/java/jakarta/websocket/Session.java
> +++ b/java/jakarta/websocket/Session.java
> @@ -24,6 +24,11 @@ import java.util.List;
>  import java.util.Map;
>  import java.util.Set;
>
> +/**
> + * Represents a WebSocket session, which is the WebSocket connection between a client and a server.
> + * A session is created when a WebSocket connection is established and is used to send and receive
> + * messages.
> + */
>  public interface Session extends Closeable {
>
>      /**
> @@ -46,18 +51,54 @@ public interface Session extends Closeable {
>       */
>      void addMessageHandler(MessageHandler handler) throws IllegalStateException;
>
> +    /**
> +     * Returns the set of message handlers currently registered on this session.
> +     *
> +     * @return The set of registered message handlers
> +     */
>      Set<MessageHandler> getMessageHandlers();
>
> +    /**
> +     * Removes the specified message handler from this session.
> +     *
> +     * @param listener The message handler to remove
> +     */
>      void removeMessageHandler(MessageHandler listener);
>
> +    /**
> +     * Returns the version of the WebSocket protocol in use for this session.
> +     *
> +     * @return The protocol version
> +     */
>      String getProtocolVersion();
>
> +    /**
> +     * Returns the sub-protocol negotiated for this session, or {@code null} if no sub-protocol
> +     * was negotiated.
> +     *
> +     * @return The negotiated sub-protocol
> +     */
>      String getNegotiatedSubprotocol();
>
> +    /**
> +     * Returns the list of extensions negotiated for this session.
> +     *
> +     * @return The list of negotiated extensions
> +     */
>      List<Extension> getNegotiatedExtensions();
>
> +    /**
> +     * Returns whether this session is using a secure connection (wss://).
> +     *
> +     * @return {@code true} if the connection is secure
> +     */
>      boolean isSecure();
>
> +    /**
> +     * Returns whether this session is currently open.
> +     *
> +     * @return {@code true} if the session is open
> +     */
>      boolean isOpen();
>
>      /**
> @@ -104,8 +145,19 @@ public interface Session extends Closeable {
>       */
>      int getMaxTextMessageBufferSize();
>
> +    /**
> +     * Returns the asynchronous remote endpoint for this session, used for non-blocking message
> +     * sending.
> +     *
> +     * @return The asynchronous remote endpoint
> +     */
>      RemoteEndpoint.Async getAsyncRemote();
>
> +    /**
> +     * Returns the synchronous remote endpoint for this session, used for blocking message sending.
> +     *
> +     * @return The synchronous remote endpoint
> +     */
>      RemoteEndpoint.Basic getBasicRemote();
>
>      /**
> @@ -135,16 +187,47 @@ public interface Session extends Closeable {
>       */
>      void close(CloseReason closeReason) throws IOException;
>
> +    /**
> +     * Returns the URI of the request that initiated this WebSocket session.
> +     *
> +     * @return The request URI
> +     */
>      URI getRequestURI();
>
> +    /**
> +     * Returns the query parameters from the request that initiated this WebSocket session.
> +     *
> +     * @return The query parameter map
> +     */
>      Map<String,List<String>> getRequestParameterMap();
>
> +    /**
> +     * Returns the query string from the request that initiated this WebSocket session.
> +     *
> +     * @return The query string
> +     */
>      String getQueryString();
>
> +    /**
> +     * Returns the path parameters extracted from the request URI using the endpoint's URI template.
> +     *
> +     * @return The path parameter map
> +     */
>      Map<String,String> getPathParameters();
>
> +    /**
> +     * Returns a map of user properties associated with this session.
> +     *
> +     * @return The user properties map
> +     */
>      Map<String,Object> getUserProperties();
>
> +    /**
> +     * Returns the principal of the user associated with this session, or {@code null} if the
> +     * user is not authenticated.
> +     *
> +     * @return The user principal
> +     */
>      Principal getUserPrincipal();
>
>      /**
> diff --git a/java/jakarta/websocket/SessionException.java b/java/jakarta/websocket/SessionException.java
> index d1d0f9908c..7645c73fa0 100644
> --- a/java/jakarta/websocket/SessionException.java
> +++ b/java/jakarta/websocket/SessionException.java
> @@ -18,20 +18,38 @@ package jakarta.websocket;
>
>  import java.io.Serial;
>
> +/**
> + * Exception thrown when an error occurs on a WebSocket session.
> + */
>  public class SessionException extends Exception {
>
>      @Serial
>      private static final long serialVersionUID = 1L;
>
> +    /**
> +     * The session on which the error occurred.
> +     */
>      private final Session session;
>
>
> +    /**
> +     * Creates a SessionException with the specified detail message, cause, and session.
> +     *
> +     * @param message The detail message
> +     * @param cause   The underlying cause of the exception
> +     * @param session The session on which the error occurred
> +     */
>      public SessionException(String message, Throwable cause, Session session) {
>          super(message, cause);
>          this.session = session;
>      }
>
>
> +    /**
> +     * Returns the session on which the error occurred.
> +     *
> +     * @return The session
> +     */
>      public Session getSession() {
>          return session;
>      }
> diff --git a/java/jakarta/websocket/WebSocketContainer.java b/java/jakarta/websocket/WebSocketContainer.java
> index 82ddb7ff47..7613ece7a7 100644
> --- a/java/jakarta/websocket/WebSocketContainer.java
> +++ b/java/jakarta/websocket/WebSocketContainer.java
> @@ -20,6 +20,9 @@ import java.io.IOException;
>  import java.net.URI;
>  import java.util.Set;
>
> +/**
> + * Provides the ability to create new WebSocket client connections.
> + */
>  public interface WebSocketContainer {
>
>      /**
> @@ -36,8 +39,27 @@ public interface WebSocketContainer {
>       */
>      void setAsyncSendTimeout(long timeout);
>
> +    /**
> +     * Creates a new connection to the WebSocket server endpoint.
> +     *
> +     * @param endpoint The POJO endpoint instance that will handle responses from the server
> +     * @param path     The full URL of the WebSocket endpoint to connect to
> +     * @return The WebSocket session for the connection
> +     * @throws DeploymentException If the connection cannot be established
> +     * @throws IOException         If an I/O error occurred while trying to establish the connection
> +     */
>      Session connectToServer(Object endpoint, URI path) throws DeploymentException, IOException;
>
> +    /**
> +     * Creates a new connection to the WebSocket server endpoint.
> +     *
> +     * @param annotatedEndpointClass The annotated endpoint class. An instance of this class will be
> +     *                                   created to handle responses from the server
> +     * @param path                   The full URL of the WebSocket endpoint to connect to
> +     * @return The WebSocket session for the connection
> +     * @throws DeploymentException If the connection cannot be established
> +     * @throws IOException         If an I/O error occurred while trying to establish the connection
> +     */
>      Session connectToServer(Class<?> annotatedEndpointClass, URI path) throws DeploymentException, IOException;
>
>      /**
> diff --git a/java/jakarta/websocket/server/HandshakeRequest.java b/java/jakarta/websocket/server/HandshakeRequest.java
> index 457942ed76..a17cb21545 100644
> --- a/java/jakarta/websocket/server/HandshakeRequest.java
> +++ b/java/jakarta/websocket/server/HandshakeRequest.java
> @@ -26,17 +26,51 @@ import java.util.Map;
>   */
>  public interface HandshakeRequest {
>
> +    /**
> +     * Name of the Sec-WebSocket-Key HTTP header.
> +     */
>      String SEC_WEBSOCKET_KEY = "Sec-WebSocket-Key";
> +    /**
> +     * Name of the Sec-WebSocket-Protocol HTTP header.
> +     */
>      String SEC_WEBSOCKET_PROTOCOL = "Sec-WebSocket-Protocol";
> +    /**
> +     * Name of the Sec-WebSocket-Version HTTP header.
> +     */
>      String SEC_WEBSOCKET_VERSION = "Sec-WebSocket-Version";
> +    /**
> +     * Name of the Sec-WebSocket-Extensions HTTP header.
> +     */
>      String SEC_WEBSOCKET_EXTENSIONS = "Sec-WebSocket-Extensions";
>
> +    /**
> +     * Returns the HTTP headers from the handshake request.
> +     *
> +     * @return The HTTP headers
> +     */
>      Map<String,List<String>> getHeaders();
>
> +    /**
> +     * Returns the principal of the user associated with this request, or {@code null} if the
> +     * user is not authenticated.
> +     *
> +     * @return The user principal
> +     */
>      Principal getUserPrincipal();
>
> +    /**
> +     * Returns the URI of the handshake request.
> +     *
> +     * @return The request URI
> +     */
>      URI getRequestURI();
>
> +    /**
> +     * Returns whether the user associated with this request is in the given role.
> +     *
> +     * @param role The role to check
> +     * @return {@code true} if the user is in the specified role
> +     */
>      boolean isUserInRole(String role);
>
>      /**
> @@ -47,7 +81,17 @@ public interface HandshakeRequest {
>       */
>      Object getHttpSession();
>
> +    /**
> +     * Returns the query parameters from the handshake request.
> +     *
> +     * @return The query parameter map
> +     */
>      Map<String,List<String>> getParameterMap();
>
> +    /**
> +     * Returns the query string from the handshake request.
> +     *
> +     * @return The query string
> +     */
>      String getQueryString();
>  }
> diff --git a/java/jakarta/websocket/server/PathParam.java b/java/jakarta/websocket/server/PathParam.java
> index 22293b3dda..b86dbbf85b 100644
> --- a/java/jakarta/websocket/server/PathParam.java
> +++ b/java/jakarta/websocket/server/PathParam.java
> @@ -28,5 +28,11 @@ import java.lang.annotation.Target;
>  @Retention(RetentionPolicy.RUNTIME)
>  @Target(ElementType.PARAMETER)
>  public @interface PathParam {
> +
> +    /**
> +     * The name of the path parameter from the URI template.
> +     *
> +     * @return The path parameter name
> +     */
>      String value();
>  }
> diff --git a/java/jakarta/websocket/server/ServerContainer.java b/java/jakarta/websocket/server/ServerContainer.java
> index 82b92dc7bd..e6c4f68c91 100644
> --- a/java/jakarta/websocket/server/ServerContainer.java
> +++ b/java/jakarta/websocket/server/ServerContainer.java
> @@ -26,8 +26,21 @@ import jakarta.websocket.WebSocketContainer;
>   * Provides the ability to deploy endpoints programmatically.
>   */
>  public interface ServerContainer extends WebSocketContainer {
> +    /**
> +     * Deploys the given endpoint class. The class must be annotated with
> +     * {@link jakarta.websocket.server.ServerEndpoint} or extend {@link jakarta.websocket.Endpoint}.
> +     *
> +     * @param clazz The endpoint class to deploy
> +     * @throws DeploymentException If the endpoint cannot be deployed
> +     */
>      void addEndpoint(Class<?> clazz) throws DeploymentException;
>
> +    /**
> +     * Deploys the endpoint configured by the given {@link ServerEndpointConfig}.
> +     *
> +     * @param sec The server endpoint configuration
> +     * @throws DeploymentException If the endpoint cannot be deployed
> +     */
>      void addEndpoint(ServerEndpointConfig sec) throws DeploymentException;
>
>      /**
> diff --git a/java/jakarta/websocket/server/ServerEndpoint.java b/java/jakarta/websocket/server/ServerEndpoint.java
> index b29ebec134..f0efc31112 100644
> --- a/java/jakarta/websocket/server/ServerEndpoint.java
> +++ b/java/jakarta/websocket/server/ServerEndpoint.java
> @@ -24,6 +24,11 @@ import java.lang.annotation.Target;
>  import jakarta.websocket.Decoder;
>  import jakarta.websocket.Encoder;
>
> +/**
> + * Annotates a class as a WebSocket server endpoint. The annotation provides configuration
> + * information about the endpoint such as the URI path, subprotocols, encoders, decoders,
> + * and configurator.
> + */
>  @Retention(RetentionPolicy.RUNTIME)
>  @Target(ElementType.TYPE)
>  public @interface ServerEndpoint {
> @@ -35,11 +40,31 @@ public @interface ServerEndpoint {
>       */
>      String value();
>
> +    /**
> +     * The sub-protocols that this server endpoint supports.
> +     *
> +     * @return The list of supported sub-protocols
> +     */
>      String[] subprotocols() default {};
>
> +    /**
> +     * The decoder classes that this server endpoint uses.
> +     *
> +     * @return The list of decoder classes
> +     */
>      Class<? extends Decoder>[] decoders() default {};
>
> +    /**
> +     * The encoder classes that this server endpoint uses.
> +     *
> +     * @return The list of encoder classes
> +     */
>      Class<? extends Encoder>[] encoders() default {};
>
> +    /**
> +     * The configurator class used to customize the WebSocket handshake.
> +     *
> +     * @return The configurator class
> +     */
>      Class<? extends ServerEndpointConfig.Configurator> configurator() default ServerEndpointConfig.Configurator.class;
>  }
> diff --git a/java/jakarta/websocket/server/ServerEndpointConfig.java b/java/jakarta/websocket/server/ServerEndpointConfig.java
> index e72a879608..caf697a61b 100644
> --- a/java/jakarta/websocket/server/ServerEndpointConfig.java
> +++ b/java/jakarta/websocket/server/ServerEndpointConfig.java
> @@ -33,6 +33,11 @@ import jakarta.websocket.HandshakeResponse;
>   */
>  public interface ServerEndpointConfig extends EndpointConfig {
>
> +    /**
> +     * Returns the class of the endpoint.
> +     *
> +     * @return The endpoint class
> +     */
>      Class<?> getEndpointClass();
>
>      /**
> @@ -43,15 +48,40 @@ public interface ServerEndpointConfig extends EndpointConfig {
>       */
>      String getPath();
>
> +    /**
> +     * Returns the list of sub-protocols supported by this endpoint.
> +     *
> +     * @return The list of supported sub-protocols
> +     */
>      List<String> getSubprotocols();
>
> +    /**
> +     * Returns the list of extensions supported by this endpoint.
> +     *
> +     * @return The list of supported extensions
> +     */
>      List<Extension> getExtensions();
>
> +    /**
> +     * Returns the configurator for this server endpoint.
> +     *
> +     * @return The configurator
> +     */
>      Configurator getConfigurator();
>
>
> +    /**
> +     * Builder for creating {@link ServerEndpointConfig} instances.
> +     */
>      final class Builder {
>
> +        /**
> +         * Creates a new builder for the given endpoint class and path.
> +         *
> +         * @param endpointClass The endpoint class
> +         * @param path          The path at which the endpoint will be registered
> +         * @return A new builder instance
> +         */
>          public static Builder create(Class<?> endpointClass, String path) {
>              return new Builder(endpointClass, path);
>          }
> @@ -83,12 +113,23 @@ public interface ServerEndpointConfig extends EndpointConfig {
>              this.path = path;
>          }
>
> + /**
> +         * Builds and returns a {@link ServerEndpointConfig} with the configured settings.
> +         *
> +         * @return The configured server endpoint configuration
> +         */
>          public ServerEndpointConfig build() {
>              return new DefaultServerEndpointConfig(endpointClass, path, subprotocols, extensions, encoders, decoders,
>                      configurator);
>          }
>
>
> +        /**
> +         * Sets the list of encoder classes to use for the WebSocket connection.
> +         *
> +         * @param encoders The list of encoder classes
> +         * @return This builder instance
> +         */
>          public Builder encoders(List<Class<? extends Encoder>> encoders) {
>              if (encoders == null || encoders.isEmpty()) {
>                  this.encoders = Collections.emptyList();
> @@ -99,6 +140,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
>          }
>
>
> +        /**
> +         * Sets the list of decoder classes to use for the WebSocket connection.
> +         *
> +         * @param decoders The list of decoder classes
> +         * @return This builder instance
> +         */
>          public Builder decoders(List<Class<? extends Decoder>> decoders) {
>              if (decoders == null || decoders.isEmpty()) {
>                  this.decoders = Collections.emptyList();
> @@ -109,6 +156,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
>          }
>
>
> +        /**
> +         * Sets the list of sub-protocols supported by the endpoint.
> +         *
> +         * @param subprotocols The list of sub-protocols
> +         * @return This builder instance
> +         */
>          public Builder subprotocols(List<String> subprotocols) {
>              if (subprotocols == null || subprotocols.isEmpty()) {
>                  this.subprotocols = Collections.emptyList();
> @@ -119,6 +172,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
>          }
>
>
> +        /**
> +         * Sets the list of extensions supported by the endpoint.
> +         *
> +         * @param extensions The list of extensions
> +         * @return This builder instance
> +         */
>          public Builder extensions(List<Extension> extensions) {
>              if (extensions == null || extensions.isEmpty()) {
>                  this.extensions = Collections.emptyList();
> @@ -129,6 +188,12 @@ public interface ServerEndpointConfig extends EndpointConfig {
>          }
>
>
> +        /**
> +         * Sets the configurator to use for the WebSocket handshake.
> +         *
> +         * @param serverEndpointConfigurator The configurator, or {@code null} to use the default
> +         * @return This builder instance
> +         */
>          public Builder configurator(Configurator serverEndpointConfigurator) {
>              if (serverEndpointConfigurator == null) {
>                  this.configurator = Configurator.fetchContainerDefaultConfigurator();
> @@ -140,8 +205,18 @@ public interface ServerEndpointConfig extends EndpointConfig {
>      }
>
>
> +    /**
> +     * Provides a mechanism to customize the WebSocket handshake for server endpoints.
> +     * Applications may subclass this to inspect or modify the handshake.
> +     */
>      class Configurator {
>
> +        /**
> +         * Creates a new instance of the Configurator.
> +         */
> +        public Configurator() {
> +        }
> +
>          private static volatile Configurator defaultImpl = null;
>          private static final Object defaultImplLock = new Object();
>
> @@ -195,22 +270,61 @@ public interface ServerEndpointConfig extends EndpointConfig {
>              return fetchContainerDefaultConfigurator();
>          }
>
> +        /**
> +         * Determines the sub-protocol to use for the WebSocket connection by comparing the
> +         * supported and requested sub-protocols.
> +         *
> +         * @param supported The list of sub-protocols supported by the endpoint
> +         * @param requested The list of sub-protocols requested by the client
> +         * @return The negotiated sub-protocol, or {@code null} if none matches
> +         */
>          public String getNegotiatedSubprotocol(List<String> supported, List<String> requested) {
>              return fetchContainerDefaultConfigurator().getNegotiatedSubprotocol(supported, requested);
>          }
>
> +        /**
> +         * Determines the extensions to use for the WebSocket connection by comparing the
> +         * installed and requested extensions.
> +         *
> +         * @param installed The list of extensions installed on the server
> +         * @param requested The list of extensions requested by the client
> +         * @return The list of negotiated extensions
> +         */
>          public List<Extension> getNegotiatedExtensions(List<Extension> installed, List<Extension> requested) {
>              return fetchContainerDefaultConfigurator().getNegotiatedExtensions(installed, requested);
>          }
>
> +        /**
> +         * Checks whether the given Origin header value is acceptable. The default implementation
> +         * always returns {@code true}.
> +         *
> +         * @param originHeaderValue The Origin header value to check
> +         * @return {@code true} if the origin is acceptable
> +         */
>          public boolean checkOrigin(String originHeaderValue) {
>              return fetchContainerDefaultConfigurator().checkOrigin(originHeaderValue);
>          }
>
> +        /**
> +         * Provides the opportunity to modify the handshake before it is completed. This method
> +         * is called after the sub-protocol and extensions have been negotiated.
> +         *
> +         * @param sec     The server endpoint configuration
> +         * @param request The handshake request
> +         * @param response The handshake response
> +         */
>          public void modifyHandshake(ServerEndpointConfig sec, HandshakeRequest request, HandshakeResponse response) {
>              fetchContainerDefaultConfigurator().modifyHandshake(sec, request, response);
>          }
>
> +        /**
> +         * Creates a new instance of the endpoint class.
> +         *
> +         * @param <T>    The type of the endpoint class
> +         * @param clazz  The endpoint class
> +         * @return A new instance of the endpoint
> +         * @throws InstantiationException If the endpoint cannot be instantiated
> +         */
>          public <T extends Object> T getEndpointInstance(Class<T> clazz) throws InstantiationException {
>              return fetchContainerDefaultConfigurator().getEndpointInstance(clazz);
>          }
> diff --git a/java/jakarta/xml/ws/WebServiceRef.java b/java/jakarta/xml/ws/WebServiceRef.java
> index 3c7e7a4738..e90a6f9c3c 100644
> --- a/java/jakarta/xml/ws/WebServiceRef.java
> +++ b/java/jakarta/xml/ws/WebServiceRef.java
> @@ -21,19 +21,48 @@ import java.lang.annotation.Retention;
>  import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
> +/**
> + * Declares a reference to a web service. The WebServiceRef annotation can be applied to a field or method to inject
> + * a reference to a web service, or to a class to declare web service dependencies.
> + */
>  @Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD })
>  @Retention(RetentionPolicy.RUNTIME)
> -
>  public @interface WebServiceRef {
> +
> +    /**
> +     * The name for the web service reference. The name is relative to the default initial context.
> +     *
> +     * @return the name of the web service reference
> +     */
>      String name() default "";
>
> +    /**
> +     * The type of the injected object, typically the service endpoint interface.
> +     *
> +     * @return the type class
> +     */
>      @SuppressWarnings("rawtypes") // Can't use Class<?> because API needs to match specification
>      Class type() default Object.class;
>
> +    /**
> +     * The web service class, typically the service endpoint interface class.
> +     *
> +     * @return the web service class
> +     */
>      @SuppressWarnings("rawtypes") // Can't use Class<?> because API needs to match specification
>      Class value() default Object.class;
>
> +    /**
> +     * The location of the WSDL document for the web service.
> +     *
> +     * @return the WSDL location
> +     */
>      String wsdlLocation() default "";
>
> +    /**
> +     * A provider-specific name that this reference should be mapped to.
> +     *
> +     * @return the provider-specific mapped name
> +     */
>      String mappedName() default "";
>  }
> diff --git a/java/jakarta/xml/ws/WebServiceRefs.java b/java/jakarta/xml/ws/WebServiceRefs.java
> index 0b69d9e1f2..020d86a674 100644
> --- a/java/jakarta/xml/ws/WebServiceRefs.java
> +++ b/java/jakarta/xml/ws/WebServiceRefs.java
> @@ -21,9 +21,18 @@ import java.lang.annotation.Retention;
>  import java.lang.annotation.RetentionPolicy;
>  import java.lang.annotation.Target;
>
> +/**
> + * Groups multiple {@link WebServiceRef} annotations on a single declaration. Use this annotation when a class has
> + * dependencies on more than one web service.
> + */
>  @Target(ElementType.TYPE)
>  @Retention(RetentionPolicy.RUNTIME)
> -
>  public @interface WebServiceRefs {
> +
> +    /**
> +     * The array of WebServiceRef annotations.
> +     *
> +     * @return the WebServiceRef annotations
> +     */
>      WebServiceRef[] value();
>  }
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
> For additional commands, e-mail: dev-help@tomcat.apache.org
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org