From 6776d6e88bc0951dd3b36c0539849bb074d63ae3 Mon Sep 17 00:00:00 2001
From: zihluwang <really@zihlu.wang>
Date: Tue, 22 Oct 2024 13:45:03 +0800
Subject: [PATCH] docs: updated docs for record class QuartileBounds

---
 .../onixbyte/nums/model/QuartileBounds.java   | 74 +++++++++++++++++--
 1 file changed, 69 insertions(+), 5 deletions(-)

diff --git a/num4j/src/main/java/com/onixbyte/nums/model/QuartileBounds.java b/num4j/src/main/java/com/onixbyte/nums/model/QuartileBounds.java
index 45c6d24..3936e61 100644
--- a/num4j/src/main/java/com/onixbyte/nums/model/QuartileBounds.java
+++ b/num4j/src/main/java/com/onixbyte/nums/model/QuartileBounds.java
@@ -18,11 +18,32 @@
 package com.onixbyte.nums.model;
 
 /**
- * QuartileBound.
+ * A record representing the quartile bounds of a dataset.
+ * <p>
+ * This class encapsulates the lower and upper bounds of a dataset, which are typically used for detecting outliers in
+ * the data. The bounds are calculated based on the interquartile range (IQR) of the dataset. Values below the lower
+ * bound or above the upper bound may be considered outliers.
+ * <p>
+ * Quartile bounds consist of:
+ * <ul>
+ *   <li>{@code lowerBound} - The lower bound of the dataset, typically {@code Q1 - 1.5 * IQR}.</li>
+ *   <li>{@code upperBound} - The upper bound of the dataset, typically {@code Q3 + 1.5 * IQR}.</li>
+ * </ul>
+ * </p>
+ * <p>
+ * Example usage:
+ * <pre>
+ * QuartileBounds bounds = QuartileBounds.builder()
+ *     .lowerBound(1.5)
+ *     .upperBound(7.5)
+ *     .build();
+ * </pre>
  *
- * @param upperBound
- * @param lowerBound
+ * @param upperBound the upper bound of the dataset
+ * @param lowerBound the lower bound of the dataset
  * @author zihluwang
+ * @version 1.6.5
+ * @since 1.6.5
  */
 public record QuartileBounds(
         Double upperBound,
@@ -30,31 +51,74 @@ public record QuartileBounds(
 ) {
 
     /**
-     * Get a builder for {@link QuartileBounds}.
+     * Creates a new {@link Builder} instance for building a {@code QuartileBounds} object.
+     * <p>
+     * The {@link Builder} pattern is used to construct the {@code QuartileBounds} object with optional values for the
+     * upper and lower bounds.
+     * </p>
      *
-     * @return a builder
+     * @return a new instance of the {@link Builder} class
      */
     public static Builder builder() {
         return new Builder();
     }
 
+    /**
+     * A builder class for constructing instances of the {@code QuartileBounds} record.
+     * <p>
+     * The {@link Builder} pattern allows for the step-by-step construction of a {@code QuartileBounds} object,
+     * providing a flexible way to set values for the lower and upper bounds. Once the builder has the required values,
+     * the {@link #build()} method creates and returns a new {@code QuartileBounds} object.
+     * </p>
+     * <p>
+     * Example usage:
+     * <pre>
+     * {@code
+     * QuartileBounds bounds = QuartileBounds.builder()
+     *     .lowerBound(1.5)
+     *     .upperBound(7.5)
+     *     .build();
+     * }
+     * </pre>
+     */
     public static class Builder {
         private Double upperBound;
         private Double lowerBound;
 
+        /**
+         * Private constructor for {@code Builder}, ensuring it can only be instantiated through the
+         * {@link QuartileBounds#builder()} method.
+         */
         private Builder() {
         }
 
+        /**
+         * Sets the upper bound for the {@code QuartileBounds}.
+         *
+         * @param upperBound the upper bound of the dataset
+         * @return the current {@code Builder} instance, for method chaining
+         */
         public Builder upperBound(Double upperBound) {
             this.upperBound = upperBound;
             return this;
         }
 
+        /**
+         * Sets the lower bound for the {@code QuartileBounds}.
+         *
+         * @param lowerBound the lower bound of the dataset
+         * @return the current {@code Builder} instance, for method chaining
+         */
         public Builder lowerBound(Double lowerBound) {
             this.lowerBound = lowerBound;
             return this;
         }
 
+        /**
+         * Builds and returns a new {@code QuartileBounds} instance with the specified upper and lower bounds.
+         *
+         * @return a new {@code QuartileBounds} object containing the specified bounds
+         */
         public QuartileBounds build() {
             return new QuartileBounds(upperBound, lowerBound);
         }