updated documentation for explanation module

Author: larsbengel

org-tweetyproject-arg-explanations/src/main/java/org/tweetyproject/arg/explanations/examples/SequenceExplanationExample.java

@@ -1,15 +1,37 @@
+/*
+ *  This file is part of "TweetyProject", a collection of Java libraries for
+ *  logical aspects of artificial intelligence and knowledge representation.
+ *
+ *  TweetyProject is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Lesser General Public License version 3 as
+ *  published by the Free Software Foundation.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ *  Copyright 2025 The TweetyProject Team <http://tweetyproject.org/contact/>
+ */
+
 package org.tweetyproject.arg.explanations.examples;
 
 import org.tweetyproject.arg.dung.syntax.Argument;
 import org.tweetyproject.arg.dung.syntax.DungTheory;
 import org.tweetyproject.arg.explanations.reasoner.acceptance.AbstractSequenceExplanationReasoner;
 import org.tweetyproject.arg.explanations.reasoner.acceptance.DialecticalSequenceExplanationReasoner;
-import org.tweetyproject.arg.explanations.reasoner.acceptance.MinimalSequenceExplanationReasoner;
-import org.tweetyproject.arg.explanations.reasoner.acceptance.SequenceExplanationReasoner;
 import org.tweetyproject.arg.explanations.semantics.Explanation;
 
 import java.util.Collection;
 
