From: Alexander Goussas <alexandergoussas.thoughtworks@latam.com>
Date: Mon, 29 Dec 2025 15:20:40 +0000 (-0500)
Subject: add javadocs to public interfaces
X-Git-Url: http://git.frustrated-labs.net/?a=commitdiff_plain;h=aa2d7bfd905cb0df444b8249c6ce8cd78c362ada;p=gradle-configvalidator-plugin.git

add javadocs to public interfaces
---

diff --git a/lib/src/main/java/io/github/aloussase/configvalidator/ConfigurationVariableSource.java b/lib/src/main/java/io/github/aloussase/configvalidator/ConfigurationVariableSource.java
index e98ac25..e8ed0ef 100644
--- a/lib/src/main/java/io/github/aloussase/configvalidator/ConfigurationVariableSource.java
+++ b/lib/src/main/java/io/github/aloussase/configvalidator/ConfigurationVariableSource.java
@@ -2,9 +2,21 @@ package io.github.aloussase.configvalidator;
 
 import java.util.List;
 
+/**
+ * Implementors of this interface should be able to fetch configuration variables
+ * from a given source (HTTP API, file; etc.) corresponding to the provided environment.
+ * <p>
+ * Implementors are free to ignore the {@code env} argument as well if not needed.
+ */
 public interface ConfigurationVariableSource {
     /**
      * Read a list of configuration variables defined for the specified environment.
+     * <p>
+     * This method should fail silently and return an empty list in the case of error.
+     * You may want to log errors to a file for bookkeeping. You might also want to throw
+     * and exception, in which case it will be visible to the end user.
+     * <p>
+     * Better error reporting is planned for future versions.
      *
      * @param env The environment for which to fetch configuration variables.
      * @return A list of the configuration variables defined in the given environment.
diff --git a/lib/src/main/java/io/github/aloussase/configvalidator/reporting/ResultsReporter.java b/lib/src/main/java/io/github/aloussase/configvalidator/reporting/ResultsReporter.java
index 5f94be1..67d14bf 100644
--- a/lib/src/main/java/io/github/aloussase/configvalidator/reporting/ResultsReporter.java
+++ b/lib/src/main/java/io/github/aloussase/configvalidator/reporting/ResultsReporter.java
@@ -4,6 +4,10 @@ import io.github.aloussase.configvalidator.Validation;
 
 import java.util.List;
 
+/**
+ * Implementors of this interface should be able to take a list of {@link Validation}s
+ * and report it in some arbitrary way (e.g. through an HTML document, console output; etc.).
+ */
 public interface ResultsReporter {
     /**
      * Report the results of configuration variable configuration.
diff --git a/lib/src/main/java/io/github/aloussase/configvalidator/rules/parser/RuleParser.java b/lib/src/main/java/io/github/aloussase/configvalidator/rules/parser/RuleParser.java
index 0c6cb13..58bdaed 100644
--- a/lib/src/main/java/io/github/aloussase/configvalidator/rules/parser/RuleParser.java
+++ b/lib/src/main/java/io/github/aloussase/configvalidator/rules/parser/RuleParser.java
@@ -4,9 +4,18 @@ import io.github.aloussase.configvalidator.rules.Rule;
 
 import java.util.List;
 
+/**
+ * Implementors of this interface should be able to take a string representing
+ * validation rules in a given format (e.g. JSON, YAML or a custom format), parse it
+ * and generate a list of {@link  Rule}.
+ */
 public interface RuleParser {
     /**
      * Parse a list of rules from a given string source.
+     * <p>
+     * Any parsing errors should be communicated to the end user in the form
+     * of exceptions. Better error handling and reporting is planned for future
+     * versions.
      *
      * @param source The string from which to parse the rules.
      * @return A list of Rules.