From 0e92aef980bb6f49ad5c219dd2479ebee5a2d03f Mon Sep 17 00:00:00 2001
From: Erik Olsson <olsson.erik1993@gmail.com>
Date: Sat, 16 May 2026 22:56:45 +0200
Subject: [PATCH] chore(javadocs): add validation usage examples for `Ensure`
 methods and update library documentation

Signed-off-by: Erik Olsson <olsson.erik1993@gmail.com>
---
 .../examples/ExamplesInPackageInfo.java       | 44 ++++++++++++++++
 .../ensure4j/examples/JavaStreamExample.java  | 19 +++++++
 .../io/github/mangila/ensure4j/Ensure.java    |  7 +++
 .../mangila/ensure4j/EnsureException.java     |  1 +
 .../github/mangila/ensure4j/package-info.java | 52 +++++++++++++++++++
 5 files changed, 123 insertions(+)
 create mode 100644 examples/src/main/java/io/github.com/ensure4j/examples/ExamplesInPackageInfo.java
 create mode 100644 examples/src/main/java/io/github.com/ensure4j/examples/JavaStreamExample.java

diff --git a/examples/src/main/java/io/github.com/ensure4j/examples/ExamplesInPackageInfo.java b/examples/src/main/java/io/github.com/ensure4j/examples/ExamplesInPackageInfo.java
new file mode 100644
index 0000000..9d1e90c
--- /dev/null
+++ b/examples/src/main/java/io/github.com/ensure4j/examples/ExamplesInPackageInfo.java
@@ -0,0 +1,44 @@
+package io.github.com.ensure4j.examples;
+
+import io.github.mangila.ensure4j.Ensure;
+
+public class ExamplesInPackageInfo {
+
+    private static final String EMAIL_REGEX = "the email regex";
+
+    public void processOrder(Order order) {
+        Ensure.notNull(order);
+        Ensure.positive(order.getAmount());
+        // ...
+    }
+
+    public void sendEmail(String email) {
+        Ensure.notBlank(email, "Email must not be blank");
+        Ensure.matches(email, EMAIL_REGEX, "Invalid email format");
+        // ...
+    }
+
+    public void withdraw(int amount, int balance) {
+        Ensure.positive(amount, () -> new InsufficientFundsException("Amount must be positive"));
+        Ensure.max(amount, balance, () -> new InsufficientFundsException("Insufficient funds"));
+        // ...
+    }
+
+    private static class Order {
+        private final int amount;
+
+        Order(int amount) {
+            this.amount = amount;
+        }
+
+        int getAmount() {
+            return amount;
+        }
+    }
+
+    private static class InsufficientFundsException extends RuntimeException {
+        public InsufficientFundsException(String message) {
+            super(message);
+        }
+    }
+}
diff --git a/examples/src/main/java/io/github.com/ensure4j/examples/JavaStreamExample.java b/examples/src/main/java/io/github.com/ensure4j/examples/JavaStreamExample.java
new file mode 100644
index 0000000..8b7c00d
--- /dev/null
+++ b/examples/src/main/java/io/github.com/ensure4j/examples/JavaStreamExample.java
@@ -0,0 +1,19 @@
+package io.github.com.ensure4j.examples;
+
+import io.github.mangila.ensure4j.Ensure;
+
+import java.util.List;
+
+public class JavaStreamExample {
+
+    private static final List<String> stringCollection = List.of("a", "b", "c");
+
+    void streamIt() {
+        Ensure.notEmpty(stringCollection);
+        stringCollection.stream()
+                .map(Ensure::notBlank)
+                .map(s -> Ensure.matches(s, "[a-z]+", "invalid string"))
+                .forEach(s -> System.out.println("i have ensured my string!"));
+    }
+
+}
diff --git a/lib/src/main/java/io/github/mangila/ensure4j/Ensure.java b/lib/src/main/java/io/github/mangila/ensure4j/Ensure.java
index 698f90e..d462aae 100644
--- a/lib/src/main/java/io/github/mangila/ensure4j/Ensure.java
+++ b/lib/src/main/java/io/github/mangila/ensure4j/Ensure.java
@@ -7,6 +7,13 @@
 import org.intellij.lang.annotations.RegExp;
 import org.jetbrains.annotations.Contract;
 
