Improve documentation and consistency of type parameter naming

language-api/src/main/java/de/jplag/Language.java

@@ -8,40 +8,33 @@
 
 /**
  * Common interface for all languages. Each language-front end must provide a concrete language implementation.
- * @author robin
- * @version $Id: $Id
  */
 public interface Language {
 
     /**
      * Suffixes for the files containing code of the language. An empty array means all suffixes are valid.
-     * @return an array of {@link java.lang.String} objects
      */
     String[] suffixes();
 
     /**
      * Descriptive name of the language.
-     * @return a {@link java.lang.String} object
      */
     String getName();
 
     /**
      * Identifier of the language used for CLI options and dynamic loading. You should use some name within {@code [a-z_-]+}
-     * @return a {@link java.lang.String} object
      */
     String getIdentifier();
 
     /**
      * Minimum number of tokens required for a match.
-     * @return a int
      */
     int minimumTokenMatch();
 
     /**
      * Parses a set of files. Override this method, if you don't require normalization.
      * @param files are the files to parse.
      * @return the list of parsed JPlag tokens.
-     * @throws de.jplag.ParsingException if an error during parsing the files occurred.
      * @deprecated Replaced by {@link #parse(Set, boolean)}
      */
     @Deprecated(forRemoval = true)
@@ -54,22 +47,19 @@ default List<Token> parse(Set<File> files) throws ParsingException {
      * @param files are the files to parse.
      * @param normalize True, if the tokens should be normalized
      * @return the list of parsed JPlag tokens.
-     * @throws de.jplag.ParsingException if an error during parsing the files occurred.
      */
     List<Token> parse(Set<File> files, boolean normalize) throws ParsingException;
 
     /**
      * Indicates whether the tokens returned by parse have semantic information added to them, i.e. whether the token
      * attribute semantics is null or not.
-     * @return a boolean
      */
     default boolean tokensHaveSemantics() {
         return false;
     }
 
     /**
      * Determines whether a fixed-width font should be used to display that language.
-     * @return a boolean
      */
     default boolean isPreformatted() {
         return true;
@@ -78,15 +68,13 @@ default boolean isPreformatted() {
     /**
      * Indicates whether the input files (code) should be used as representation in the report, or different files that form
      * a view on the input files.
-     * @return a boolean
      */
     default boolean useViewFiles() {
         return false;
     }
 
     /**
      * If the language uses representation files, this method returns the suffix used for the representation files.
-     * @return a {@link java.lang.String} object
      */
     default String viewFileSuffix() {
         return "";
@@ -118,9 +106,6 @@ default List<File> customizeSubmissionOrder(List<File> submissions) {
     }
 
     /**
-     * <p>
-     * supportsNormalization.
-     * </p>
      * @return True, if this language supports token sequence normalization. This does not include other normalization
      * mechanisms that might be part of the language modules.
      */

language-api/src/main/java/de/jplag/TokenType.java

@@ -5,8 +5,6 @@
  * be extracted from code written in that language. A token type is expected to be stateless, thus it is recommended to
  * use an <code>enum</code> or <code>record</code>.
  * @see SharedTokenType
- * @author robin
- * @version $Id: $Id
  */
 public interface TokenType {
     /**

language-api/src/main/java/de/jplag/options/DefaultLanguageOption.java

@@ -3,8 +3,6 @@
 /**
  * Default implementation for {@link de.jplag.options.LanguageOption}
  * @param <T> The type of the option
- * @author robin
- * @version $Id: $Id
  */
 public class DefaultLanguageOption<T> implements LanguageOption<T> {
     private final OptionType<T> type;

language-api/src/main/java/de/jplag/options/LanguageOption.java

@@ -3,8 +3,6 @@
 /**
  * A single language specific option.
  * @param <T> The type of the options value
- * @author robin
- * @version $Id: $Id
  */
 public interface LanguageOption<T> {
     /**

language-api/src/main/java/de/jplag/options/LanguageOptions.java

@@ -6,11 +6,8 @@
 
 /**
  * Container for a languages options. Should be implemented per language.
- * @author robin
- * @version $Id: $Id
  */
 public abstract class LanguageOptions {
-    /** Constant <code>EMPTY_OPTIONS</code> */
     public static final LanguageOptions EMPTY_OPTIONS = new LanguageOptions() {
     };
 
@@ -76,9 +73,6 @@ protected <T> LanguageOption<T> createOption(OptionType<T> type, String name) {
     }
 
     /**
-     * <p>
-     * getOptionsAsList.
-     * </p>
      * @return The list of all options
      */
     public List<LanguageOption<?>> getOptionsAsList() {

language-api/src/main/java/de/jplag/util/FileUtils.java

@@ -29,8 +29,6 @@
 
 /**
  * Encapsulates various interactions with files to prevent issues with file encodings.
- * @author robin
- * @version $Id: $Id
  */
 public class FileUtils {
     private static final Charset DEFAULT_OUTPUT_CHARSET = StandardCharsets.UTF_8;

languages/java-cpg/src/main/java/de/jplag/java_cpg/CpgAdapter.java

@@ -28,7 +28,7 @@ public class CpgAdapter {
     private boolean reorderingEnabled = true;
 
     /**
-     * Constructor for CpgAdapter.
+     * Constructs a new CpgAdapter.
      * @param transformations a list of {@link GraphTransformation}s
      */
     public CpgAdapter(GraphTransformation... transformations) {

languages/java-cpg/src/main/java/de/jplag/java_cpg/JavaCpgLanguage.java

@@ -99,37 +99,19 @@ private GraphTransformation[] obligatoryTransformations() {
      * @return the array of recommended transformations
      */
     public GraphTransformation[] standardTransformations() {
-        return new GraphTransformation[] {removeOptionalOfCall,               // 1
-                removeOptionalGetCall,              // 2
-                moveConstantToOnlyUsingClass,       // 5
-                inlineSingleUseVariable,            // 7
-                removeLibraryRecord,                // 10
-                removeEmptyRecord,                  // 15
-        };
+        return new GraphTransformation[] {removeOptionalOfCall, removeOptionalGetCall, moveConstantToOnlyUsingClass, inlineSingleUseVariable,
+                removeLibraryRecord, removeEmptyRecord,};
     }
 
     /**
      * Returns a set of all transformations.
      * @return the array of all transformations
      */
     public GraphTransformation[] allTransformations() {
-        return new GraphTransformation[] {ifWithNegatedConditionResolution,   // 0
-                forStatementToWhileStatement,       // 1
-                removeOptionalOfCall,               // 2
-                removeOptionalGetCall,              // 3
-                removeGetterMethod,                 // 4
-                moveConstantToOnlyUsingClass,       // 5
-                inlineSingleUseConstant,            // 6
-                inlineSingleUseVariable,            // 7
-                removeEmptyDeclarationStatement,    // 8
-                removeImplicitStandardConstructor,  // 9
-                removeLibraryRecord,                // 10
-                removeLibraryField,                 // 11
-                removeEmptyConstructor,             // 12
-                removeUnsupportedConstructor,       // 13
-                removeUnsupportedMethod,            // 14
-                removeEmptyRecord,                  // 15
-        };
+        return new GraphTransformation[] {ifWithNegatedConditionResolution, forStatementToWhileStatement, removeOptionalOfCall, removeOptionalGetCall,
+                removeGetterMethod, moveConstantToOnlyUsingClass, inlineSingleUseConstant, inlineSingleUseVariable, removeEmptyDeclarationStatement,
+                removeImplicitStandardConstructor, removeLibraryRecord, removeLibraryField, removeEmptyConstructor, removeUnsupportedConstructor,
+                removeUnsupportedMethod, removeEmptyRecord,};
     }
 
     @Override

languages/java-cpg/src/main/java/de/jplag/java_cpg/passes/DfgSortPass.kt

@@ -410,7 +410,7 @@ class DfgSortPass(ctx: TranslationContext) : TranslationUnitPass(ctx) {
             it.end.prevEOGEdges.remove(it)
         }
 
-        // eogPred may be DummyNeighbor if
+        //rebuild EOG edges into the block
         eogPred.filterNot { it is DummyNeighbor }
             .filterNot { TransformationUtil.isEogSuccessor(it, newEntry) }
             .forEach {
@@ -420,7 +420,7 @@ class DfgSortPass(ctx: TranslationContext) : TranslationUnitPass(ctx) {
                 newEntry.addPrevEOG(edge)
             }
 
-
+        //rebuild EOG edges out of the block
         val newExit = TransformationUtil.getEogBorders((parent.statements.last())).exits[0]
         if (exit != newExit) {
             newExit.nextEOGEdges.filter { it.end is DummyNeighbor }.forEach {

languages/java-cpg/src/main/java/de/jplag/java_cpg/passes/JTokenizationPass.java

@@ -35,16 +35,13 @@ public class JTokenizationPass extends TranslationResultPass {
     Consumer<List<Token>> callback = null;
 
     /**
-     * <p>
-     * Constructor for JTokenizationPass.
-     * </p>
-     * @param ctx a {@link de.fraunhofer.aisec.cpg.TranslationContext} object
+     * Constructs a new JTokenizationPass.
+     * @param ctx the current {@link de.fraunhofer.aisec.cpg.TranslationContext}
      */
     public JTokenizationPass(@NotNull TranslationContext ctx) {
         super(ctx);
     }
 
-    /** {@inheritDoc} */
     @Override
     public void accept(TranslationResult translationResult) {
         tokenList.clear();
@@ -57,11 +54,7 @@ public void accept(TranslationResult translationResult) {
         callback.accept(tokenList);
     }
 
-    /**
-     * <p>
-     * cleanup.
-     * </p>
-     */
+    @Override
     public void cleanup() {
         logger.info("Found {} tokens", tokenList.size());
     }

languages/java-cpg/src/main/java/de/jplag/java_cpg/passes/PrintPass.kt

@@ -6,20 +6,12 @@ import de.fraunhofer.aisec.cpg.graph.declarations.TranslationUnitDeclaration
 import de.fraunhofer.aisec.cpg.helpers.SubgraphWalker
 import de.fraunhofer.aisec.cpg.passes.TranslationUnitPass
 import java.util.*
-import java.util.function.Consumer
-import kotlin.reflect.KClass
 
 /**
  * A pass that prints all found nodes to the console.
  */
 class PrintPass(ctx: TranslationContext) : TranslationUnitPass(ctx) {
 
-    companion object {
-        @JvmStatic
-        val KClass: KClass<PrintPass> = PrintPass::class
-    }
-
-    override fun cleanup() {}
 
     override fun accept(translationUnitDeclaration: TranslationUnitDeclaration) {
         val graphWalker = SubgraphWalker.IterativeGraphWalker()
@@ -36,4 +28,8 @@ class PrintPass(ctx: TranslationContext) : TranslationUnitPass(ctx) {
             graphWalker.iterate(node)
         }
     }
+
+    override fun cleanup() {
+        // Nothing to do
+    }
 }

languages/java-cpg/src/main/java/de/jplag/java_cpg/token/ACpgNodeListener.java

@@ -6,9 +6,9 @@
 import de.fraunhofer.aisec.cpg.graph.statements.expressions.*;
 
 /**
- * This class provides empty dummy implementations for {@link de.jplag.java_cpg.token.CpgNodeListener}s.
+ * This class provides empty dummy implementations for {@link CpgNodeListener}s.
  */
-public abstract class ACpgNodeListener extends IVisitorExitor<Node> {
+public abstract class ACpgNodeListener extends VisitorExitor<Node> {
 
     /**
      * Creates a new {@link ACpgNodeListener}.

languages/java-cpg/src/main/java/de/jplag/java_cpg/token/CpgToken.java

@@ -16,8 +16,8 @@ public class CpgToken extends Token {
 
     /**
      * Creates a new {@link CpgToken}.
-     * @param tokenType the {@link de.jplag.TokenType}
-     * @param file the {@link java.io.File} that contains the represented piece of code
+     * @param tokenType the {@link TokenType}
+     * @param file the {@link File} that contains the represented piece of code
      * @param startLine the starting line of the represented code
      * @param startColumn the starting column of the represented code
      * @param length the length of the represented code

languages/java-cpg/src/main/java/de/jplag/java_cpg/token/CpgTokenConsumer.java

@@ -10,6 +10,7 @@
 import de.fraunhofer.aisec.cpg.graph.Node;
 import de.fraunhofer.aisec.cpg.sarif.PhysicalLocation;
 import de.fraunhofer.aisec.cpg.sarif.Region;
+import de.jplag.Token;
 import de.jplag.TokenType;
 
 /**
@@ -33,9 +34,9 @@ private static int calculateLength(Region region) {
     }
 
     /**
-     * Adds a new {@link de.jplag.Token} for the given {@link TokenType} and {@link Node}.
-     * @param type the {@link de.jplag.TokenType}
-     * @param node the represented {@link de.fraunhofer.aisec.cpg.graph.Node}
+     * Adds a new {@link Token} for the given {@link TokenType} and {@link Node}.
+     * @param type the {@link TokenType}
+     * @param node the represented {@link Node}
      * @param isEndToken true iff the token represents the end of a block
      */
     public void addToken(TokenType type, Node node, boolean isEndToken) {

languages/java-cpg/src/main/java/de/jplag/java_cpg/token/TokenConsumer.java

@@ -3,10 +3,12 @@
 import java.io.File;
 
 import de.fraunhofer.aisec.cpg.graph.Name;
+import de.fraunhofer.aisec.cpg.graph.Node;
+import de.jplag.Token;
 import de.jplag.TokenType;
 
 /**
- * This interface represents classes that can consume and save {@link de.jplag.Token}s.
+ * This interface represents classes that can consume and save {@link Token}s.
  */
 public interface TokenConsumer {
 
@@ -17,7 +19,7 @@ public interface TokenConsumer {
      * @param startLine the line where the represented code starts
      * @param startColumn the column where the represented code starts
      * @param length The length of the represented code
-     * @param name the name of the represented {@link de.fraunhofer.aisec.cpg.graph.Node}
+     * @param name the name of the represented {@link Node}
      */
     void addToken(TokenType type, File file, int startLine, int startColumn, int length, Name name);
 

languages/java-cpg/src/main/java/de/jplag/java_cpg/token/IVisitorExitor.java → languages/java-cpg/src/main/java/de/jplag/java_cpg/token/VisitorExitor.java

@@ -12,7 +12,7 @@
  * of {@link IVisitor}.
  * @param <V> the object type to visit and exit
  */
-public abstract class IVisitorExitor<V extends IVisitable<V>> extends IVisitor<V> {
+public abstract class VisitorExitor<V extends IVisitable<V>> extends IVisitor<V> {
 
     private static final String EXIT_METHOD_IDENTIFIER = "exit";
 

languages/java-cpg/src/main/java/de/jplag/java_cpg/transformation/GraphTransformation.java

@@ -25,13 +25,13 @@ public interface GraphTransformation {
      * Applies the transformation to the Graph represented by the given {@link Match} which indicates which {@link Node}s
      * shall be involved in the transformation.
      * @param match the match of this {@link GraphTransformation}'s source pattern to a concrete graph
-     * @param ctx a {@link TranslationContext} object
+     * @param ctx the current {@link TranslationContext}
      */
     void apply(Match match, TranslationContext ctx);
 
     /**
-     * Gets the {@link ExecutionPhase} for this {@link GraphTransformation}
-     * @return a {@link ExecutionOrder} object
+     * Gets the {@link ExecutionOrder} for this {@link GraphTransformation}
+     * @return the execution order
      */
     ExecutionOrder getExecutionOrder();
 

languages/java-cpg/src/main/java/de/jplag/java_cpg/transformation/TransformationException.java

@@ -1,7 +1,7 @@
 package de.jplag.java_cpg.transformation;
 
 /**
- * An {@link java.lang.Exception} that relates to the Transformation process.
+ * An {@link Exception} that relates to the Transformation process.
  */
 public class TransformationException extends RuntimeException {