feat: idea for api design

Signed-off-by: Eric Deandrea <eric.deandrea@ibm.com>

Author: edeandrea

api/src/main/java/ai/docling/api/DoclingApi.java

@@ -33,6 +33,13 @@ public interface DoclingApi {
    */
   <T extends DoclingApi, B extends DoclingApiBuilder<T, B>> DoclingApiBuilder<T, B> toBuilder();
 
+  /**
+   * A builder interface for constructing implementations of {@link DoclingApi}. This interface
+   * supports a fluent API for setting configuration properties before building an instance.
+   *
+   * @param <T> the type of the {@link DoclingApi} implementation being built.
+   * @param <B> the type of the concrete builder implementation.
+   */
   interface DoclingApiBuilder<T extends DoclingApi, B extends DoclingApiBuilder<T, B>> {
     /**
      * Builds and returns an instance of the specified type, representing the completed configuration

api/src/main/java/ai/docling/api/convert/response/DocumentResponse.java

@@ -4,6 +4,8 @@
 import java.util.Map;
 import java.util.Optional;
 
+import org.jspecify.annotations.Nullable;
+
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import tools.jackson.databind.annotation.JsonDeserialize;
@@ -12,21 +14,80 @@
 @JsonInclude(JsonInclude.Include.NON_ABSENT)
 @JsonDeserialize(builder = DocumentResponse.Builder.class)
 public interface DocumentResponse {
+  /**
+   * Retrieves the content of the doc tags, if available.
+   *
+   * @return the content of the doc tags, or null if not present
+   */
+  @Nullable
   String doctagsContent();
+
+  /**
+   * Retrieves the filename associated with the document.
+   *
+   * @return the filename of the document as a string
+   */
   String filename();
+
+  /**
+   * Retrieves the HTML content associated with the document, if available.
+   *
+   * @return the HTML content as a string, or null if not present
+   */
+  @Nullable
   String htmlContent();
+
+  /**
+   * Retrieves the JSON content associated with the document.
+   *
+   * @return a map representing the JSON content, or an empty map if no JSON content is present
+   */
   Map<String, Object> jsonContent();
+
+  /**
+   * Retrieves the Markdown content associated with the document, if available.
+   *
+   * @return the Markdown content as a string, or null if no Markdown content is present
+   */
+  @Nullable
   String markdownContent();
+
+  /**
+   * Retrieves the plain text content associated with the document, if available.
+   *
+   * @return the plain text content as a string, or null if no text content is present
+   */
+  @Nullable
   String textContent();
 
+  /**
+   * Creates a new {@code Builder} instance initialized with the current state of the {@code DocumentResponse}.
+   *
+   * @return a {@code Builder} instance populated with the values from this {@code DocumentResponse}
+   */
   default Builder toBuilder() {
     return new Builder(this);
   }
 
+  /**
+   * Creates and returns a new instance of the {@code Builder} class, which can be used to
+   * construct a {@code DocumentResponse} object in a step-by-step manner.
+   *
+   * @return a new {@code Builder} instance
+   */
   static Builder builder() {
     return new Builder();
   }
 
+  /**
+   * Default implementation of the {@link DocumentResponse} interface.
+   * This record represents the response containing document data in various formats.
+   * It is an immutable data structure that consolidates information related to a document,
+   * such as its filename, content in multiple formats, and metadata.
+   *
+   * Each instance ensures the provided JSON content is unmodifiable by copying
+   * the input map if it is present, or initializing it to an empty map otherwise.
+   */
   record DefaultDocumentResponse(String doctagsContent,
                                  String filename,
                                  String htmlContent,
@@ -50,6 +111,26 @@ public DefaultDocumentResponse(Builder builder) {
     }
   }
 
+  /**
+   * A builder class for constructing instances of {@code DocumentResponse}.
+   *
+   * This class provides a step-by-step approach to configure and create a
+   * {@code DocumentResponse} object. Each method in this class sets a specific
+   * property of the object being built. Once all the desired properties are set,
+   * the {@code build} method is used to create the final {@code DocumentResponse}
+   * instance.
+   *
+   * The builder supports customization of various document-related attributes,
+   * including doc tags content, filename, HTML content, JSON content, Markdown
+   * content, and plain text content.
+   *
+   * By default, the builder initializes attributes with an empty state or default
+   * values. If a {@code DocumentResponse} instance is provided to the constructor,
+   * the builder is pre-populated with the attributes from the given response.
+   *
+   * This class is intended for internal use and is protected to restrict its
+   * accessibility outside the defining package or class hierarchy.
+   */
   @JsonPOJOBuilder(withPrefix = "")
   class Builder {
     protected String doctagsContent;
@@ -59,10 +140,30 @@ class Builder {
     protected String markdownContent;
     protected String textContent;
 
+    /**
+     * Constructs a new {@code Builder} instance.
+     *
+     * This constructor initializes a builder with default or empty states for all
+     * attributes. It is protected to restrict direct instantiation outside of the
+     * defining package or class hierarchy.
+     *
+     * The {@code Builder} class is primarily used to facilitate the creation of
+     * {@code DocumentResponse} objects through a step-by-step configuration process.
+     */
     protected Builder() {
 
     }
 
+    /**
+     * Constructs a new {@code Builder} instance using the provided {@code DocumentResponse}.
+     *
+     * This constructor initializes the builder's fields with the data from the given
+     * {@code DocumentResponse} object. It allows for the creation of a {@code Builder}
+     * instance pre-populated with the state of an existing {@code DocumentResponse}.
+     *
+     * @param documentResponse the {@code DocumentResponse} instance whose data will
+     *                          populate the fields of this builder
+     */
     protected Builder(DocumentResponse documentResponse) {
       this.doctagsContent = documentResponse.doctagsContent();
       this.filename = documentResponse.filename();
@@ -72,42 +173,95 @@ protected Builder(DocumentResponse documentResponse) {
       this.textContent = documentResponse.textContent();
     }
 
+    /**
+     * Sets the doctags content for the builder instance.
+     *
+     * @param doctagsContent the doctags content to be set
+     * @return this Builder instance for method chaining
+     */
     @JsonProperty("doctags_content")
     public Builder doctagsContent(String doctagsContent) {
       this.doctagsContent = doctagsContent;
       return this;
     }
 
+    /**
+     * Sets the filename for the builder instance.
+     *
+     * @param filename the filename to be set
+     * @return this Builder instance for method chaining
+     */
     @JsonProperty("filename")
     public Builder filename(String filename) {
       this.filename = filename;
       return this;
     }
 
+    /**
+     * Sets the HTML content for the builder instance.
+     *
+     * @param htmlContent the HTML content to be set
+     * @return this Builder instance for method chaining
+     */
     @JsonProperty("html_content")
     public Builder htmlContent(String htmlContent) {
       this.htmlContent = htmlContent;
       return this;
     }
 
+    /**
+     * Sets the JSON content for the builder instance.
+     *
+     * The JSON content is represented as a map of key-value pairs, where the keys
+     * are {@code String} objects, and the values are {@code Object} instances.
+     *
+     * @param jsonContent the JSON content to be set, represented as a {@code Map<String, Object>}
+     * @return this {@link Builder} instance for method chaining
+     */
     @JsonProperty("json_content")
     public Builder jsonContent(Map<String, Object> jsonContent) {
       this.jsonContent = jsonContent;
       return this;
     }
 
+    /**
+     * Sets the Markdown content for this builder instance.
+     *
+     * The Markdown content represents the textual data formatted in Markdown syntax,
+     * which can include headings, lists, links, and other Markdown elements.
+     *
+     * @param markdownContent the Markdown content to be set, represented as a {@code String}
+     * @return this {@link Builder} instance for method chaining
+     */
     @JsonProperty("md_content")
     public Builder markdownContent(String markdownContent) {
       this.markdownContent = markdownContent;
       return this;
     }
 
+    /**
+     * Sets the plain text content for this builder instance.
+     *
+     * The plain text content represents unformatted textual data that can be
+     * used for display or processing purposes within the application.
+     *
+     * @param textContent the plain text content to be set, represented as a {@code String}
+     * @return this {@link Builder} instance for method chaining
+     */
     @JsonProperty("text_content")
     public Builder textContent(String textContent) {
       this.textContent = textContent;
       return this;
     }
 
+    /**
+     * Creates and returns a {@link DocumentResponse} instance based on the current state of this {@link Builder}.
+     *
+     * <p>The returned {@link DocumentResponse} will encapsulate the values configured in the builder,
+     * and further modifications to the builder instance will not affect the created {@code DocumentResponse}.
+     *
+     * @return a new {@code DocumentResponse} instance constructed from the builder's state
+     */
     public DocumentResponse build() {
       return new DefaultDocumentResponse(this);
     }

client/src/main/java/ai/docling/client/DoclingClient.java

@@ -74,10 +74,29 @@ public Builder toBuilder() {
     return new Builder(this);
   }
 
+  /**
+   * Creates and returns a new instance of {@link Builder} for constructing a {@link DoclingClient}.
+   * The builder allows customization of configuration such as base URL, HTTP client, and JSON mapper.
+   *
+   * @return a new {@link Builder} instance for creating a {@link DoclingClient}.
+   */
   public static Builder builder() {
     return new Builder();
   }
 
+  /**
+   * A builder class for creating instances of {@link DoclingClient}. This builder supports a fluent
+   * API for configuring properties such as the base URL, HTTP client, and JSON mapper.
+   *
+   * <p>The {@link Builder} provides customization options through the available methods and ensures
+   * proper validation of inputs during configuration.
+   *
+   * <p>An instance of {@code Builder} can be obtained via {@link DoclingClient#builder()} or
+   * {@link DoclingClient#toBuilder()}.
+   *
+   * <p>This class is an implementation of {@link DoclingApiBuilder}, allowing it to construct
+   * {@code DoclingClient} instances as part of the API construction process.
+   */
   public static final class Builder implements DoclingApiBuilder<DoclingClient, Builder> {
     private URI baseUrl = DEFAULT_BASE_URL;
     private HttpClient.Builder httpClientBuilder = HttpClient.newBuilder();
@@ -92,26 +111,67 @@ private Builder(DoclingClient doclingClient) {
       this.jsonMapperBuilder = doclingClient.jsonMapper.rebuild();
     }
 
+    /**
+     * Sets the base URL for the Docling API service.
+     * 
+     * <p>The URL string will be parsed and converted to a {@link URI}.
+     *
+     * @param baseUrl the base URL as a string (must not be blank)
+     * @return this {@link Builder} instance for method chaining
+     * @throws IllegalArgumentException if baseUrl is null or blank
+     */
     public Builder baseUrl(String baseUrl) {
       this.baseUrl = URI.create(ensureNotBlank(baseUrl, "baseUrl"));
       return this;
     }
 
+    /**
+     * Sets the base URL for the Docling API service.
+     *
+     * @param baseUrl the base URL as a {@link URI}
+     * @return this {@link Builder} instance for method chaining
+     */
     public Builder baseUrl(URI baseUrl) {
       this.baseUrl = baseUrl;
       return this;
     }
 
+    /**
+     * Sets the HTTP client builder to be used for creating the underlying HTTP client.
+     * 
+     * <p>This allows customization of HTTP client properties such as timeouts,
+     * proxy settings, SSL context, and other connection parameters.
+     *
+     * @param httpClientBuilder the {@link HttpClient.Builder} to use
+     * @return this {@link Builder} instance for method chaining
+     */
     public Builder httpClientBuilder(HttpClient.Builder httpClientBuilder) {
       this.httpClientBuilder = httpClientBuilder;
       return this;
     }
 
+    /**
+     * Sets the JSON mapper builder to be used for creating the JSON mapper.
+     * 
+     * <p>This allows customization of JSON serialization and deserialization behavior,
+     * such as configuring features, modules, or property naming strategies.
+     *
+     * @param jsonMapperBuilder the {@link JsonMapper.Builder} to use
+     * @return this {@link Builder} instance for method chaining
+     */
     public Builder jsonParser(JsonMapper.Builder jsonMapperBuilder) {
       this.jsonMapperBuilder = jsonMapperBuilder;
       return this;
     }
 
+    /**
+     * Builds and returns a new {@link DoclingClient} instance with the configured properties.
+     *
+     * <p>This method validates all required parameters and constructs the client.
+     *
+     * @return a new {@link DoclingClient} instance
+     * @throws IllegalArgumentException if any required parameter is null
+     */
     @Override
     public DoclingClient build() {
       return new DoclingClient(this);