Add description to @Overwrite, log override sources, and generate Markdown reference file

Signed-off-by: Nora <46890129+RainbowDashLabs@users.noreply.github.com>

Author: rainbowdashlabs

build.gradle.kts

@@ -14,7 +14,7 @@ plugins {
 
 publishData {
     useEldoNexusRepos(false)
-    publishingVersion = "2.1.1"
+    publishingVersion = "2.1.2"
 }
 
 group = "dev.chojo"
@@ -119,4 +119,24 @@ tasks {
     compileJava {
         dependsOn(spotlessApply)
     }
+
+    register<Copy>("copyOverrideReference") {
+        description = "Copies the generated override reference file to build/ocular/"
+        from(fileTree(layout.buildDirectory) {
+            include("**/META-INF/ocular/overrides.md")
+        })
+        eachFile {
+            relativePath = RelativePath(true, name)
+        }
+        includeEmptyDirs = false
+        into(layout.buildDirectory.dir("ocular"))
+    }
+
+    named("classes") {
+        finalizedBy("copyOverrideReference")
+    }
+
+    test {
+        finalizedBy("copyOverrideReference")
+    }
 }

src/main/java/dev/chojo/ocular/override/OverrideApplier.java

@@ -54,6 +54,9 @@ public static <V> void applyOverrides(V object, ValueSupplier supplier) {
         // override values without the config class needing any special code.
         Class<?> clazz = object.getClass();
 
+        // Log available overrides with their descriptions
+        logAvailableOverrides(clazz);
+
         // Walk through every field in the config class (e.g. "private String host")
         // and check if the generated supplier has an override value for that field name.
         for (Field field : clazz.getDeclaredFields()) {
@@ -178,6 +181,75 @@ private static Field findBackingField(Class<?> clazz, String methodName, Class<?
         return bestMatch;
     }
 
+    /**
+     * Logs all available overrides for the given configuration class, including their descriptions
+     * if provided via the {@link Overwrite#description()} attribute.
+     * Takes {@link OverwritePrefix} into account for deriving default keys and forced prefixes.
+     */
+    private static void logAvailableOverrides(Class<?> clazz) {
+        String prefix = clazz.getSimpleName();
+        boolean forcePrefix = false;
+        OverwritePrefix overwritePrefix = clazz.getAnnotation(OverwritePrefix.class);
+        if (overwritePrefix != null) {
+            prefix = overwritePrefix.value();
+            forcePrefix = overwritePrefix.force();
+        }
+
+        boolean headerLogged = false;
+        for (Field field : clazz.getDeclaredFields()) {
+            Overwrite overwrite = field.getAnnotation(Overwrite.class);
+            if (overwrite != null) {
+                if (!headerLogged) {
+                    log.info("Available overrides for {}:", clazz.getSimpleName());
+                    headerLogged = true;
+                }
+                logOverwriteSources(overwrite, prefix, forcePrefix, field.getName());
+            }
+        }
+        for (Method method : clazz.getDeclaredMethods()) {
+            Overwrite overwrite = method.getAnnotation(Overwrite.class);
+            if (overwrite != null) {
+                if (!headerLogged) {
+                    log.info("Available overrides for {}:", clazz.getSimpleName());
+                    headerLogged = true;
+                }
+                logOverwriteSources(overwrite, prefix, forcePrefix, method.getName());
+            }
+        }
+    }
+
+    /**
+     * Logs the property and environment variable sources for a single {@link Overwrite} annotation,
+     * taking the prefix and force flag into account.
+     */
+    private static void logOverwriteSources(Overwrite overwrite, String prefix, boolean forcePrefix, String memberName) {
+        String desc = overwrite.description().isEmpty() ? "" : " - " + overwrite.description();
+        for (Prop prop : overwrite.prop()) {
+            String propPrefix = prefix.replace("_", ".").toLowerCase();
+            String key;
+            if (prop.value().isEmpty()) {
+                key = propPrefix + "." + memberName;
+            } else if (forcePrefix) {
+                key = propPrefix + "." + prop.value();
+            } else {
+                key = prop.value();
+            }
+            log.info("  Property: {}{}", key, desc);
+        }
+        for (Env env : overwrite.env()) {
+            String envPrefix = prefix.replace(".", "_").toUpperCase();
+            String key;
+            if (env.value().isEmpty()) {
+                key = envPrefix + "_" + memberName.toUpperCase();
+            } else if (forcePrefix) {
+                key = envPrefix + "_" + env.value();
+            } else {
+                key = env.value();
+            }
+            log.info("  Environment: {}{}", key, desc);
+        }
+    }
+
     /**
      * Converts a string override value to the target field/parameter type.
      * Supports all Java primitive types and their boxed equivalents, plus String.

src/main/java/dev/chojo/ocular/override/Overwrite.java

@@ -14,7 +14,7 @@
  * Marks a field or method in a configuration class as overridable at runtime.
  * <p>
  * When a configuration class contains fields or methods annotated with {@code @Overwrite},
- * the annotation processor ({@link dev.chojo.ocular.processor.OcularProcessor}) will generate
+ * the annotation processor ({@link dev.chojo.ocular.processor.OcularProcessor OcularProcessor}) will generate
  * a helper class at compile time that knows how to look up override values from environment
  * variables and/or system properties.
  * <p>
@@ -39,4 +39,9 @@
      * System property sources to check for an override value.
      */
     Prop[] prop() default {};
+
+    /**
+     * Description of the override.
+     */
+    String description() default "";
 }

src/main/java/dev/chojo/ocular/processor/OcularProcessor.java

@@ -5,8 +5,8 @@
  */
 package dev.chojo.ocular.processor;
 
-import dev.chojo.ocular.override.OverwritePrefix;
 import dev.chojo.ocular.override.Overwrite;
+import dev.chojo.ocular.override.OverwritePrefix;
 
 import javax.annotation.processing.AbstractProcessor;
 import javax.annotation.processing.Filer;
@@ -23,10 +23,14 @@
 import javax.lang.model.element.PackageElement;
 import javax.lang.model.element.TypeElement;
 import javax.tools.Diagnostic;
+import javax.tools.FileObject;
 import javax.tools.JavaFileObject;
+import javax.tools.StandardLocation;
 import java.io.IOException;
+import java.io.Writer;
 import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -125,16 +129,30 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
             classesToProcess.computeIfAbsent(enclosingClass, k -> new ArrayList<>()).add(element);
         }
 
+        // Collect override info for the reference file
+        Map<String, List<OverrideInfo>> allOverrides = new LinkedHashMap<>();
+
         // Generate one override provider class per config class
         for (Map.Entry<TypeElement, List<Element>> entry : classesToProcess.entrySet()) {
             try {
-                generateOverrideProvider(entry.getKey(), entry.getValue());
+                List<OverrideInfo> infos = generateOverrideProvider(entry.getKey(), entry.getValue());
+                allOverrides.put(entry.getKey().getQualifiedName().toString(), infos);
             } catch (IOException e) {
                 messager.printMessage(Diagnostic.Kind.ERROR,
                         "Could not generate override provider for " + entry.getKey().getQualifiedName() + ": " + e.getMessage());
             }
         }
 
+        // Generate reference documentation file
+        if (!allOverrides.isEmpty()) {
+            try {
+                generateOverrideDocumentation(allOverrides);
+            } catch (IOException e) {
+                messager.printMessage(Diagnostic.Kind.ERROR,
+                        "Could not generate override documentation: " + e.getMessage());
+            }
+        }
+
         return true;
     }
 
