Add more Javadoc

languages/scxml/src/main/java/de/jplag/scxml/parser/HandcraftedScxmlTokenGenerator.java

@@ -14,13 +14,19 @@
 public class HandcraftedScxmlTokenGenerator extends SimpleScxmlTokenGenerator {
 
     /**
-     * Creates the visitor.
-     * @param adapter is the parser adapter which receives the generated tokens.
+     * Creates the token generator.
+     * @param adapter the parser adapter which receives the generated tokens
      */
     public HandcraftedScxmlTokenGenerator(ScxmlParserAdapter adapter) {
         super(adapter);
     }
 
+    /**
+     * Visits a state and extracts tokens based on whether its {@code initial}
+     * and {@code parallel} attributes are set to {@code true}.
+     *
+     * @param state the state to visit
+     */
     protected void visitStateAttributes(State state) {
         if (state.initial()) {
             adapter.addToken(INITIAL_STATE, state);

languages/scxml/src/main/java/de/jplag/scxml/parser/SimpleScxmlTokenGenerator.java

@@ -20,7 +20,7 @@
 public class SimpleScxmlTokenGenerator extends AbstractScxmlVisitor {
 
     /**
-     * Creates the visitor.
+     * Creates the token generator.
      * @param adapter the parser adapter which receives the generated tokens
      */
     public SimpleScxmlTokenGenerator(ScxmlParserAdapter adapter) {
@@ -135,6 +135,7 @@ public void visitExecutableContent(ExecutableContent content) {
             return;
         }
 
+        // TODO: use entries
         Map<Class<? extends StatechartElement>, ScxmlTokenType> tokenTypeMap = Map.of(Send.class, SEND, Cancel.class, CANCEL);
         ScxmlTokenType type = tokenTypeMap.get(content.getClass());
         adapter.addToken(type, content);

languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/Action.java

@@ -3,6 +3,12 @@
 import java.util.List;
 import java.util.Objects;
 
+/**
+ * Represents <onentry> and <onexit> SCXML elements which contain
+ * executable content to be executed when a state is entered / exited.
+ * @param type the type of the action ({@link Type#ON_ENTRY} or {@link Type#ON_EXIT})
+ * @param contents the list of executable contents within the action
+ */
 public record Action(Type type, List<ExecutableContent> contents) implements ExecutableContent {
 
     @Override
@@ -15,8 +21,17 @@ public String toString() {
         return String.format("Action (type=%s) {", type == Type.ON_ENTRY ? "OnEntry" : "OnExit");
     }
 
+    /**
+     * The type of the action.
+     */
     public enum Type {
+        /**
+         * Represents an <onentry> SCXML element.
+         */
         ON_ENTRY,
+        /**
+         * Represents an <onexit> SCXML element.
+         */
         ON_EXIT,
     }
 }

languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/Cancel.java

@@ -1,5 +1,9 @@
 package de.jplag.scxml.parser.model.executable_content;
 
+/**
+ * Represents a <cancel> SCXML element.
+ * @param sendid represents the sendid attribute of the SCXML element which is the ID of the event to be cancelled
+ */
 public record Cancel(String sendid) implements ExecutableContent {
 
     @Override

languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/ExecutableContent.java

@@ -9,17 +9,36 @@
 import de.jplag.scxml.parser.model.StatechartElement;
 import de.jplag.scxml.parser.util.NodeUtil;
 
+/**
+ * Represents executable content in an SCXML statechart, which are elements that can be executed
+ * during state transitions, state entry, state exit or in conditional statements.
+ */
 public interface ExecutableContent extends StatechartElement {
 
     /**
-     * Defines the set of allowed XML element names that are considered valid executable content. <else> and <elseif>
-     * elements are not allowed as they may only present as children of an <if> element.
+     * Defines the set of allowed XML element names that are considered valid executable content. {@literal <else>} and
+     * {@literal <elseif>} elements are not allowed as they may only present as children of an {@literal <if>} element.
      */
     Set<String> ALLOWED_XML_ELEMENTS = Set.of("raise", "if", "foreach", "log", "assign", "script", "send", "cancel");
 
+    /**
+     * String constant for the <else> element.
+     */
     String ELSE_ELEMENT = "else";
+
+    /**
+     * String constant for the "event" attribute.
+     */
     String EVENT_ATTRIBUTE = "event";
+
+    /**
+     * String constant for the "sendid" attribute.
+     */
     String SEND_ID_ATTRIBUTE = "sendid";
+
+    /**
+     * String constant for the "delay" attribute.
+     */
     String DELAY_ATTRIBUTE = "delay";
 
     /**

languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/ForEach.java

@@ -2,6 +2,12 @@
 
 import java.util.List;
 
+/**
+ * Represents a {@code <foreach>} SCXML element, which is executable content
+ * that executes its contents for each item in a given data set.
+ *
+ * @param contents the list of executable contents within the {@code <foreach>} element
+ */
 public record ForEach(List<ExecutableContent> contents) implements ExecutableContent {
 
     @Override

languages/scxml/src/main/java/de/jplag/scxml/parser/model/executable_content/If.java

@@ -9,6 +9,16 @@
 
 import de.jplag.scxml.parser.util.NodeUtil;
 
+/**
+ * Represents an {@literal <if>} SCXML element, which is an executable content element used for conditional execution.
+ * The {@literal <if>} element can contain {@literal <elseif>} and {@literal <else>} branches for handling multiple conditions.
+ *
+ * @param cond the cond attribute of the {@literal <if>} element which is the condition expression
+ * for the contained executable contents to be executed
+ * @param contents the list of executable contents to be executed when the condition is met
+ * @param elseIfs represents the list of {@literal <elseif>} branches in the {@literal <if>} element
+ * @param else_ the {@literal <else>} branch corresponding to the {@literal <if>} element, or {@code null} if not present
+ */
 public record If(String cond, List<ExecutableContent> contents, List<ElseIf> elseIfs, Else else_) implements ExecutableContent {
 
     private static final Set<String> ALLOWED_CONTENTS = Set.of("raise", "if", "foreach", "log", "assign", "script", "send", "cancel");
@@ -17,6 +27,15 @@ public record If(String cond, List<ExecutableContent> contents, List<ElseIf> els
     private static final String ELSEIF_ELEMENT = "elseif";
     private static final String COND_ATTRIBUTE = "cond";
 
+
+    /**
+     * Constructs an If instance with the specified condition and a list of executable contents.
+     * The {@code elseIf} attribute is set to an empty list and the {@code else} is set to null.
+     *
+     * @param cond the cond attribute of the {@literal <if>} element which is the condition expression
+     * for the contained executable contents to be executed
+     * @param contents the list of executable contents to be executed when the condition is met
+     */
     public If(String cond, ExecutableContent... contents) {
         this(cond, new ArrayList<>(List.of(contents)), new ArrayList<>(), null);
     }
@@ -32,8 +51,7 @@ private static void addBranch(String branch, List<ExecutableContent> contents, L
     /**
      * Constructs an If statechart element from a given node with optional ElseIf or Else branches. The W3C SCXML
      * specification defines a valid {@literal <if>} element as follows:
-     * <p>
-     * 
+     *
      * <pre>
      * {@code
      * <if cond="cond1">
@@ -52,6 +70,7 @@ private static void addBranch(String branch, List<ExecutableContent> contents, L
      * on the same level.
      * @param node the node to create the If object from. Must contain at least one {@literal <if>} element and optionally
      * {@literal <elseif>} or {@literal <else>} tags.
+     * @return an instance of If created from the node
      * @throws IllegalArgumentException when more than one {@literal <else>} statement is present
      */
     public static If fromNode(Node node) throws IllegalArgumentException {

languages/scxml/src/main/java/de/jplag/scxml/parser/util/NodeUtil.java

@@ -76,8 +76,13 @@ public static List<Node> getNodesRecursive(Node root, String childName) {
     }
 
     /**
-     * @return the value of the attribute specified by name of the given node or null if the node does not contain an
-     * attribute with this name
+     * Retrieves the value of an attribute with the specified name from the given node. If the attribute is not present,
+     * {@code null} is returned.
+     *
+     * @param node the node containing the attribute
+     * @param name the name of the attribute to retrieve
+     * @return the value of the attribute, or {@code null} if the node does not contain an
+     * attribute with the given name
      */
     public static String getAttribute(Node node, String name) {
         Node attribute = node.getAttributes().getNamedItem(name);

languages/scxml/src/main/java/de/jplag/scxml/sorting/SortingStrategy.java

@@ -13,5 +13,6 @@ public interface SortingStrategy {
      * Sorts a list of statechart elements.
      * @param statechartElements the list of statechart elements to sort
      */
+    // TODO: try without type parameter
     <T extends StatechartElement> List<T> sort(List<T> statechartElements);
 }

languages/scxml/src/main/java/de/jplag/scxml/util/AbstractScxmlVisitor.java

@@ -19,8 +19,19 @@
  */
 public abstract class AbstractScxmlVisitor {
 
+    /**
+     * The current parser adapter that is called to add new tokens.
+     */
     protected ScxmlParserAdapter adapter;
+
+    /**
+     * The sorting strategy to use for visiting nested statechart elements.
+     */
     protected SortingStrategy sorter;
+
+    /**
+     * The current depth in the statechart.
+     */
     protected int depth;
 
     public AbstractScxmlVisitor(ScxmlParserAdapter adapter) {
@@ -40,6 +51,7 @@ public void setSorter(SortingStrategy sorter) {
      * Visits a statechart element without effecting the main token stream by temporarily swapping out the current parser
      * adapter. Returns a list of collected token type ordinals.
      * @param element the statechart element to visit
+     * @return a list of visited token type ordinals
      */
     public List<Integer> peekTokens(StatechartElement element) {
         ScxmlParserAdapter prevAdapter = this.adapter;
@@ -76,22 +88,66 @@ public final void visit(StatechartElement element) throws IllegalArgumentExcepti
         visitorMap.get(element.getClass()).accept(element);
     }
 
+    /**
+     * Recursively visits a statechart.
+     *
+     * @param statechart the statechart to visit
+     */
     protected abstract void visitStatechart(Statechart statechart);
 
+    /**
+     * Recursively visits a state.
+     *
+     * @param state the state to visit
+     */
     protected abstract void visitState(State state);
 
+    /**
+     * Recursively visits a transition.
+     *
+     * @param transition the transition to visit
+     */
+    protected abstract void visitTransition(Transition transition);
+
+    /**
+     * Recursively visits a list of actions.
+     *
+     * @param actions the list of actions to visit
+     */
     protected abstract void visitActions(List<Action> actions);
 
+    /**
+     * Recursively visits an if statechart element.
+     *
+     * @param if_ the if element to visit
+     */
     protected abstract void visitIf(If if_);
 
+    /**
+     * Recursively visits an elseIf statechart element.
+     *
+     * @param elseIf the elseIf element to visit
+     */
     protected abstract void visitElseIf(ElseIf elseIf);
 
+    /**
+     * Recursively visits an else statechart element.
+     *
+     * @param else_ the else element to visit
+     */
     protected abstract void visitElse(Else else_);
 
+    /**
+     * Recursively visits executable content.
+     *
+     * @param content the executable content to visit
+     */
     protected abstract void visitExecutableContent(ExecutableContent content);
 
+    /**
+     * Visits simple executable content.
+     *
+     * @param content the simple executable content to visit
+     */
     protected abstract void visitSimpleExecutableContent(SimpleExecutableContent content);
-
-    protected abstract void visitTransition(Transition transition);
-
 }