+/**
+ * Example usage of sequence explanations
+ *
+ * @author Lars Bengel
+ */
 public class SequenceExplanationExample {
     public static void main(String[] args) {
         AbstractSequenceExplanationReasoner reasoner = new DialecticalSequenceExplanationReasoner();

org-tweetyproject-arg-explanations/src/main/java/org/tweetyproject/arg/explanations/examples/SufficientExplanationExample.java

@@ -1,9 +1,33 @@
+/*
+ *  This file is part of "TweetyProject", a collection of Java libraries for
+ *  logical aspects of artificial intelligence and knowledge representation.
+ *
+ *  TweetyProject is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Lesser General Public License version 3 as
+ *  published by the Free Software Foundation.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ *  Copyright 2025 The TweetyProject Team <http://tweetyproject.org/contact/>
+ */
+
 package org.tweetyproject.arg.explanations.examples;
 
 import org.tweetyproject.arg.dung.syntax.Argument;
 import org.tweetyproject.arg.dung.syntax.DungTheory;
 import org.tweetyproject.arg.explanations.reasoner.acceptance.SufficientExplanationReasoner;
 
+/**
+ * Example usage of sufficient explanations
+ *
+ * @author Lars Bengel
+ */
 public class SufficientExplanationExample {
     public static void main(String[] args) {
         DungTheory theory = new DungTheory();

org-tweetyproject-arg-explanations/src/main/java/org/tweetyproject/arg/explanations/principles/ExplanationPrinciple.java

@@ -1,3 +1,22 @@
+/*
+ *  This file is part of "TweetyProject", a collection of Java libraries for
+ *  logical aspects of artificial intelligence and knowledge representation.
+ *
+ *  TweetyProject is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Lesser General Public License version 3 as
+ *  published by the Free Software Foundation.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ *  Copyright 2025 The TweetyProject Team <http://tweetyproject.org/contact/>
+ */
+
 package org.tweetyproject.arg.explanations.principles;
 
 import org.tweetyproject.arg.dung.syntax.Argument;
@@ -8,6 +27,11 @@
 
 import java.util.Collection;
 
+/**
+ * Abstract class for modeling principles/postulates for explanations in abstract argumentation
+ *
+ * @author Lars Bengel
+ */
 public abstract class ExplanationPrinciple implements Postulate<Argument> {
     @Override
     public boolean isApplicable(Collection<Argument> kb) {

org-tweetyproject-arg-explanations/src/main/java/org/tweetyproject/arg/explanations/reasoner/acceptance/AbstractAcceptanceExplanationReasoner.java

@@ -1,3 +1,22 @@
+/*
+ *  This file is part of "TweetyProject", a collection of Java libraries for
+ *  logical aspects of artificial intelligence and knowledge representation.
+ *
+ *  TweetyProject is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Lesser General Public License version 3 as
+ *  published by the Free Software Foundation.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ *  Copyright 2025 The TweetyProject Team <http://tweetyproject.org/contact/>
+ */
+
 package org.tweetyproject.arg.explanations.reasoner.acceptance;
 
 import org.tweetyproject.arg.dung.syntax.Argument;
@@ -6,10 +25,28 @@
 
 import java.util.Collection;
 
+/**
+ * Abstract class for all acceptance explanation reasoners
+ * An acceptance explanation reasoner provides explanations for the acceptance of some argument within an argumentation framework
+ *
+ * @author Lars Bengel
+ */
 public abstract class AbstractAcceptanceExplanationReasoner {
+    /**
+     * Computes some acceptance explanation for <code>argument</code>
+     * @param theory some argumentation framework
+     * @param argument some argument
+     * @return some explanation for the acceptance of <code>argument</code> in <code>theory</code>
+     */
     public Explanation getExplanation(DungTheory theory, Argument argument) {
         return getExplanations(theory, argument).iterator().next();
     }
 
+    /**
+     * Computes all acceptance explanations for <code>argument</code>
+     * @param theory some argumentation framework
+     * @param argument some argument
+     * @return all explanations for the acceptance of <code>argument</code> in <code>theory</code>
+     */
     public abstract Collection<Explanation> getExplanations(DungTheory theory, Argument argument);
 }

org-tweetyproject-arg-explanations/src/main/java/org/tweetyproject/arg/explanations/reasoner/acceptance/AbstractSequenceExplanationReasoner.java

@@ -1,6 +1,28 @@
-package org.tweetyproject.arg.explanations.reasoner.acceptance;
+/*
+ *  This file is part of "TweetyProject", a collection of Java libraries for
+ *  logical aspects of artificial intelligence and knowledge representation.
+ *
+ *  TweetyProject is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Lesser General Public License version 3 as
+ *  published by the Free Software Foundation.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ *  Copyright 2025 The TweetyProject Team <http://tweetyproject.org/contact/>
+ */
 
-import org.tweetyproject.arg.explanations.semantics.Explanation;
+package org.tweetyproject.arg.explanations.reasoner.acceptance;
 
+/**
+ * Abstract class for sequence-based explanation reasoners
+ *
+ * @author Lars Bengel
+ */
 public abstract class AbstractSequenceExplanationReasoner extends AbstractAcceptanceExplanationReasoner {
 }

org-tweetyproject-arg-explanations/src/main/java/org/tweetyproject/arg/explanations/reasoner/acceptance/DialecticalSequenceExplanationReasoner.java

@@ -1,3 +1,22 @@
+/*
+ *  This file is part of "TweetyProject", a collection of Java libraries for
+ *  logical aspects of artificial intelligence and knowledge representation.
+ *
+ *  TweetyProject is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Lesser General Public License version 3 as
+ *  published by the Free Software Foundation.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ *  Copyright 2025 The TweetyProject Team <http://tweetyproject.org/contact/>
+ */
+
 package org.tweetyproject.arg.explanations.reasoner.acceptance;
 
 import org.tweetyproject.arg.dung.serialisability.semantics.SerialisationSequence;
@@ -10,6 +29,15 @@
 import java.util.Collection;
 import java.util.HashSet;
 
+/**
+ * Reasoner for dialectical sequence explanations for the acceptance of arguments
+ * A sequence (S_1, T_1, ... S_n, T_n) of sets is a dialectical sequence explanation for the acceptance of an argument 'a' iff
+ * (S-1, ..., S_n) is a sequence explanation for 'a' and every T_i is the set of arguments defeated by S_i in the context of the explanation.
+ *
+ * @see "Lars Bengel, and Matthias Thimm. 'Sequence Explanations for Acceptance in Abstract Argumentation' Conference on Principles of Knowledge Representation and Reasoning (KR'25) (2025)."
+ *
+ * @author Lars Bengel
+ */
 public class DialecticalSequenceExplanationReasoner extends AbstractSequenceExplanationReasoner {
     @Override
     public Collection<Explanation> getExplanations(DungTheory theory, Argument argument) {
@@ -27,6 +55,15 @@ public Collection<Explanation> getExplanations(DungTheory theory, Argument argum
         return result;
     }
 
+    /**
+     * Computes the set of arguments that are defeated within the sequence 'seq' for the argument 'a' by the set 's'
+     * This set consists of all arguments that are relevant for 'a' and defeated by 's' but have not been defeated earlier in the sequence 'seq'
+     * @param theory some argumentation framework
+     * @param seq some serialisation sequence
+     * @param a the argument to be explained
+     * @param s the set of arguments
+     * @return the set of arguments defeated by 's' given the sequence and argument
+     */
     private Collection<Argument> getDefeated(DungTheory theory, SerialisationSequence seq, Argument a, Collection<Argument> s) {
         Collection<Argument> relevantAttackers = new HashSet<>();
         relevantAttackers.addAll(theory.getAttackers(a));

org-tweetyproject-arg-explanations/src/main/java/org/tweetyproject/arg/explanations/reasoner/acceptance/MinimalSequenceExplanationReasoner.java

@@ -1,3 +1,23 @@
+/*
+ *  This file is part of "TweetyProject", a collection of Java libraries for
+ *  logical aspects of artificial intelligence and knowledge representation.
+ *
+ *  TweetyProject is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Lesser General Public License version 3 as
+ *  published by the Free Software Foundation.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ *  Copyright 2025 The TweetyProject Team <http://tweetyproject.org/contact/>
+ */
+
+
 package org.tweetyproject.arg.explanations.reasoner.acceptance;
 
 import org.tweetyproject.arg.dung.syntax.Argument;
@@ -8,6 +28,15 @@
 import java.util.Collection;
 import java.util.HashSet;
 
+/**
+ * Reasoner for minimal sequence explanations for the acceptance of arguments
+ * A sequence (S_1, ... S_n) of sets is a minimal sequence explanation for the acceptance of an argument 'a' iff
+ * (S-1, ..., S_n) is a sequence explanation for 'a' and there exists no shorter sequence satisfying this.
+ *
+ * @see "Lars Bengel, and Matthias Thimm. 'Sequence Explanations for Acceptance in Abstract Argumentation' Conference on Principles of Knowledge Representation and Reasoning (KR'25) (2025)."
+ *
+ * @author Lars Bengel
+ */
 public class MinimalSequenceExplanationReasoner extends AbstractSequenceExplanationReasoner {
     @Override
     public Collection<Explanation> getExplanations(DungTheory theory, Argument argument) {

org-tweetyproject-arg-explanations/src/main/java/org/tweetyproject/arg/explanations/reasoner/acceptance/MinimalSufficientExplanationReasoner.java

@@ -1,3 +1,23 @@
+/*
+ *  This file is part of "TweetyProject", a collection of Java libraries for
+ *  logical aspects of artificial intelligence and knowledge representation.
+ *
+ *  TweetyProject is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Lesser General Public License version 3 as
+ *  published by the Free Software Foundation.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ *  Copyright 2025 The TweetyProject Team <http://tweetyproject.org/contact/>
+ */
+
+
 package org.tweetyproject.arg.explanations.reasoner.acceptance;
 
 import org.tweetyproject.arg.dung.reasoner.SimpleAdmissibleReasoner;
@@ -9,6 +29,15 @@
 import java.util.Collection;
 import java.util.HashSet;
 
+/**
+ * Reasoner for necessary explanations for the acceptance of an argument
+ * a set S is a necessary explanation for the acceptance of an argument 'a'
+ * iff every 'b' in S is contained in every admissible set containing 'a'
+ *
+ * @see "Borg, AnneMarie, and Floris Bex. 'Minimality, necessity and sufficiency for argumentation and explanation.' International Journal of Approximate Reasoning 168 (2024): 109143."
+ *
+ * @author Lars Bengel
+ */
 public class NecessaryExplanationReasoner extends AbstractAcceptanceExplanationReasoner {
     @Override
     public Collection<Explanation> getExplanations(DungTheory theory, Argument argument) {
@@ -18,7 +47,7 @@ public Collection<Explanation> getExplanations(DungTheory theory, Argument argum
             if (!arguments.contains(argument)) continue;
             intersection.retainAll(arguments);
         }
-        result.add(new SetExplanation(intersection));
+        result.add(new SetExplanation(argument, intersection));
         return result;
     }
 }

org-tweetyproject-arg-explanations/src/main/java/org/tweetyproject/arg/explanations/reasoner/acceptance/NecessaryExplanationReasoner.java

@@ -1,9 +1,27 @@
+/*
+ *  This file is part of "TweetyProject", a collection of Java libraries for
+ *  logical aspects of artificial intelligence and knowledge representation.
+ *
+ *  TweetyProject is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Lesser General Public License version 3 as
+ *  published by the Free Software Foundation.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ *  Copyright 2025 The TweetyProject Team <http://tweetyproject.org/contact/>
+ */
+
+
 package org.tweetyproject.arg.explanations.reasoner.acceptance;
 
-import org.tweetyproject.arg.dung.reasoner.SerialisedExtensionReasoner;
 import org.tweetyproject.arg.dung.reasoner.SimpleInitialReasoner;
 import org.tweetyproject.arg.dung.semantics.Extension;
-import org.tweetyproject.arg.dung.semantics.Semantics;
 import org.tweetyproject.arg.dung.serialisability.semantics.SerialisationSequence;
 import org.tweetyproject.arg.dung.serialisability.syntax.SelectionFunction;
 import org.tweetyproject.arg.dung.syntax.Argument;
@@ -15,6 +33,15 @@
 
 import static org.tweetyproject.arg.dung.reasoner.SimpleInitialReasoner.Initial.*;
 
+/**
+ * Reasoner for sequence explanations for the acceptance of arguments
+ * A sequence (S_1, ... S_n) of sets is a sequence explanation for the acceptance of an argument 'a' iff
+ * (S-1, ..., S_n) is a serialisation sequence and 'a' is contained in S_n.
+ *
+ * @see "Lars Bengel, and Matthias Thimm. 'Sequence Explanations for Acceptance in Abstract Argumentation' Conference on Principles of Knowledge Representation and Reasoning (KR'25) (2025)."
+ *
+ * @author Lars Bengel
+ */
 public class SequenceExplanationReasoner extends AbstractSequenceExplanationReasoner {
     @Override
     public Collection<Explanation> getExplanations(DungTheory theory, Argument argument) {