chore(javadocs): update javados and examples

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);
+        }
+    }
+}

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!"));
+    }
+
+}

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() {

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;

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;