Add documentation for vDmnFunctions

dmnverifierapi/src/main/java/de/unikoblenz/fgbks/core/dmn/domain/vdmn/utils/VDmnFunctions.java

@@ -15,8 +15,19 @@ import java.util.List;
 import java.util.stream.Collectors;
 import org.apache.commons.lang3.Validate;
 
+/**
+ * VDmnFunctions is a utility class, providing functions for the VDmn classes.
+ */
 public class VDmnFunctions {
 
+  /**
+   * Generate a list of {@link VDmnColumn}, which are in the {@link VDmnDefinition} and has the
+   * defined type ({@link VTypeRef}).
+   *
+   * @param dmnDefinition the {@link VDmnDefinition}
+   * @param vTypeRef the type as {@link VTypeRef}
+   * @return a new list of {@link VDmnColumn}s
+   */
   public static List<VDmnColumn> getColumnsByTypeRef(
       VDmnDefinition dmnDefinition, VTypeRef vTypeRef) {
     Validate.notNull(dmnDefinition);
@@ -39,29 +50,68 @@ public class VDmnFunctions {
     return columns;
   }
 
+  /**
+   * Generate a list of all output columns ({@link VDmnOutputColumn}) of the given {@link
+   * VDmnDefinition}.
+   *
+   * @param dmnDefinition the {@link VDmnDefinition}
+   * @return a new list with all output columns ({@link VDmnOutputColumn})
+   */
   public static List<VDmnOutputColumn> getOutputColumns(VDmnDefinition dmnDefinition) {
     return Validate.notNull(dmnDefinition).getDmnDecisions().stream()
         .flatMap(v -> v.getDmnDecisionTable().getOutputColumns().stream())
         .collect(Collectors.toList());
   }
 
+  /**
+   * Generate a list of {@link VDmnValue}s, which are in the specified {@link VDmnColumn} and which
+   * are filtered with the given list of {@link VDmnRule}.
+   *
+   * @param column the {@link VDmnColumn}, containing the {@link VDmnValue}s
+   * @param rules the list of {@link VDmnRule}
+   * @return a new list of {@link VDmnValue}
+   */
   public static List<VDmnValue> getColumnValuesInRules(VDmnColumn column, List<VDmnRule> rules) {
     return getColumnValuesInRuleIds(
         column, rules.stream().map(VDmnRule::getRuleId).collect(Collectors.toList()));
   }
 
+  /**
+   * Generate a list of {@link VDmnValue}s, which are in the specified {@link VDmnColumn} and which
+   * are filtered with the given list of {@link RuleId}.
+   *
+   * @param column the {@link VDmnColumn}, containing the {@link VDmnValue}s
+   * @param ruleIds the list of {@link RuleId}
+   * @return a new list of {@link VDmnValue}
+   */
   public static List<VDmnValue> getColumnValuesInRuleIds(VDmnColumn column, List<RuleId> ruleIds) {
     return column.getValues().stream()
         .filter(v -> ruleIds.contains(v.getRuleId()))
         .collect(Collectors.toList());
   }
 
+  /**
+   * Generate a list of {@link VDmnInputValue}s, which are in the specified {@link VDmnInputColumn}
+   * and which are filtered with the given list of {@link VDmnInputValue}.
+   *
+   * @param column the {@link VDmnInputColumn}, containing the {@link VDmnInputValue}s
+   * @param rules the list of {@link VDmnRule}
+   * @return a new list of {@link VDmnInputValue}
+   */
   public static List<VDmnInputValue> getColumnValuesInRules(
       VDmnInputColumn column, List<VDmnRule> rules) {
     return getColumnValuesInRuleIds(
         column, rules.stream().map(VDmnRule::getRuleId).collect(Collectors.toList()));
   }
 
+  /**
+   * Generate a list of {@link VDmnInputValue}s, which are in the specified {@link VDmnInputColumn}
+   * and which are filtered with the given list of {@link RuleId}.
+   *
+   * @param column the {@link VDmnInputColumn}, containing the {@link VDmnInputValue}s
+   * @param ruleIds the list of {@link RuleId}
+   * @return a new list of {@link VDmnInputValue}
+   */
   public static List<VDmnInputValue> getColumnValuesInRuleIds(
       VDmnInputColumn column, List<RuleId> ruleIds) {
     return column.getInputValues().stream()
@@ -69,8 +119,14 @@ public class VDmnFunctions {
         .collect(Collectors.toList());
   }
 
+  /**
+   * Check, if the given {@link VDmnRule}s have different conclusions.
+   *
+   * @param rules the {@link VDmnRule}s to check
+   * @return true, if at least one rule has a different conclusion
+   */
   public static boolean differentConclusions(List<VDmnRule> rules) {
-    if (rules.size() == 0) {
+    if (Validate.notNull(rules).size() == 0) {
       return false;
     }
     VDmnRule refRule = rules.get(0);
@@ -82,8 +138,26 @@ public class VDmnFunctions {
     return false;
   }
 
+  /**
+   * Check, if the given {@link VDmnRule}s have different conclusions.
+   *
+   * @param rules the {@link VDmnRule}s to check
+   * @return true, if at least one rule has a different conclusion
+   */
+  public static boolean sameConclusions(List<VDmnRule> rules) {
+    return !differentConclusions(rules);
+  }
+
+  /**
+   * Check, if the given two {@link VDmnRule}s have different conclusions (outputs).
+   *
+   * @param oneRule the first {@link VDmnRule} to check
+   * @param otherRule the second {@link VDmnRule} to check
+   * @return true, if both rules has different conclusions.
+   */
   public static boolean differentConclusions(VDmnRule oneRule, VDmnRule otherRule) {
-    if (oneRule.getDmnOutputValues().size() != otherRule.getDmnOutputValues().size()) {
+    if (Validate.notNull(oneRule).getDmnOutputValues().size()
+        != Validate.notNull(otherRule).getDmnOutputValues().size()) {
       return true;
     }
     for (int i = 0; i < oneRule.getDmnOutputValues().size(); i++) {
@@ -98,6 +172,24 @@ public class VDmnFunctions {
     return false;
   }
 
+  /**
+   * Check, if the given two {@link VDmnRule}s have the same conclusions (outputs).
+   *
+   * @param oneRule the first {@link VDmnRule} to check
+   * @param otherRule the second {@link VDmnRule} to check
+   * @return true, if both rules has the same conclusions.
+   */
+  public static boolean sameConclusions(VDmnRule oneRule, VDmnRule otherRule) {
+    return !differentConclusions(oneRule, otherRule);
+  }
+
+  /**
+   * Get a nested list of {@link VDmnRule} from the given {@link VDmnDecisionTable}. Each element in
+   * the list is a cluster of rules, which has the same conclusion.
+   *
+   * @param dmnDecisionTable the {@link VDmnDecisionTable}
+   * @return the nested list of {@link VDmnRule}
+   */
   public static List<List<VDmnRule>> getRuleClustersWithIdenticalOutput(
       VDmnDecisionTable dmnDecisionTable) {
     List<List<VDmnRule>> clusters = new ArrayList<>();
@@ -109,7 +201,7 @@ public class VDmnFunctions {
         remainingRules.set(i, null);
         for (int u = i + 1; u < remainingRules.size(); u++) {
           if (remainingRules.get(u) != null
-              && !differentConclusions(newCluster.get(0), remainingRules.get(u))) {
+              && sameConclusions(newCluster.get(0), remainingRules.get(u))) {
             newCluster.add(remainingRules.get(u));
             remainingRules.set(u, null);
           }