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 e98ac25e8812eff4a75f25bf3866bc4cf43e92b3..e8ed0ef60d394bff6771f2897e1e8bd1ae5e3172 100644 (file)
--- 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 5f94be1eda47e792d5191457c2e3367b651baf51..67d14bfac2aaf510d11f41e9a65a1843a5519ee8 100644 (file)
--- 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 0c6cb132b60748a8f585404e073eed3a000ee7af..58bdaedd62b16b5785576a1bb2bf8fca1af22577 100644 (file)
--- 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.