From 432b705327d68cf5bb0e987d7b07cb860f8b2be9 Mon Sep 17 00:00:00 2001
From: Leo Galambos <lg@hq.egothor.org>
Date: Sun, 6 Jul 2025 13:46:03 +0200
Subject: [PATCH] docs: guide in package javadoc; fix &lt;

Signed-off-by: Leo Galambos <lg@hq.egothor.org>
---
 build.gradle                            |  4 ++++
 src/main/java/conflux/Ctx.java          |  2 +-
 src/main/java/conflux/package-info.java | 32 +++++++++++++++++++++++++
 3 files changed, 37 insertions(+), 1 deletion(-)
 create mode 100644 src/main/java/conflux/package-info.java

diff --git a/build.gradle b/build.gradle
index 9271be9..79993f9 100644
--- a/build.gradle
+++ b/build.gradle
@@ -39,6 +39,10 @@ tasks.named('test') {
     useJUnitPlatform()
 }
 
+tasks.withType(Javadoc).configureEach {
+    options.bottom = "Copyright &copy; 2025 Egothor"
+}
+
 if (project.hasProperty('giteaToken') && project.giteaToken) {
     publishing {
         publications {
diff --git a/src/main/java/conflux/Ctx.java b/src/main/java/conflux/Ctx.java
index b6a4f0b..cbbb441 100644
--- a/src/main/java/conflux/Ctx.java
+++ b/src/main/java/conflux/Ctx.java
@@ -57,7 +57,7 @@ import java.util.concurrent.CopyOnWriteArrayList;
  * Usage:
  * 
  * <pre>
- * Key<Integer> COUNT = Key.of("count", Integer.class);
+ * Key&lt;Integer> COUNT = Key.of("count", Integer.class);
  * Ctx.INSTANCE.put(COUNT, 42);
  * int v = Ctx.INSTANCE.get(COUNT);
  * </pre>
diff --git a/src/main/java/conflux/package-info.java b/src/main/java/conflux/package-info.java
new file mode 100644
index 0000000..8ef96a9
--- /dev/null
+++ b/src/main/java/conflux/package-info.java
@@ -0,0 +1,32 @@
+/**
+ * Provides a lightweight, type-safe, application-wide context mechanism for
+ * sharing strongly typed data among otherwise decoupled classes.
+ * <p>
+ * The {@link conflux.Ctx} class acts as a central, generic context storage
+ * supporting key-based put/get operations. Each {@link conflux.Key} defines a
+ * unique, strongly typed entry in the context, ensuring type consistency and
+ * preventing misuse. {@link conflux.Listener} interfaces allow clients to
+ * observe value changes for specific keys. Listeners are held with weak
+ * references to avoid memory leaks.
+ * <p>
+ * Typical usage involves defining {@link conflux.Key} instances with explicit
+ * types, storing values through {@code Ctx.INSTANCE.put()}, and retrieving them
+ * with {@code Ctx.INSTANCE.get()}. Listeners can be attached via
+ * {@code Ctx.INSTANCE.addListener()} to react to context changes in a decoupled
+ * and thread-safe manner. Values and listeners can be removed individually or
+ * the entire context can be cleared.
+ * <p>
+ * <b>Best Practices:</b>
+ * <ul>
+ * <li>Define keys as constants to maintain consistency and avoid
+ * collisions.</li>
+ * <li>Remove listeners when no longer needed (although weak references help
+ * prevent leaks).</li>
+ * <li>Use unique key names to ensure no accidental type conflicts.</li>
+ * </ul>
+ *
+ * @see conflux.Ctx
+ * @see conflux.Key
+ * @see conflux.Listener
+ */
+package conflux;
\ No newline at end of file