some cleanup

src/main/java/de/kosit/validationtool/api/AcceptRecommendation.java

@@ -1,21 +1,22 @@
 package de.kosit.validationtool.api;
 
 /**
- * Tri-state describtion of a Recommendation.
+ * Tri-state recommendation whether to accept the {@link Input} or not.
  */
 public enum AcceptRecommendation {
+
     /**
      * The evaluation of the overall validation could not be computed.
      */
     UNDEFINED,
 
     /**
-     * Recommendation is to accept input based on the evaluation of the overall validation.
+     * Recommendation is to accept {@link Input} based on the evaluation of the overall validation.
      */
     ACCEPTABLE,
 
     /**
-     * Recommendation is to reject input based on the evaluation of the overall validation.
+     * Recommendation is to reject {@link Input}  based on the evaluation of the overall validation.
      */
     REJECT
 }

src/main/java/de/kosit/validationtool/api/Configuration.java

@@ -12,15 +12,15 @@ import de.kosit.validationtool.impl.Scenario;
 /**
  * Configuration of the actual {@link Check} instance. This is an interface and can be implemented by custom
  * configuration classes. There are two implementations supported out of the box:
- * 
+ *
  * <ol>
  * <li>{@link ConfigurationLoader} implements loading {@link Check} configurations from a scenario.xml file</li>
  * <li>Using a builder style api {@link de.kosit.validationtool.config.ConfigurationBuilder}to configure the
  * {@link Check}</li>
  * </ol>
- * 
+ * <p>
  * Both methods can be used via convinience methods. See below.
- * 
+ *
  * @author Andreas Penski
  */
 
@@ -28,51 +28,57 @@ public interface Configuration {
 
     /**
      * Returns a list of configured scenarios.
-     * 
+     *
      * @return the list of scenarios
      */
     List<Scenario> getScenarios();
 
     /**
      * Returns the configured fallback scenario to use, in case no configured scenario match.
-     * 
+     *
      * @return the fallback scenario
      */
     Scenario getFallbackScenario();
 
     /**
      * Returns the author of this configuration.
-     * 
+     *
      * @return the author
      */
     String getAuthor();
 
     /**
      * Returns the name of the specification
-     * 
+     *
      * @return the name
      */
     String getName();
 
     /**
      * The creation date of the config
-     * 
+     *
      * @return the date
      */
     String getDate();
 
+    /**
+     * Add some additional parameters to the validator configuration. Parameter usage depends on actual implementation of
+     * {@link Check}
+     *
+     * @return
+     */
     Map<String, Object> getAdditionalParameters();
 
     /**
      * The content repository including resolving strategies.
-     * 
+     *
      * @return the configured {@link ContentRepository}
      */
     ContentRepository getContentRepository();
 
     /**
      * Loads an XML based scenario definition from the file specified via URI.
-     * 
+     *
      * @param scenarioDefinition the XML file with scenario definition
      * @return the loaded configuration
      */
@@ -93,7 +99,7 @@ public interface Configuration {
 
     /**
      * Creates a {@link Configuration} based on a builder style API using {@link ConfigurationBuilder}
-     * 
+     *
      * @return the Builder
      */
     static ConfigurationBuilder create() {

src/main/java/de/kosit/validationtool/api/ResolvingConfigurationStrategy.java

@@ -10,12 +10,15 @@ import javax.xml.validation.Validator;
 import net.sf.saxon.s9api.Processor;
 
 /**
- * Centralized construction and configuration of XML related infrastructore components. The KoSIT Validator provides out
- * of the box implementaions with various security levels.
+ * Centralized construction and configuration of XML related infrastructure components. This interface allows to use
+ * custom implementations and configurations of internal xml related factories and objects.
+ * 
+ * The KoSIT Validator provides out of the box implementations with various security levels based on openjdk SAX stack.
  * 
  * If you decide to implement a custom strategy, please be aware of XML security within your stack. The validator
  * components beyond this strategy asume secured implementation of the interfaces provided by this strategy. There is no
- * effort to mitigate or prevent xml related security issues such as XXE, loading external sources etc.
+ * effort to mitigate or prevent xml related security issues such as XXE, loading external sources etc. Your would be
+ * responsible for this!
  * 
  * @see de.kosit.validationtool.impl.ResolvingMode
  * @author Andreas Penski
@@ -35,12 +38,14 @@ public interface ResolvingConfigurationStrategy {
      * leverages the saxon s9api for internal processing e.g. xml reading and writing. So this is the main object to secure
      * for reading, transforming and writing xml files.
      * 
+     * Note: you need exactly one instance for all validator related processing.
+     * 
      * @return a preconfigured {@link Processor}
      */
     Processor getProcessor();
 
     /**
-     * Creates a specific implementation for resolving referenced objects in XML files. The URIResolver, it is used for
+     * Creates a specific implementation for resolving referenced objects in XML files. The URIResolver is used for
      * dereferencing an absolute URI (after resolution) to return a {@link javax.xml.transform.Source}. It <b>can</b> be
      * used for resolving relative URIs against a base URI or restrict access to certain URIs.
      * <p>
@@ -48,6 +53,7 @@ public interface ResolvingConfigurationStrategy {
      * <code>xsl:import-schema</code> declarations.
      * </p>
      * 
+     * @param scenarioRepository an optional repository, your implementation might not need this
      * @return a preconfigured {@link URIResolver}
      */
     URIResolver createResolver(URI scenarioRepository);