[refactor] update javadoc

Author: dizzzz

extensions/modules/http-client/src/main/java/org/exist/xquery/modules/httpclient/ContentTypeHelper.java

@@ -50,6 +50,9 @@ private ContentTypeHelper() {
 
     /**
      * Tests whether the content type represents XML that should be parsed.
+     *
+     * @param contentType the content type to test
+     * @return {@code true} if the content type is XML
      */
     public static boolean isXml(final String contentType) {
         final String mediaType = extractMediaType(contentType);
@@ -60,6 +63,9 @@ public static boolean isXml(final String contentType) {
 
     /**
      * Tests whether the content type represents HTML that should be parsed.
+     *
+     * @param contentType the content type to test
+     * @return {@code true} if the content type is HTML
      */
     public static boolean isHtml(final String contentType) {
         final String mediaType = extractMediaType(contentType);
@@ -71,6 +77,9 @@ public static boolean isHtml(final String contentType) {
      * Tests whether the content type represents text that should be returned as xs:string.
      *
      * <p>Excludes XML and HTML types (which are parsed as documents instead).</p>
+     *
+     * @param contentType the content type to test
+     * @return {@code true} if the content type is text
      */
     public static boolean isText(final String contentType) {
         final String mediaType = extractMediaType(contentType);

extensions/modules/http-client/src/main/java/org/exist/xquery/modules/httpclient/HttpClientFactory.java

@@ -42,7 +42,7 @@
  * holds at most 25 entries and evicts entries that have not been accessed for one hour.
  * It is also cleared on JVM shutdown via a registered shutdown hook.</p>
  */
-class HttpClientFactory {
+public class HttpClientFactory {
 
     private static final Cache<HttpClientOptions, HttpClient> CLIENT_CACHE =
             Caffeine.newBuilder()

extensions/modules/http-client/src/main/java/org/exist/xquery/modules/httpclient/HttpClientModule.java

@@ -45,31 +45,46 @@
  */
 public class HttpClientModule extends AbstractInternalModule {
 
+    /** Namespace URI for the module. */
     public static final String NAMESPACE_URI = "http://expath.org/ns/http-client";
+    /** Default prefix for the module. */
     public static final String PREFIX = "http";
+    /** Release version of the module. */
     public static final String RELEASE = "0.9.0-SNAPSHOT";
 
+    /** Namespace URI for EXPath error codes. */
     public static final String ERROR_NS = "http://expath.org/ns/error";
 
     // EXPath HTTP Client error codes
+    /** An HTTP error occurred. */
     public static final ErrorCodes.ErrorCode HC001 = new ErrorCodes.ErrorCode(
             new QName("HC001", ERROR_NS, "err"), "An HTTP error occurred");
+    /** Error parsing entity content as XML or HTML. */
     public static final ErrorCodes.ErrorCode HC002 = new ErrorCodes.ErrorCode(
             new QName("HC002", ERROR_NS, "err"), "Error parsing entity content as XML or HTML");
+    /** Multipart override-media-type violation. */
     public static final ErrorCodes.ErrorCode HC003 = new ErrorCodes.ErrorCode(
             new QName("HC003", ERROR_NS, "err"), "Multipart override-media-type violation");
+    /** src attribute conflicts with body content. */
     public static final ErrorCodes.ErrorCode HC004 = new ErrorCodes.ErrorCode(
             new QName("HC004", ERROR_NS, "err"), "src attribute conflicts with body content");
+    /** Invalid request element structure. */
     public static final ErrorCodes.ErrorCode HC005 = new ErrorCodes.ErrorCode(
             new QName("HC005", ERROR_NS, "err"), "Invalid request element structure");
+    /** Timeout waiting for response. */
     public static final ErrorCodes.ErrorCode HC006 = new ErrorCodes.ErrorCode(
             new QName("HC006", ERROR_NS, "err"), "Timeout waiting for response");
 
+    /** The functions defined in this module. */
     public static final FunctionDef[] functions = functionDefs(
             functionDefs(SendRequestFunction.class,
                     SendRequestFunction.FS_SEND_REQUEST)
     );
 
+    /**
+     * Creates a new module instance.
+     * @param parameters the module parameters
+     */
     public HttpClientModule(final Map<String, List<?>> parameters) {
         super(functions, parameters);
     }

extensions/modules/http-client/src/main/java/org/exist/xquery/modules/httpclient/RequestBuilder.java

@@ -64,6 +64,7 @@
  */
 public class RequestBuilder {
 
+
     private static final String HTTP_NS = HttpClientModule.NAMESPACE_URI;
 
     private String method;
@@ -160,6 +161,9 @@ private void validate() throws XPathException {
     /**
      * Builds the {@link java.net.http.HttpRequest} from the parsed parameters, sending credentials
      * preemptively only when {@code @send-authorization} is true.
+     *
+     * @return the built HttpRequest
+     * @throws XPathException if the URI is invalid
      */
     public HttpRequest build() throws XPathException {
         return build(null);
@@ -171,6 +175,8 @@ public HttpRequest build() throws XPathException {
      * @param authorizationHeader when non-null, attach this exact {@code Authorization} header
      *     value — used to answer a 401 challenge with a Basic or Digest response computed by
      *     {@link #challengeResponse(String)} (see {@link #shouldAttemptChallenge()}).
+     * @return the built HttpRequest
+     * @throws XPathException if the URI is invalid
      */
     public HttpRequest build(final String authorizationHeader) throws XPathException {
         final URI uri;
@@ -413,6 +419,10 @@ private static String md5(final String s) {
         }
     }
 
+    /**
+     * Returns the parsed request options.
+     * @return the request options
+     */
     public RequestOptions getOptions() {
         return allOptions;
     }

extensions/modules/http-client/src/main/java/org/exist/xquery/modules/httpclient/ResponseHandler.java

@@ -85,6 +85,7 @@ public class ResponseHandler {
      * @param statusOnly    if true, return only the response element (no body)
      * @param overrideMedia if non-null, use this media type instead of the response Content-Type
      * @return the result sequence
+     * @throws XPathException if an error occurs during result building
      */
     public static Sequence buildResult(final HttpResponse<byte[]> response,
                                         final XQueryContext context,

extensions/modules/http-client/src/main/java/org/exist/xquery/modules/httpclient/SendRequestFunction.java

@@ -54,6 +54,7 @@ public class SendRequestFunction extends BasicFunction {
             "The response is a sequence where the first item is an http:response element " +
             "with status, message, and header information, followed by the response body content.";
 
+    /** The function signature for http:send-request. */
     public static final FunctionSignature[] FS_SEND_REQUEST = functionSignatures(
             HttpClientModule.qname(FS_SEND_REQUEST_NAME),
             FS_SEND_REQUEST_DESCRIPTION,
@@ -75,6 +76,12 @@ public class SendRequestFunction extends BasicFunction {
             )
     );
 
+    /**
+     * Creates a new function instance.
+     *
+     * @param context   the XQuery context
+     * @param signature the function signature
+     */
     public SendRequestFunction(final XQueryContext context, final FunctionSignature signature) {
         super(context, signature);
     }

extensions/modules/http-client/src/main/java/org/exist/xquery/modules/httpclient/config/HttpClientOptions.java

@@ -28,13 +28,20 @@
  *
  * <p>All fields correspond directly to attributes on the {@code http:request} element
  * as defined by the EXPath HTTP Client specification.</p>
+ *
+ * @param followRedirect     whether to follow HTTP redirects
+ * @param timeout            connection timeout in seconds
+ * @param httpVersion        the HTTP version to use
+ * @param autoAcceptEncoding whether to automatically add the {@code Accept-Encoding} header
  */
 public record HttpClientOptions(
         boolean followRedirect,
         int timeout,
         HttpClient.Version httpVersion,
         boolean autoAcceptEncoding
 ) {
-    /** Default options: follow redirects, no timeout, HTTP/1.1, auto-accept encoding. */
+    /**
+     * Default options: follow redirects, no timeout, HTTP/1.1, auto-accept encoding.
+     */
     public static final HttpClientOptions DEFAULTS = new HttpClientOptions(true, 0, HttpClient.Version.HTTP_1_1, true);
 }

extensions/modules/http-client/src/main/java/org/exist/xquery/modules/httpclient/config/RequestOptions.java

@@ -26,6 +26,10 @@
 /**
  * Combines the parsed {@link HttpClientOptions}, {@link ResponseOptions}, and {@link UserCredentials}
  * returned by {@link RequestOptionsParser#parse(org.w3c.dom.Element)}.
+ *
+ * @param requestOptions  the parsed HTTP client options
+ * @param responseOptions the parsed response handling options
+ * @param userCredentials the parsed user credentials for authentication
  */
 public record RequestOptions(
         HttpClientOptions requestOptions,

extensions/modules/http-client/src/main/java/org/exist/xquery/modules/httpclient/config/ResponseOptions.java

@@ -26,11 +26,16 @@
  *
  * <p>These fields control how the HTTP response is interpreted and returned,
  * as defined by the EXPath HTTP Client specification.</p>
+ *
+ * @param statusOnly        whether to return only the status code and headers, omitting the body
+ * @param overrideMediaType an optional media type to use when parsing the response body
  */
 public record ResponseOptions(
         boolean statusOnly,
         String overrideMediaType
 ) {
-    /** Default response options: return full body, no media-type override. */
+    /**
+     * Default response options: return full body, no media-type override.
+     */
     public static final ResponseOptions DEFAULTS = new ResponseOptions(false, null);
 }

extensions/modules/http-client/src/main/java/org/exist/xquery/modules/httpclient/config/UserCredentials.java

@@ -27,13 +27,20 @@
  * <p>Holds the authentication-related attributes ({@code username}, {@code password},
  * {@code auth-method}, {@code send-authorization}) as defined by the EXPath HTTP Client
  * specification.</p>
+ *
+ * @param username          the username for authentication
+ * @param password          the password for authentication
+ * @param authMethod        the authentication method (e.g., "Basic", "Digest")
+ * @param sendAuthorization whether to send the Authorization header preemptively
  */
 public record UserCredentials(
         String username, //user
         String password, //user
         String authMethod, // user
         boolean sendAuthorization //
 ) {
-    /** Default credentials: no authentication. */
+    /**
+     * Default credentials: no authentication.
+     */
     public static final UserCredentials DEFAULTS = new UserCredentials(null, null, null, false);
 }