Prechádzať zdrojové kódy

[192-webreport] Added javadoc

Evgeni 4 rokov pred
rodič
commit
d32fb7c9a3

+ 4 - 0
jplag/src/main/java/de/jplag/reportingV2/JsonReport.java

@@ -8,6 +8,10 @@ import de.jplag.reportingV2.reportobject.model.JPlagReport;
 import java.util.List;
 import java.util.List;
 
 
 //ReportImplementation -> JsonReport
 //ReportImplementation -> JsonReport
+
+/**
+ * A report generator which reports the JPlagResult in Json format.
+ */
 public class JsonReport implements Report {
 public class JsonReport implements Report {
 
 
 	@Override
 	@Override

+ 17 - 0
jplag/src/main/java/de/jplag/reportingV2/Report.java

@@ -6,8 +6,25 @@ import de.jplag.reportingV2.reportobject.model.JPlagReport;
 import java.util.List;
 import java.util.List;
 
 
 //ReportStrategy -> Report
 //ReportStrategy -> Report
+
+/**
+ *  Strategy interface for reporting. A report generator should implement this interface.
+ */
 public interface Report {
 public interface Report {
 
 
+	/**
+	 * This function returns a list containing the report objects as simple strings.
+	 * The first element is the string of the overview object. Each following element is a string
+	 * of a comparison report object.
+	 * @param result The result of a JPlag comparison
+	 * @return A list containing report objects to string. First element is Overview. Other elements are comparisons.
+	 */
 	List<String> getReportStrings(JPlagResult result);
 	List<String> getReportStrings(JPlagResult result);
+
+	/**
+	 * Creates and saves JPlag report files to the disk.
+	 * @param result The result of a JPlag comparison.
+	 * @return True if the process is successful, otherwise false.
+	 */
 	boolean saveReport(JPlagResult result);
 	boolean saveReport(JPlagResult result);
 }
 }

+ 15 - 0
jplag/src/main/java/de/jplag/reportingV2/jsonfactory/JsonFactory.java

@@ -11,8 +11,17 @@ import java.io.IOException;
 import java.util.ArrayList;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.List;
 
 
+/**
+ * Factory class, responsible for creating Json strings and writing them to files.
+ */
 public class JsonFactory {
 public class JsonFactory {
 
 
+	/**
+	 * Uses Jackson to create Json Strings from JPlagReport object.
+	 * @param jPlagReport
+	 * @return A list, first element is Json String of Overview object. The rest elements are Json Strings of
+	 * Comparison objects.
+	 */
 	public static List<String> getJsonStrings(JPlagReport jPlagReport) {
 	public static List<String> getJsonStrings(JPlagReport jPlagReport) {
 		List<String> jsonReports = new ArrayList<>();
 		List<String> jsonReports = new ArrayList<>();
 		try {
 		try {
@@ -27,6 +36,12 @@ public class JsonFactory {
 		return jsonReports;
 		return jsonReports;
 	}
 	}
 
 
+	/**
+	 * Creates Json Files for the given JPlagReport and saves them in the given folder.
+	 * @param jPlagReport
+	 * @param folderPath
+	 * @return A boolean, representing whether the process was successful.
+	 */
 	public static boolean saveJsonFiles(JPlagReport jPlagReport, String folderPath ) {
 	public static boolean saveJsonFiles(JPlagReport jPlagReport, String folderPath ) {
 		String sanitizedFolderPath = folderPath;
 		String sanitizedFolderPath = folderPath;
 		if ( !folderPath.endsWith("/") ) { sanitizedFolderPath = folderPath.concat("/"); }
 		if ( !folderPath.endsWith("/") ) { sanitizedFolderPath = folderPath.concat("/"); }

+ 60 - 1
jplag/src/main/java/de/jplag/reportingV2/reportobject/ReportObjectFactory.java

@@ -13,14 +13,27 @@ import java.text.SimpleDateFormat;
 import java.util.*;
 import java.util.*;
 import java.util.stream.Collectors;
 import java.util.stream.Collectors;
 
 
+/**
+ * Factory class, responsible for converting a JPlagResult object to Overview and Comparison DTO classes.
+ */
 public class ReportObjectFactory {
 public class ReportObjectFactory {
 
 
+	/**
+	 * Converts a JPlagResult to a JPlagReport.
+	 * @param result
+	 * @return JPlagReport for the given JPlagResult.
+	 */
 	public static JPlagReport getReportObject(JPlagResult result) {
 	public static JPlagReport getReportObject(JPlagResult result) {
 		OverviewReport overviewReport = generateOverviewReport(result);
 		OverviewReport overviewReport = generateOverviewReport(result);
 		List<ComparisonReport> comparisons = generateComparisonReports(result);
 		List<ComparisonReport> comparisons = generateComparisonReports(result);
 		return new JPlagReport(overviewReport, comparisons);
 		return new JPlagReport(overviewReport, comparisons);
 	}
 	}
 
 
+	/**
+	 * Generates an Overview DTO of a JPlagResult.
+	 * @param result
+	 * @return
+	 */
 	private static  OverviewReport generateOverviewReport(JPlagResult result) {
 	private static  OverviewReport generateOverviewReport(JPlagResult result) {
 		List<JPlagComparison> comparisons = result.getComparisons();
 		List<JPlagComparison> comparisons = result.getComparisons();
 		OverviewReport overviewReport = new OverviewReport();
 		OverviewReport overviewReport = new OverviewReport();
@@ -44,6 +57,11 @@ public class ReportObjectFactory {
 		return overviewReport;
 		return overviewReport;
 	}
 	}
 
 
+	/**
+	 * Generates detailed ComparisonReport DTO for each comparison in a JPlagResult.
+	 * @param result
+	 * @return A list with ComparisonReport DTOs.
+	 */
 	private static List<ComparisonReport> generateComparisonReports(JPlagResult result) {
 	private static List<ComparisonReport> generateComparisonReports(JPlagResult result) {
 		List<ComparisonReport> comparisons = new ArrayList<>();
 		List<ComparisonReport> comparisons = new ArrayList<>();
 		result.getComparisons().forEach( c -> comparisons.add(
 		result.getComparisons().forEach( c -> comparisons.add(
@@ -60,6 +78,11 @@ public class ReportObjectFactory {
 		return comparisons;
 		return comparisons;
 	}
 	}
 
 
+	/**
+	 * Gets the names of all submissions.
+	 * @param comparisons
+	 * @return A list containing all submission names.
+	 */
 	private static List<String> extractSubmissionNames(List<JPlagComparison> comparisons) {
 	private static List<String> extractSubmissionNames(List<JPlagComparison> comparisons) {
 		HashSet<String> names = new HashSet<>();
 		HashSet<String> names = new HashSet<>();
 		comparisons.forEach(c -> {
 		comparisons.forEach(c -> {
@@ -69,6 +92,11 @@ public class ReportObjectFactory {
 		return new ArrayList<>(names);
 		return new ArrayList<>(names);
 	}
 	}
 
 
+	/**
+	 * Gets the names of all comparison.
+	 * @param comparisons
+	 * @return A list containing all comparisons.
+	 */
 	private static List<String> getComparisonNames(List<JPlagComparison> comparisons) {
 	private static List<String> getComparisonNames(List<JPlagComparison> comparisons) {
 		List<String> names = new ArrayList<>();
 		List<String> names = new ArrayList<>();
 		comparisons.forEach(
 		comparisons.forEach(
@@ -78,6 +106,12 @@ public class ReportObjectFactory {
 	}
 	}
 
 
 	// Currently, only one metric can be obtained.
 	// Currently, only one metric can be obtained.
+
+	/**
+	 * Gets the used metric in a JPlag comparison.
+	 * @param result
+	 * @return A list contains Metric DTOs.
+	 */
 	private static List<Metric> getMetrics(JPlagResult result) {
 	private static List<Metric> getMetrics(JPlagResult result) {
 		List<Metric> metrics = new ArrayList<>();
 		List<Metric> metrics = new ArrayList<>();
 		metrics.add(new Metric(
 		metrics.add(new Metric(
@@ -89,12 +123,25 @@ public class ReportObjectFactory {
 		return metrics;
 		return metrics;
 	}
 	}
 
 
+
+	/**
+	 * Converts JPlagComparison to a DTO for displaying only comparisons. See {@link #generateComparisonReports(JPlagResult)}
+	 * for a more detailed representation of a comparison.
+	 * @param comparisons
+	 * @return List containing TopComparison DTOs.
+	 */
 	private static List<TopComparison> getTopComparisons(List<JPlagComparison> comparisons) {
 	private static List<TopComparison> getTopComparisons(List<JPlagComparison> comparisons) {
 		List<TopComparison> topComparisons = new ArrayList<>();
 		List<TopComparison> topComparisons = new ArrayList<>();
 		comparisons.forEach( c -> topComparisons.add(new TopComparison(c.getFirstSubmission().getName(), c.getSecondSubmission().getName(), c.similarity())));
 		comparisons.forEach( c -> topComparisons.add(new TopComparison(c.getFirstSubmission().getName(), c.getSecondSubmission().getName(), c.similarity())));
 		return topComparisons;
 		return topComparisons;
 	}
 	}
 
 
+	/**
+	 * Gets the names of excluded files in a JPlag comparison.
+	 * To be changed in the future to direct access to the file names. No file reading.
+	 * @param options
+	 * @return List with the names of the files.
+	 */
 	private static List<String> getExcludedFilesNames(JPlagOptions options) {
 	private static List<String> getExcludedFilesNames(JPlagOptions options) {
 		if (options.getExclusionFileName() == null) {
 		if (options.getExclusionFileName() == null) {
 			return List.of();
 			return List.of();
@@ -117,11 +164,22 @@ public class ReportObjectFactory {
 		return new ArrayList<>(excludedFileNames);
 		return new ArrayList<>(excludedFileNames);
 	}
 	}
 
 
-
+	/**
+	 * Converts files of a submission to FilesOFSubmission DTO.
+	 * @param submission
+	 * @return A list containing FilesOfSubmission DTOs.
+	 */
 	private static List<FilesOfSubmission> getFilesForSubmission(Submission submission) {
 	private static List<FilesOfSubmission> getFilesForSubmission(Submission submission) {
 		return submission.getFiles().stream().map( f -> new FilesOfSubmission(f.getName(), readFileLines(f))).collect(Collectors.toList());
 		return submission.getFiles().stream().map( f -> new FilesOfSubmission(f.getName(), readFileLines(f))).collect(Collectors.toList());
 	}
 	}
 
 
+	/**
+	 * Converts a JPlag Match object to a Match DTO.
+	 * @param comparison The comparison from which the match originates.
+	 * @param match The match to be converted.
+	 * @param usesIndex Indicates whether the language uses indexes.
+	 * @return A Match DTO.
+	 */
 	private static Match convertMatchToReportMatch(JPlagComparison comparison, de.jplag.Match match, Boolean usesIndex) {
 	private static Match convertMatchToReportMatch(JPlagComparison comparison, de.jplag.Match match, Boolean usesIndex) {
 		TokenList tokensFirst = comparison.getFirstSubmission().getTokenList();
 		TokenList tokensFirst = comparison.getFirstSubmission().getTokenList();
 		TokenList tokensSecond = comparison.getSecondSubmission().getTokenList();
 		TokenList tokensSecond = comparison.getSecondSubmission().getTokenList();
@@ -144,6 +202,7 @@ public class ReportObjectFactory {
 				tokens
 				tokens
 		);
 		);
 	}
 	}
+
 	private static List<String> readFileLines(File file) {
 	private static List<String> readFileLines(File file) {
 		ArrayList<String> lines = new ArrayList<>();
 		ArrayList<String> lines = new ArrayList<>();
 		try {
 		try {