Added missing javadocs

Author: “jklein94”

.gitignore

@@ -31,8 +31,8 @@ bin/
 .metadata/.plugins/org.eclipse.m2e.logback.configuration/0.log
 .metadata/version.ini
 *.resources
-constructor.json
-skipped_files.txt
-warnings.json
+testBuild
 
-*.txt
+
+gurobi-9.1.0.jar
+isula-1.1.1.jar

org-tweetyproject-arg-dung/src/main/java/org/tweetyproject/arg/dung/examples/PrincipleExample.java

@@ -31,13 +31,15 @@
 import java.util.HashSet;
 
 /**
- * Example code for checking (non-)satisfaction of {@link Principle} for argumentation semantics
+ * Example code for checking (non-)satisfaction of {@link Principle} for
+ * argumentation semantics
  *
  * @author Lars Bengel
  */
 public class PrincipleExample {
     /**
      * Execute the example
+     *
      * @param args cmdline arguments
      */
     public static void main(String[] args) {
@@ -67,9 +69,29 @@ public static void main(String[] args) {
         evaluateReasoner(new SimpleAdmissibleReasoner(), all_principles);
     }
 
+    /**
+     * Evaluates a given abstract extension reasoner against a collection of
+     * principles (postulates).
+     * <p>
+     * This method uses a {@link DungTheoryGenerator} to generate Dung argumentation
+     * frameworks
+     * and evaluates how well the provided {@link AbstractExtensionReasoner}
+     * satisfies the given principles.
+     * The evaluation is conducted using a {@link PostulateEvaluator}, which applies
+     * the principles to
+     * generated frameworks and assesses the reasoner's performance.
+     * </p>
+     *
+     * @param reasoner   The {@link AbstractExtensionReasoner} to be evaluated. This
+     *                   reasoner
+     *                   provides extensions for argumentation frameworks.
+     * @param principles A collection of {@link Principle} objects representing the
+     *                   postulates
+     *                   against which the reasoner will be evaluated.
+     */
     public static void evaluateReasoner(AbstractExtensionReasoner reasoner, Collection<Principle> principles) {
         DungTheoryGenerator generator = new EnumeratingDungTheoryGenerator();
-        PostulateEvaluator<Argument,DungTheory> evaluator = new PostulateEvaluator<>(generator, reasoner);
+        PostulateEvaluator<Argument, DungTheory> evaluator = new PostulateEvaluator<>(generator, reasoner);
         evaluator.addAllPostulates(principles);
         System.out.println(evaluator.evaluate(4000, false).prettyPrint());
     }

org-tweetyproject-arg-dung/src/main/java/org/tweetyproject/arg/dung/examples/QualifiedSemanticsReasonerExample.java

@@ -33,41 +33,60 @@
 public class QualifiedSemanticsReasonerExample {
     /**
      * Execute the example
+     *
      * @param args cmdline arguments
      */
     public static void main(String[] args) {
         Semantics semantics = Semantics.CO;
         DungTheory theory = example2();
 
         System.out.println(theory.prettyPrint());
-        Collection<Extension<DungTheory>> exts = AbstractExtensionReasoner.getSimpleReasonerForSemantics(semantics).getModels(theory);
+        Collection<Extension<DungTheory>> exts = AbstractExtensionReasoner.getSimpleReasonerForSemantics(semantics)
+                .getModels(theory);
         Collection<Extension<DungTheory>> exts_q = new QualifiedReasoner(semantics).getModels(theory);
         Collection<Extension<DungTheory>> exts_sq = new SemiQualifiedReasoner(semantics).getModels(theory);
         System.out.printf("%s: %s%n", semantics.description(), exts);
         System.out.printf("qualified %s: %s%n", semantics.description(), exts_q);
         System.out.printf("semi-qualified %s: %s%n", semantics.description(), exts_sq);
     }
 
+    /**
+     * Creates and returns an example of a Dung argumentation framework (Dung
+     * Theory).
+     * <p>
+     * This example consists of three arguments: {@code a}, {@code b}, and
+     * {@code c}.
+     *
+     * @return A {@link DungTheory} object representing the defined argumentation
+     *         framework.
+     */
     public static DungTheory example1() {
         Argument a = new Argument("a");
         Argument b = new Argument("b");
         Argument c = new Argument("c");
         DungTheory theory = new DungTheory();
-        theory.add(a,b,c);
+        theory.add(a, b, c);
         theory.addAttack(a, a);
         theory.addAttack(a, b);
         theory.addAttack(b, c);
 
         return theory;
     }
 
+    /**
+     * Creates and returns an example of a Dung argumentation framework (Dung
+     * Theory).
+     *
+     * @return A {@link DungTheory} object representing the defined argumentation
+     *         framework.
+     */
     public static DungTheory example2() {
         Argument d = new Argument("d");
         Argument e = new Argument("e");
         Argument f = new Argument("f");
         Argument g = new Argument("g");
         DungTheory theory = new DungTheory();
-        theory.add(d,e,f,g);
+        theory.add(d, e, f, g);
         theory.addAttack(d, e);
         theory.addAttack(e, d);
         theory.addAttack(d, f);
@@ -77,14 +96,22 @@ public static DungTheory example2() {
         return theory;
     }
 
+    /**
+     * Creates and returns an example of a Dung argumentation framework (Dung
+     * Theory).
+     * <p>
+     *
+     * @return A {@link DungTheory} object representing the defined argumentation
+     *         framework.
+     */
     public static DungTheory example3() {
         Argument h = new Argument("h");
         Argument i = new Argument("i");
         Argument j = new Argument("j");
         Argument k = new Argument("k");
         Argument l = new Argument("l");
         DungTheory theory = new DungTheory();
-        theory.add(h,i,j,k,l);
+        theory.add(h, i, j, k, l);
         theory.addAttack(i, h);
         theory.addAttack(h, j);
         theory.addAttack(j, i);

org-tweetyproject-arg-dung/src/main/java/org/tweetyproject/arg/dung/reasoner/SerialisedExtensionReasoner.java

@@ -39,11 +39,14 @@
  * A semantics is serialisable iff it can be characterised by two functions
  * <br>
  * <ul>
- *   <li>{@link SelectionFunction} a(UA, UC, C):     Return a subset of the initial sets
- *   <li>{@link TerminationFunction} b(AF, S):     True, iff S is an extension
+ * <li>{@link SelectionFunction} a(UA, UC, C): Return a subset of the initial
+ * sets
+ * <li>{@link TerminationFunction} b(AF, S): True, iff S is an extension
  * </ul>
- * which describe a transition system where {@code a(UA,UC,C)} provides the possible transitions to new states
- * and {@code b(AF,S)} determines whether the current state is an extension of the semantics.
+ * which describe a transition system where {@code a(UA,UC,C)} provides the
+ * possible transitions to new states
+ * and {@code b(AF,S)} determines whether the current state is an extension of
+ * the semantics.
  *
  * @see "Matthias Thimm. 'Revisiting initial sets in abstract argumentation' Argument & Computation (2022)"
  *
@@ -58,19 +61,23 @@ public class SerialisedExtensionReasoner extends AbstractExtensionReasoner {
     private final Semantics semantics;
 
     /**
-     * Initializes a serialisation reasoner with the given selection and termination functions
+     * Initializes a serialisation reasoner with the given selection and termination
+     * functions
+     *
      * @param alpha some selection function
-     * @param beta some termination function
+     * @param beta  some termination function
      */
     public SerialisedExtensionReasoner(SelectionFunction alpha, TerminationFunction beta) {
         this(alpha, beta, Semantics.diverse);
     }
 
     /**
-     * Initializes a serialisation reasoner with the given selection and termination functions
+     * Initializes a serialisation reasoner with the given selection and termination
+     * functions
      * and sets the semantics
-     * @param alpha some selection function
-     * @param beta some termination function
+     *
+     * @param alpha     some selection function
+     * @param beta      some termination function
      * @param semantics some semantics
      */
     public SerialisedExtensionReasoner(SelectionFunction alpha, TerminationFunction beta, Semantics semantics) {
@@ -81,6 +88,7 @@ public SerialisedExtensionReasoner(SelectionFunction alpha, TerminationFunction
 
     /**
      * Initializes a serialisation reasoner for the given semantics
+     *
      * @param semantics some selection function
      */
     public SerialisedExtensionReasoner(Semantics semantics) {
@@ -89,32 +97,39 @@ public SerialisedExtensionReasoner(Semantics semantics) {
             case ADM -> {
                 selectionFunction = SelectionFunction.ADMISSIBLE;
                 terminationFunction = TerminationFunction.ADMISSIBLE;
-            } case CO -> {
+            }
+            case CO -> {
                 selectionFunction = SelectionFunction.ADMISSIBLE;
                 terminationFunction = TerminationFunction.COMPLETE;
-            } case PR -> {
+            }
+            case PR -> {
                 selectionFunction = SelectionFunction.ADMISSIBLE;
                 terminationFunction = TerminationFunction.PREFERRED;
-            } case SAD -> {
+            }
+            case SAD -> {
                 selectionFunction = SelectionFunction.GROUNDED;
                 terminationFunction = TerminationFunction.ADMISSIBLE;
-            } case GR -> {
+            }
+            case GR -> {
                 selectionFunction = SelectionFunction.GROUNDED;
                 terminationFunction = TerminationFunction.COMPLETE;
-            } case UC -> {
+            }
+            case UC -> {
                 selectionFunction = SelectionFunction.UNCHALLENGED;
                 terminationFunction = TerminationFunction.UNCHALLENGED;
-            } case ST -> {
+            }
+            case ST -> {
                 selectionFunction = SelectionFunction.ADMISSIBLE;
                 terminationFunction = TerminationFunction.STABLE;
-            } default -> throw new IllegalArgumentException("Semantics is not serialisable: " + semantics);
+            }
+            default -> throw new IllegalArgumentException("Semantics is not serialisable: " + semantics);
         }
     }
 
     @Override
     public Collection<Extension<DungTheory>> getModels(DungTheory bbase) {
         Collection<Extension<DungTheory>> result = new HashSet<>();
-        for (SerialisationSequence sequence: this.getSequences(bbase)) {
+        for (SerialisationSequence sequence : this.getSequences(bbase)) {
             result.add(sequence.getExtension());
         }
         return result;
@@ -128,16 +143,18 @@ public Extension<DungTheory> getModel(DungTheory bbase) {
 
     /**
      * Computes the set of serialisation sequences wrt. the semantics
+     *
      * @param bbase some argumentation framework
      * @return the set of serialisation sequences
      */
-    public Collection<SerialisationSequence> getSequences(DungTheory bbase){
+    public Collection<SerialisationSequence> getSequences(DungTheory bbase) {
         return this.getSequences(bbase, new SerialisationSequence());
     }
 
     /**
      * Recursively computes all serialisation sequences wrt. the semantics
-     * @param theory an argumentation framework
+     *
+     * @param theory         an argumentation framework
      * @param parentSequence the current serialisation sequence
      * @return the set of serialisation sequences
      */
@@ -148,10 +165,13 @@ private Collection<SerialisationSequence> getSequences(DungTheory theory, Serial
         if (this.isTerminal(theory, parentSequence.getExtension())) {
             result.add(parentSequence);
         }
-        Map<SimpleInitialReasoner.Initial, Collection<Extension<DungTheory>>> initialSets = SimpleInitialReasoner.partitionInitialSets(theory);
-        Collection<Extension<DungTheory>> candidateSets = this.getSelection(initialSets.get(UA), initialSets.get(UC), initialSets.get(C));
-        // iterate depth-first through all initial sets (and hence their induced states) and add all found serialisation sequences
-        for (Extension<DungTheory> set: candidateSets) {
+        Map<SimpleInitialReasoner.Initial, Collection<Extension<DungTheory>>> initialSets = SimpleInitialReasoner
+                .partitionInitialSets(theory);
+        Collection<Extension<DungTheory>> candidateSets = this.getSelection(initialSets.get(UA), initialSets.get(UC),
+                initialSets.get(C));
+        // iterate depth-first through all initial sets (and hence their induced states)
+        // and add all found serialisation sequences
+        for (Extension<DungTheory> set : candidateSets) {
             DungTheory reduct = theory.getReduct(set);
 
             SerialisationSequence newSequence = new SerialisationSequence(parentSequence);
@@ -163,10 +183,12 @@ private Collection<SerialisationSequence> getSequences(DungTheory theory, Serial
     }
 
     /**
-     * Creates a graph, visualizing the transition states of the serialisation process, which creates all serialisable extensions
+     * Creates a graph, visualizing the transition states of the serialisation
+     * process, which creates all serialisable extensions
      * according to the specified semantics of the specified framework.
      *
-     * @param bbase argumentation framework, for which the extensions shall be computed
+     * @param bbase argumentation framework, for which the extensions shall be
+     *              computed
      * @return Graph representing the serialisation sequences
      */
     public SerialisationGraph getSerialisationGraph(DungTheory bbase) {
@@ -175,17 +197,43 @@ public SerialisationGraph getSerialisationGraph(DungTheory bbase) {
 
     /**
      * Return the semantics of this reasoner
+     *
      * @return the semantics
      */
     public Semantics getSemantics() {
         return semantics;
     }
 
-    public Collection<Extension<DungTheory>> getSelection(Collection<Extension<DungTheory>> ua, Collection<Extension<DungTheory>> uc, Collection<Extension<DungTheory>> c) {
-        return this.selectionFunction.execute((Set<Extension<DungTheory>>) ua, (Set<Extension<DungTheory>>) uc, (Set<Extension<DungTheory>>) c);
+    /**
+     * Applies a selection function to compute a collection of preferred extensions
+     * from given sets of extensions.
+     *
+     * @param ua A collection of unattacked extensions of the Dung theory.
+     * @param uc A collection of unattacked but conflicting extensions.
+     * @param c  A collection of conflicting extensions.
+     * @return A collection of {@link Extension} objects selected based on the
+     *         applied selection function.
+     *
+     * @throws ClassCastException if any of the input collections cannot be cast to
+     *                            {@link Set<Extension<DungTheory>>}.
+     */
+    public Collection<Extension<DungTheory>> getSelection(Collection<Extension<DungTheory>> ua,
+            Collection<Extension<DungTheory>> uc, Collection<Extension<DungTheory>> c) {
+        return this.selectionFunction.execute((Set<Extension<DungTheory>>) ua, (Set<Extension<DungTheory>>) uc,
+                (Set<Extension<DungTheory>>) c);
     }
 
+    /**
+     * Checks whether a given extension is terminal in the specified Dung theory.
+     *
+     *
+     * @param theory    The {@link DungTheory} in which the extension is evaluated.
+     * @param extension The {@link Extension} to be checked for terminal status.
+     * @return {@code true} if the extension is terminal in the given theory;
+     *         {@code false} otherwise.
+     */
     public boolean isTerminal(DungTheory theory, Extension<DungTheory> extension) {
         return this.terminationFunction.execute(theory, extension);
     }
+
 }

org-tweetyproject-arg-rankings/src/main/java/org/tweetyproject/arg/rankings/postulates/RaSigmaCompatibility.java

@@ -12,14 +12,36 @@
 import java.util.HashSet;
 import java.util.Iterator;
 
+
+/**
+ * Represents the Sigma-Compatibility postulate for ranking-based argumentation frameworks.
+ *
+ *
+ * @see RankingPostulate
+ * @see AbstractExtensionReasoner
+ * @see Semantics
+ */
 public class RaSigmaCompatibility extends RankingPostulate {
 
+        /**
+     * The extension-based reasoner used to derive extensions of the argumentation framework.
+     */
     AbstractExtensionReasoner reasoner;
 
+    /**
+     * Constructs a {@code RaSigmaCompatibility} postulate with the specified extension reasoner.
+     *
+     * @param reasoner The {@link AbstractExtensionReasoner} used to compute extensions of the argumentation framework.
+     */
     public RaSigmaCompatibility(AbstractExtensionReasoner reasoner) {
         this.reasoner = reasoner;
     }
 
+    /**
+     * Constructs a {@code RaSigmaCompatibility} postulate using a specified semantics.
+     *
+     * @param semantics The {@link Semantics} defining the reasoning approach for argument evaluation.
+     */
     public RaSigmaCompatibility(Semantics semantics) {
         this(AbstractExtensionReasoner.getSimpleReasonerForSemantics(semantics));
     }