+/**
+ * Ensure4j is a lightweight, fluent Java library for parameter validation and preconditions.
+ *
+ * <p>It provides a comprehensive set of static methods in the {@link
+ * io.github.mangila.ensure4j.Ensure} class to validate various data types including objects,
+ * strings, numbers, collections, maps, arrays, and date/time objects.
+ */
 public final class Ensure {
 
   private Ensure() {
diff --git a/lib/src/main/java/io/github/mangila/ensure4j/EnsureException.java b/lib/src/main/java/io/github/mangila/ensure4j/EnsureException.java
index c1d5303..00a14bb 100644
--- a/lib/src/main/java/io/github/mangila/ensure4j/EnsureException.java
+++ b/lib/src/main/java/io/github/mangila/ensure4j/EnsureException.java
@@ -2,6 +2,7 @@
 
 import java.io.Serial;
 
+/** Exception thrown by Ensure methods. */
 public class EnsureException extends RuntimeException {
 
   @Serial private static final long serialVersionUID = 1L;
diff --git a/lib/src/main/java/io/github/mangila/ensure4j/package-info.java b/lib/src/main/java/io/github/mangila/ensure4j/package-info.java
index 5b529d4..c6a3b1b 100644
--- a/lib/src/main/java/io/github/mangila/ensure4j/package-info.java
+++ b/lib/src/main/java/io/github/mangila/ensure4j/package-info.java
@@ -1 +1,53 @@
+/**
+ * Ensure4j is a lightweight, fluent Java library for parameter validation and preconditions.
+ *
+ * <p>It provides a comprehensive set of static methods in the {@link
+ * io.github.mangila.ensure4j.Ensure} class to validate various data types including objects,
+ * strings, numbers, collections, maps, arrays, and date/time objects.
+ *
+ * <h2>Key Features</h2>
+ *
+ * <ul>
+ *   <li><b>Fluent API:</b> Easy to read and write validation logic.
+ *   <li><b>Type-Safe:</b> Returns the validated object to allow for method chaining or direct
+ *       assignment.
+ *   <li><b>Customizable:</b> Supports default exception messages, custom messages, or custom
+ *       exceptions via {@link java.util.function.Supplier}.
+ *   <li><b>Lightweight:</b> Minimal dependencies and fast execution.
+ * </ul>
+ *
+ * <h2>Usage Examples</h2>
+ *
+ * <h3>Basic Usage</h3>
+ *
+ * <pre>{@code
+ * public void processOrder(Order order) {
+ *     Ensure.notNull(order);
+ *     Ensure.positive(order.getAmount());
+ *     // ...
+ * }
+ * }</pre>
+ *
+ * <h3>Custom Exception Messages</h3>
+ *
+ * <pre>{@code
+ * public void sendEmail(String email) {
+ *  Ensure.notBlank(email, "Email must not be blank");
+ *  Ensure.matches(email, EMAIL_REGEX, "Invalid email format");
+ *  // ...
+ * }
+ * }</pre>
+ *
+ * <h3>Custom Exceptions</h3>
+ *
+ * <pre>{@code
+ * public void withdraw(double amount) {
+ *     Ensure.positive(amount, () -> new InsufficientFundsException("Amount must be positive"));
+ *     Ensure.max(amount, balance, () -> new InsufficientFundsException("Insufficient funds"));
+ *     // ...
+ * }
+ * }</pre>
+ *
+ * @see io.github.mangila.ensure4j.Ensure
+ */
 package io.github.mangila.ensure4j;