compilationUnits) {
+ private AnalyzerRoot() {
+ }
+
+ /**
+ * Perform the analysis of a solution.
+ *
+ * @param solution The solution being analyzed.
+ * @return The aggregated analysis of all applicable analyzers.
+ */
+ public static Analysis analyze(Solution solution) {
var analysis = new Analysis();
- for (Analyzer analyzer : createAnalyzers(slug)) {
- analyzer.analyze(compilationUnits, analysis);
+ for (Analyzer analyzer : createAnalyzers(solution.getSlug())) {
+ analyzer.analyze(solution, analysis);
}
- if (analysis.getComments().stream().anyMatch(x -> x.getType() != CommentType.CELEBRATORY)) {
+ if (analysis.getComments().stream().anyMatch(x -> x.getType() != Comment.Type.CELEBRATORY)) {
analysis.addComment(new FeedbackRequest());
}
diff --git a/src/main/java/analyzer/Comment.java b/src/main/java/analyzer/Comment.java
index 650f6331..a4d6569d 100644
--- a/src/main/java/analyzer/Comment.java
+++ b/src/main/java/analyzer/Comment.java
@@ -4,18 +4,82 @@
import java.util.Objects;
/**
+ * The {@link Comment} class models a single comment in the analysis output.
+ * Each comment has a unique key that translates to a Markdown template in the
+ * exercism/website-copy repository.
+ *
+ * If the Markdown template contains any parameters, classes inheriting from {@link Comment} should override the
+ * {@link Comment#getParameters()} method to return the parameter keys and values specific to that template.
+ *
+ * Override the {@link Comment#getType()} method to change the {@link Type} associated to the comment.
+ *
* @see The analyzer interface in the Exercism documentation
+ * @see Analyzer comments for the Java track in the website-copy
*/
public abstract class Comment {
+ /**
+ * The type of comment.
+ * Note that the order defined here corresponds to the order in which comments are sorted in the analyzer output.
+ *
+ * @see Documentation on comment types
+ */
+ public enum Type {
+ ESSENTIAL,
+ ACTIONABLE,
+ INFORMATIVE,
+ CELEBRATORY
+ }
+
+ /**
+ * The comment key is a {@link String} that uniquely identifies the comment.
+ *
+ * Comment keys use the format {@code "java.."}.
+ * The {@code } can be either {@code general} for general comments,
+ * or the slug of the exercise for exercise-specific comments.
+ * The {@code } specifies the name of the comment.
+ *
+ * The combination of {@code } and {@code } must be unique, and defines the location of the
+ * Markdown template in the exercism/website-copy repository.
+ *
+ * For example, the comment key {@code "java.hello-world.foo_bar"} would translate to the Markdown file at
+ * {@code analyzer-comments/java/hello-world/foo_bar.md}.
+ *
+ * @return The unique comment key.
+ */
public abstract String getKey();
+ /**
+ * Each parameter in the Markdown template should have a corresponding parameter in the comment.
+ * Parameters in Markdown templates are of the form {@code %s}.
+ *
+ * For example, if the Markdown template contains a parameter {@code %s},
+ * the implementation of this method could look like this:
+ * {@code
+ * public Map getParameters() {
+ * return Map.of("methodName", "theNameOfTheMethod");
+ * }
+ * }
+ *
+ * @return The parameters for the comment.
+ */
public Map getParameters() {
return Map.of();
}
- public CommentType getType() {
- return CommentType.INFORMATIVE;
+ /**
+ *
+ * - Use {@link Type#ESSENTIAL} to instruct students that they must address it.
+ * - Use {@link Type#ACTIONABLE} to instruct students that they could improve their solution by addressing it.
+ * - Use {@link Type#INFORMATIVE} to give students extra information without expecting them to use it.
+ * - Use {@link Type#CELEBRATORY} to tell students that they did something right.
+ *
+ *
+ * @return The type of the comment.
+ * @see Documentation on comment types
+ */
+ public Type getType() {
+ return Type.INFORMATIVE;
}
@Override
diff --git a/src/main/java/analyzer/CommentType.java b/src/main/java/analyzer/CommentType.java
deleted file mode 100644
index 9d50a567..00000000
--- a/src/main/java/analyzer/CommentType.java
+++ /dev/null
@@ -1,11 +0,0 @@
-package analyzer;
-
-/**
- * @see The analyzer interface in the Exercism documentation
- */
-public enum CommentType {
- ESSENTIAL,
- ACTIONABLE,
- INFORMATIVE,
- CELEBRATORY
-}
diff --git a/src/main/java/analyzer/Main.java b/src/main/java/analyzer/Main.java
deleted file mode 100644
index 911c6cc7..00000000
--- a/src/main/java/analyzer/Main.java
+++ /dev/null
@@ -1,68 +0,0 @@
-package analyzer;
-
-import com.github.javaparser.ParseResult;
-import com.github.javaparser.ast.CompilationUnit;
-import com.github.javaparser.utils.SourceRoot;
-
-import java.io.File;
-import java.io.FileWriter;
-import java.io.IOException;
-import java.nio.file.Path;
-import java.util.ArrayList;
-import java.util.List;
-
-public class Main {
-
- private static boolean isNotValidDirectory(String p) {
- return !p.endsWith("/") || !new File(p).isDirectory();
- }
-
- private static Options validateOptions(String... args) {
- if (args.length < 3) {
- System.err.println("Invalid arguments. Usage: java-analyzer