@@ -148,7 +166,41 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
      *   <li>A {@code getValue()} method that looks up a field name in the map.</li>
      * </ul>
      */
-    private void generateOverrideProvider(TypeElement typeElement, List<Element> elements) throws IOException {
+    /**
+     * Holds information about a single override for documentation and logging purposes.
+     */
+    private record OverrideInfo(String fieldName, String description, List<String> sources) {
+    }
+
+    /**
+     * Generates a Markdown reference file at {@code META-INF/ocular/overrides.md} listing all
+     * overridable properties and environment variables with their descriptions.
+     */
+    private void generateOverrideDocumentation(Map<String, List<OverrideInfo>> allOverrides) throws IOException {
+        FileObject resource = filer.createResource(StandardLocation.CLASS_OUTPUT, "", "META-INF/ocular/overrides.md");
+        try (Writer writer = resource.openWriter()) {
+            writer.append("# Ocular Override Reference\n\n");
+            writer.append("This file is auto-generated by the Ocular annotation processor.\n");
+            writer.append("It lists all available configuration overrides.\n\n");
+
+            for (Map.Entry<String, List<OverrideInfo>> entry : allOverrides.entrySet()) {
+                writer.append("## ").append(entry.getKey()).append("\n\n");
+                for (OverrideInfo info : entry.getValue()) {
+                    writer.append("### ").append(info.fieldName()).append("\n\n");
+                    if (!info.description().isEmpty()) {
+                        writer.append(info.description()).append("\n\n");
+                    }
+                    writer.append("Sources (in priority order):\n");
+                    for (String source : info.sources()) {
+                        writer.append("- ").append(source).append("\n");
+                    }
+                    writer.append("\n");
+                }
+            }
+        }
+    }
+
+    private List<OverrideInfo> generateOverrideProvider(TypeElement typeElement, List<Element> elements) throws IOException {
         // Extract the package (e.g. "com.example") so we can put the generated file in the same package
         String packageName = ((PackageElement) typeElement.getEnclosingElement()).getQualifiedName().toString();
         // Full name like "com.example.MyConfig"
@@ -170,6 +222,9 @@ private void generateOverrideProvider(TypeElement typeElement, List<Element> ele
 
         // Ask the compiler to create a new .java source file. The compiler will automatically
         // compile this generated file in the same compilation round — we just need to write valid Java into it.
+        // Collect override info for documentation
+        List<OverrideInfo> overrideInfos = new ArrayList<>();
+
         JavaFileObject builderFile = filer.createSourceFile(packageName + "." + generatedClassName);
         // SourceWriter is a helper that handles indentation so the generated code is readable
         try (SourceWriter out = new SourceWriter(builderFile.openWriter())) {
@@ -191,7 +246,10 @@ private void generateOverrideProvider(TypeElement typeElement, List<Element> ele
             for (Element element : elements) {
                 String fieldName = element.getSimpleName().toString();
                 // Write the lookup code for this field's env/prop sources into the constructor
-                emitLookupsInOrder(out, element, prefix, forcePrefix, fieldName);
+                OverrideInfo info = emitLookupsInOrder(out, element, prefix, forcePrefix, fieldName);
+                if (info != null) {
+                    overrideInfos.add(info);
+                }
             }
             out.endBlock();
 
@@ -203,6 +261,7 @@ private void generateOverrideProvider(TypeElement typeElement, List<Element> ele
 
             out.endBlock();
         }
+        return overrideInfos;
     }
 
     /**
@@ -217,12 +276,17 @@ private void generateOverrideProvider(TypeElement typeElement, List<Element> ele
      * code structure (mirrors), not the actual runtime annotation objects. Mirrors preserve the
      * declaration order of attributes, which is essential for correct precedence.
      */
-    private void emitLookupsInOrder(SourceWriter out, Element element, String prefix, boolean forcePrefix, String fieldName) throws IOException {
+    private OverrideInfo emitLookupsInOrder(SourceWriter out, Element element, String prefix, boolean forcePrefix, String fieldName) throws IOException {
         // Get the compile-time representation ("mirror") of the @Overwrite annotation on this field.
         // We need the mirror (not the annotation object) because at compile time the annotation class
         // isn't loaded as a real object — it only exists as metadata in the source code.
         AnnotationMirror overwriteMirror = findOverwriteMirror(element);
-        if (overwriteMirror == null) return;
+        if (overwriteMirror == null) return null;
+
+        // Extract the description from the @Overwrite annotation
+        String description = extractStringValue(overwriteMirror, "description");
+        if (description == null) description = "";
+        List<String> sources = new ArrayList<>();
 
         // Walk through each attribute of @Overwrite in the order the user wrote them.
         // For example, in @Overwrite(prop = @Prop(), env = @Env()), we'd iterate:
@@ -232,6 +296,8 @@ private void emitLookupsInOrder(SourceWriter out, Element element, String prefix
         // The first source that provides a non-null value wins.
         for (Map.Entry<? extends ExecutableElement, ? extends AnnotationValue> entry :
                 overwriteMirror.getElementValues().entrySet()) {
+            // Skip the description value
+            if (entry.getValue().getValue().getClass() == String.class) continue;
             // attrName is either "prop" or "env" — the attribute name from @Overwrite
             String attrName = entry.getKey().getSimpleName().toString();
             // The value is an array of nested annotations (e.g. the @Prop[] or @Env[] array)
@@ -255,6 +321,7 @@ private void emitLookupsInOrder(SourceWriter out, Element element, String prefix
                     }
                     // Write Java code like: String value = System.getProperty("myclass.host");
                     emitLookup(out, fieldName, "System.getProperty(\"" + key + "\")");
+                    sources.add("Property: `" + key + "`");
                 }
             } else if ("env".equals(attrName)) {
                 prefix = prefix.replace(".", "_").toUpperCase();
@@ -271,9 +338,11 @@ private void emitLookupsInOrder(SourceWriter out, Element element, String prefix
                     }
                     // Write Java code like: String value = System.getenv("MYCLASS_HOST");
                     emitLookup(out, fieldName, "System.getenv(\"" + key + "\")");
+                    sources.add("Environment: `" + key + "`");
                 }
             }
         }
+        return new OverrideInfo(fieldName, description, sources);
     }
 
     /**

src/test/java/dev/chojo/classes/AnnotationConfig.java

@@ -11,7 +11,7 @@
 
 public class AnnotationConfig {
     // prop is declared first, so it takes precedence over env
-    @Overwrite(prop = @Prop, env = @Env)
+    @Overwrite(prop = @Prop, env = @Env, description = "Some description")
     public String test;
 
     // explicit keys