Update javadocs

easy-rules-core/src/main/java/org/jeasy/rules/annotation/Action.java

@@ -32,7 +32,6 @@ import java.lang.annotation.*;
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */
-
 @Inherited
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)

easy-rules-core/src/main/java/org/jeasy/rules/annotation/Condition.java

@@ -31,7 +31,6 @@ import java.lang.annotation.*;
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */
-
 @Inherited
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)

easy-rules-core/src/main/java/org/jeasy/rules/annotation/Fact.java

@@ -30,7 +30,6 @@ import java.lang.annotation.*;
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */
-
 @Inherited
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.PARAMETER})

easy-rules-core/src/main/java/org/jeasy/rules/annotation/Priority.java

@@ -31,7 +31,6 @@ import java.lang.annotation.*;
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */
-
 @Inherited
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)

easy-rules-core/src/main/java/org/jeasy/rules/annotation/Rule.java

@@ -30,14 +30,13 @@ import java.lang.annotation.*;
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */
-
 @Inherited
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 public @interface Rule {
 
     /**
-     * The rule name which must be unique within an rules registry.
+     * The rule name which must be unique within a rules registry.
      * @return The rule name
      */
     String name() default org.jeasy.rules.api.Rule.DEFAULT_NAME;

easy-rules-core/src/main/java/org/jeasy/rules/api/Action.java

@@ -32,7 +32,7 @@ package org.jeasy.rules.api;
 public interface Action {
 
     /**
-     * Execute the action when the rule evaluates to true.
+     * Execute the action when the rule's condition evaluates to true.
      *
      * @param facts known at the time of execution of the action
      * @throws Exception when unable to execute the action

easy-rules-core/src/main/java/org/jeasy/rules/api/Fact.java

@@ -38,6 +38,11 @@ public class Fact<T> {
 	
 	private final T value;
 
+	/**
+	 * Create a new fact.
+	 * @param name of the fact
+	 * @param value of the fact
+	 */
 	public Fact(String name, T value) {
 		Objects.requireNonNull(name, "name must not be null");
 		Objects.requireNonNull(value, "value must not be null");
@@ -45,10 +50,18 @@ public class Fact<T> {
 		this.value = value;
 	}
 
+	/**
+	 * Get the fact name.
+	 * @return fact name
+	 */
 	public String getName() {
 		return name;
 	}
 
+	/**
+	 * Get the fact value.
+	 * @return fact value
+	 */
 	public T getValue() {
 		return value;
 	}

easy-rules-core/src/main/java/org/jeasy/rules/api/Facts.java

@@ -26,7 +26,8 @@ package org.jeasy.rules.api;
 import java.util.*;
 
 /**
- * Represents a set of named facts. Facts have unique names within a <code>Facts</code> object.
+ * This class encapsulates a set of facts and represents a facts namespace.
+ * Facts have unique names within a <code>Facts</code> object.
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */
@@ -37,8 +38,8 @@ public class Facts implements Iterable<Fact<?>> {
     /**
      * Add a fact, replacing any fact with the same name.
      *
-     * @param name of the fact to add
-     * @param value of the fact to add
+     * @param name of the fact to add, must not be null
+     * @param value of the fact to add, must not be null
      */
     public <T> void put(String name, T value) {
         Objects.requireNonNull(name, "fact name must not be null");
@@ -53,7 +54,7 @@ public class Facts implements Iterable<Fact<?>> {
     /**
      * Add a fact, replacing any fact with the same name.
      * 
-     * @param fact to add
+     * @param fact to add, must not be null
      */
     public <T> void add(Fact<T> fact) {
         Objects.requireNonNull(fact, "fact must not be null");
@@ -67,7 +68,7 @@ public class Facts implements Iterable<Fact<?>> {
     /**
      * Remove a fact by name.
      *
-     * @param factName name of the fact to remove
+     * @param factName name of the fact to remove, must not be null
      */
     public void remove(String factName) {
         Objects.requireNonNull(factName, "fact name must not be null");
@@ -80,7 +81,7 @@ public class Facts implements Iterable<Fact<?>> {
     /**
      * Remove a fact.
      *
-     * @param fact to remove
+     * @param fact to remove, must not be null
      */
     public <T> void remove(Fact<T> fact) {
         Objects.requireNonNull(fact, "fact must not be null");
@@ -91,9 +92,10 @@ public class Facts implements Iterable<Fact<?>> {
      * Get the value of a fact by its name. This is a convenience method provided
      * as a short version of {@code getFact(factName).getValue()}.
      *
-     * @param factName name of the fact
+     * @param factName name of the fact, must not be null
      * @param <T> type of the fact's value
-     * @return the value of the fact having the given name, or {@code null} if there is no fact with the given name
+     * @return the value of the fact having the given name, or null if there is
+     * no fact with the given name
      */
     @SuppressWarnings("unchecked")
     public <T> T get(String factName) {
@@ -108,8 +110,8 @@ public class Facts implements Iterable<Fact<?>> {
     /**
      * Get a fact by name.
      *
-     * @param factName name of the fact
-     * @return the fact having the given name, or {@code null} if there is no fact with the given name
+     * @param factName name of the fact, must not be null
+     * @return the fact having the given name, or null if there is no fact with the given name
      */
     public Fact<?> getFact(String factName) {
         Objects.requireNonNull(factName, "fact name must not be null");

easy-rules-core/src/main/java/org/jeasy/rules/api/Rule.java

@@ -24,9 +24,10 @@
 package org.jeasy.rules.api;
 
 /**
- * Abstraction for a rule that can be fired by the rules engine.
+ * Abstraction for a rule that can be fired by a rules engine.
  *
- * Rules are registered in a rule set of type <code>Rules</code> in which they must have a <strong>unique</strong> name.
+ * Rules are registered in a namespace of rule of type {@link Rules}
+ * in which they must have a <strong>unique</strong> name.
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */
@@ -72,7 +73,7 @@ public interface Rule extends Comparable<Rule> {
     }
 
     /**
-     * Rule conditions abstraction : this method encapsulates the rule's conditions.
+     * This method implements the rule's condition(s).
      * <strong>Implementations should handle any runtime exception and return true/false accordingly</strong>
      *
      * @return true if the rule should be applied given the provided facts, false otherwise
@@ -80,8 +81,8 @@ public interface Rule extends Comparable<Rule> {
     boolean evaluate(Facts facts);
 
     /**
-     * Rule actions abstraction : this method encapsulates the rule's actions.
-     * @throws Exception thrown if an exception occurs during actions performing
+     * This method implements the rule's action(s).
+     * @throws Exception thrown if an exception occurs when performing action(s)
      */
     void execute(Facts facts) throws Exception;
 

easy-rules-core/src/main/java/org/jeasy/rules/api/RuleListener.java

@@ -24,7 +24,7 @@
 package org.jeasy.rules.api;
 
 /**
- * A listener for rules execution events.
+ * A listener for rule execution events.
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */

easy-rules-core/src/main/java/org/jeasy/rules/api/Rules.java

@@ -69,7 +69,7 @@ public class Rules implements Iterable<Rule> {
     /**
      * Register a new rule.
      *
-     * @param rule to register
+     * @param rule to register, must not be null
      */
     public void register(Object rule) {
         Objects.requireNonNull(rule);
@@ -79,7 +79,7 @@ public class Rules implements Iterable<Rule> {
     /**
      * Unregister a rule.
      *
-     * @param rule to unregister
+     * @param rule to unregister, must not be null
      */
     public void unregister(Object rule) {
         Objects.requireNonNull(rule);
@@ -89,7 +89,7 @@ public class Rules implements Iterable<Rule> {
     /**
      * Unregister a rule by name.
      *
-     * @param ruleName the name of the rule to unregister
+     * @param ruleName name of the rule to unregister, must not be null
      */
     public void unregister(final String ruleName) {
         Objects.requireNonNull(ruleName);
@@ -115,6 +115,11 @@ public class Rules implements Iterable<Rule> {
         rules.clear();
     }
 
+    /**
+     * Return an iterator on the rules set. It is not intended to remove rules
+     * using this iterator.
+     * @return an iterator on the rules set
+     */
     @Override
     public Iterator<Rule> iterator() {
         return rules.iterator();

easy-rules-core/src/main/java/org/jeasy/rules/api/RulesEngineListener.java

@@ -34,7 +34,9 @@ public interface RulesEngineListener {
 
     /**
      * Triggered before evaluating the rule set.
-     * <strong>When this listener is used with a {@link InferenceRulesEngine}, this method will be triggered before the evaluation of each candidate rule set in each iteration.</strong>
+     * <strong>When this listener is used with a {@link InferenceRulesEngine},
+     * this method will be triggered before the evaluation of each candidate rule
+     * set in each iteration.</strong>
      *
      * @param rules to fire
      * @param facts present before firing rules
@@ -43,7 +45,9 @@ public interface RulesEngineListener {
 
     /**
      * Triggered after executing the rule set
-     * <strong>When this listener is used with a {@link InferenceRulesEngine}, this method will be triggered after the execution of each candidate rule set in each iteration.</strong>
+     * <strong>When this listener is used with a {@link InferenceRulesEngine},
+     * this method will be triggered after the execution of each candidate rule
+     * set in each iteration.</strong>
      *
      * @param rules fired
      * @param facts present after firing rules

easy-rules-core/src/main/java/org/jeasy/rules/core/AbstractRulesEngine.java

@@ -52,6 +52,10 @@ public abstract class AbstractRulesEngine implements RulesEngine {
         this.rulesEngineListeners = new ArrayList<>();
     }
 
+    /**
+     * Return a copy of the rules engine parameters.
+     * @return copy of the rules engine parameters
+     */
     @Override
     public RulesEngineParameters getParameters() {
         return new RulesEngineParameters(
@@ -62,11 +66,19 @@ public abstract class AbstractRulesEngine implements RulesEngine {
         );
     }
 
+    /**
+     * Return an unmodifiable list of the registered rule listeners.
+     * @return an unmodifiable list of the registered rule listeners
+     */
     @Override
     public List<RuleListener> getRuleListeners() {
         return Collections.unmodifiableList(ruleListeners);
     }
 
+    /**
+     * Return an unmodifiable list of the registered rules engine listeners
+     * @return an unmodifiable list of the registered rules engine listeners
+     */
     @Override
     public List<RulesEngineListener> getRulesEngineListeners() {
         return Collections.unmodifiableList(rulesEngineListeners);

easy-rules-core/src/main/java/org/jeasy/rules/core/DefaultRulesEngine.java

@@ -33,9 +33,9 @@ import java.util.Map;
 /**
  * Default {@link RulesEngine} implementation.
  *
- * This implementation handles a set of rules with unique names.
- *
  * Rules are fired according to their natural order which is priority by default.
+ * This implementation iterates over the sorted set of rules, evaluates the condition
+ * of each rule and executes its actions if the condition evaluates to true.
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */

easy-rules-core/src/main/java/org/jeasy/rules/core/InferenceRulesEngine.java

@@ -32,9 +32,9 @@ import java.util.*;
 /**
  * Inference {@link RulesEngine} implementation.
  *
- * Rules are selected based on given facts and fired according to their natural order which is priority by default.
- *
- * The engine continuously selects and fires rules until no more rules are applicable.
+ * Rules are selected based on given facts and fired according to their natural
+ * order which is priority by default. This implementation continuously selects
+ * and fires rules until no more rules are applicable.
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */

easy-rules-mvel/src/main/java/org/jeasy/rules/mvel/MVELAction.java

@@ -33,7 +33,8 @@ import org.slf4j.LoggerFactory;
 import java.io.Serializable;
 
 /**
- * This class is an implementation of {@link Action} that uses <a href="https://github.com/mvel/mvel">MVEL</a> to execute the action.
+ * This class is an implementation of {@link Action} that uses
+ * <a href="https://github.com/mvel/mvel">MVEL</a> to execute the action.
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */

easy-rules-mvel/src/main/java/org/jeasy/rules/mvel/MVELCondition.java

@@ -31,7 +31,8 @@ import org.mvel2.ParserContext;
 import java.io.Serializable;
 
 /**
- * This class is an implementation of {@link Condition} that uses <a href="https://github.com/mvel/mvel">MVEL</a> to evaluate the condition.
+ * This class is an implementation of {@link Condition} that uses
+ * <a href="https://github.com/mvel/mvel">MVEL</a> to evaluate the condition.
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */

easy-rules-mvel/src/main/java/org/jeasy/rules/mvel/MVELRule.java

@@ -34,7 +34,8 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * A {@link org.jeasy.rules.api.Rule} implementation that uses <a href="https://github.com/mvel/mvel">MVEL</a> to evaluate and execute the rule.
+ * A {@link org.jeasy.rules.api.Rule} implementation that uses
+ * <a href="https://github.com/mvel/mvel">MVEL</a> to evaluate and execute the rule.
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */

easy-rules-mvel/src/main/java/org/jeasy/rules/mvel/MVELRuleFactory.java

@@ -76,7 +76,7 @@ public class MVELRuleFactory extends AbstractRuleFactory {
      * If no rule definitions are found, a {@link IllegalArgumentException} will be thrown.
      * If more than a rule is defined in the descriptor, the first rule will be returned.
      *
-     * @param ruleDescriptor as a Reader
+     * @param ruleDescriptor descriptor of rule definition
      * @return a new rule
      */
     public Rule createRule(Reader ruleDescriptor) throws Exception {
@@ -88,9 +88,9 @@ public class MVELRuleFactory extends AbstractRuleFactory {
     }
 
     /**
-     * Create a set of {@link MVELRule} from a Reader.
+     * Create a set of {@link MVELRule} from a rule descriptor.
      *
-     * @param rulesDescriptor as a Reader
+     * @param rulesDescriptor descriptor of rule definitions
      * @return a set of rules
      */
     public Rules createRules(Reader rulesDescriptor) throws Exception {

easy-rules-spel/src/main/java/org/jeasy/rules/spel/SpELAction.java

@@ -36,7 +36,9 @@ import org.springframework.expression.spel.standard.SpelExpressionParser;
 import org.springframework.expression.spel.support.StandardEvaluationContext;
 
 /**
- * This class is an implementation of {@link Action} that uses <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#expressions">SpEL</a> to execute the action.
+ * This class is an implementation of {@link Action} that uses
+ * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#expressions">SpEL</a>
+ * to execute the action.
  *
  * Each fact is set as a variable in the {@link org.springframework.expression.EvaluationContext}.
  *

easy-rules-spel/src/main/java/org/jeasy/rules/spel/SpELCondition.java

@@ -34,7 +34,9 @@ import org.springframework.expression.spel.standard.SpelExpressionParser;
 import org.springframework.expression.spel.support.StandardEvaluationContext;
 
 /**
- * This class is an implementation of {@link Condition} that uses <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#expressions">SpEL</a> to evaluate the condition.
+ * This class is an implementation of {@link Condition} that uses
+ * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#expressions">SpEL</a>
+ * to evaluate the condition.
  *
  * Each fact is set as a variable in the {@link org.springframework.expression.EvaluationContext}.
  *

easy-rules-spel/src/main/java/org/jeasy/rules/spel/SpELRule.java

@@ -36,7 +36,9 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * A {@link Rule} implementation that uses <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#expressions">SpEL</a> to evaluate and execute the rule.
+ * A {@link Rule} implementation that uses 
+ * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#expressions">SpEL</a>
+ * to evaluate and execute the rule.
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */

easy-rules-spel/src/main/java/org/jeasy/rules/spel/SpELRuleFactory.java

@@ -107,7 +107,7 @@ public class SpELRuleFactory extends AbstractRuleFactory {
      * If no rule definitions are found, a {@link IllegalArgumentException} will be thrown.
      * If more than a rule is defined in the descriptor, the first rule will be returned.
      *
-     * @param ruleDescriptor as a Reader
+     * @param ruleDescriptor descriptor of rule definition
      * @return a new rule
      */
     public Rule createRule(Reader ruleDescriptor) throws Exception {
@@ -121,7 +121,7 @@ public class SpELRuleFactory extends AbstractRuleFactory {
     /**
      * Create a set of {@link SpELRule} from a Reader.
      *
-     * @param rulesDescriptor as a Reader
+     * @param rulesDescriptor descriptor of rule definitions
      * @return a set of rules
      */
     public Rules createRules(Reader rulesDescriptor) throws Exception {

easy-rules-support/src/main/java/org/jeasy/rules/support/RuleDefinition.java

@@ -32,7 +32,7 @@ import java.util.List;
  * Rule definition as defined in a rule descriptor.
  * This class encapsulates the static definition of a {@link Rule}.
  *
- * A rule definition is produced by a {@code RuleDefinitionReader}
+ * Rule definitions are produced by a {@code RuleDefinitionReader}s
  * and consumed by rule factories to create rules.
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)

easy-rules-support/src/main/java/org/jeasy/rules/support/composite/ActivationRuleGroup.java

@@ -29,8 +29,9 @@ import org.jeasy.rules.api.Rule;
 import java.util.TreeSet;
 
 /**
- * An activation rule group is a composite rule that fires the first applicable rule and ignores other rules in
- * the group (XOR logic). Rules are first sorted by their natural order (priority by default) within the group.
+ * An activation rule group is a composite rule that fires the first applicable 
+ * rule and ignores other rules in the group (XOR logic).
+ * Rules are first sorted by their natural order (priority by default) within the group.
  *
  * @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */

easy-rules-support/src/main/java/org/jeasy/rules/support/composite/ConditionalRuleGroup.java

@@ -33,9 +33,10 @@ import java.util.List;
 import java.util.Set;
 
 /**
- * A conditional rule group is a composite rule where the rule with the highest priority acts as a condition:
- * if the rule with the highest priority evaluates to true, then we try to evaluate the rest of the rules
- * and execute the ones that evaluate to true.
+ * A conditional rule group is a composite rule where the rule with the highest 
+ * priority acts as a condition: if the rule with the highest priority evaluates
+ * to true, then we try to evaluate the rest of the rules and execute the ones
+ * that evaluate to true.
  *
  * @author Dag Framstad (dagframstad@gmail.com)
  */
@@ -81,9 +82,11 @@ public class ConditionalRuleGroup extends CompositeRule {
     }
 
     /**
-     * A path rule will trigger all it's rules if the path rule's condition is true.
+     * A conditional rule group will trigger all its composing rules if the condition
+     * of the rule with highest priority evaluates to true.
+     * 
      * @param facts The facts.
-     * @return true if the path rules condition is true.
+     * @return true if the conditions of all composing rules evaluate to true
      */
     @Override
     public boolean evaluate(Facts facts) {
@@ -101,8 +104,9 @@ public class ConditionalRuleGroup extends CompositeRule {
     }
 
     /**
-     * When a conditional rule group is applied, all rules that evaluated to true are performed
-     * in their natural order, but with the conditional rule (the one with the highest priority) first.
+     * When a conditional rule group is executed, all rules that evaluated to true
+     * are performed in their natural order, but with the conditional rule 
+     * (the one with the highest priority) first.
      *
      * @param facts The facts.
      *
@@ -118,7 +122,7 @@ public class ConditionalRuleGroup extends CompositeRule {
 
     private Rule getRuleWithHighestPriority() {
         List<Rule> copy = sort(rules);
-        // make sure that we only have one rule with the highest priority
+        // make sure we only have one rule with the highest priority
         Rule highest = copy.get(0);
         if (copy.size() > 1 && copy.get(1).getPriority() == highest.getPriority()) {
            throw new IllegalArgumentException("Only one rule can have highest priority");

easy-rules-support/src/main/java/org/jeasy/rules/support/composite/UnitRuleGroup.java

@@ -27,7 +27,8 @@ import org.jeasy.rules.api.Facts;
 import org.jeasy.rules.api.Rule;
 
 /**
- * A unit rule group is a composite rule that acts as a unit: Either all rules are applied or nothing is applied.
+ * A unit rule group is a composite rule that acts as a unit: Either all rules are
+ * applied or nothing is applied (all or nothing semantic).
  *
  *  @author Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
  */