From 8b4555b70a2b5ad7f2ac83594d08d3f620a5fbc9 Mon Sep 17 00:00:00 2001 From: HCY123902 <54735123+HCY123902@users.noreply.github.com> Date: Thu, 17 Dec 2020 20:45:53 +0800 Subject: [PATCH] [#1202] Add Javadoc for backend functions (#1364) Some methods in `StreamGobbler`, `CustomLogFormatter`, `FileType`, and `RepoConfiguration` do not have Javadoc although the methods are not standard getter or setter. To enhance readability, it may be necessary to explain what they do, especially for `run()` in `StreamGobbler` since the method name may not give enough information. Additionally, there is a colon missing in the developer guide architecture section. Let's add Javadoc to these methods and also add the missing colon to the developer guide to make documentation more consistent. --- docs/dg/architecture.md | 2 +- src/main/java/reposense/model/FileType.java | 4 ++++ src/main/java/reposense/model/RepoConfiguration.java | 8 ++++++++ src/main/java/reposense/system/CustomLogFormatter.java | 4 ++++ src/main/java/reposense/system/LogsManager.java | 5 +++-- src/main/java/reposense/system/StreamGobbler.java | 3 +++ 6 files changed, 23 insertions(+), 3 deletions(-) diff --git a/docs/dg/architecture.md b/docs/dg/architecture.md index 545aef93ec..aa3a2aa9ba 100644 --- a/docs/dg/architecture.md +++ b/docs/dg/architecture.md @@ -17,7 +17,7 @@ * [`ArgsParser`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/parser/ArgsParser.java): Parses the user-supplied command line arguments into a `CliArguments` object. * [`CsvParser`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/parser/CsvParser.java): Abstract generic class for CSV parsing functionality. The following three classes extend `CsvParser`. * [`AuthorConfigCsvParser`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/parser/AuthorConfigCsvParser.java): Parses the `author-config.csv` config file into a list of `AuthorConfiguration` for each repository to analyze. - * [`GroupConfigCsvParser`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/parser/GroupConfigCsvParser.java) Parses the `group-config.csv` config file into a list of `GroupConfiguration` for each repository to analyze. + * [`GroupConfigCsvParser`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/parser/GroupConfigCsvParser.java): Parses the `group-config.csv` config file into a list of `GroupConfiguration` for each repository to analyze. * [`RepoConfigCsvParser`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/parser/RepoConfigCsvParser.java): Parses the `repo-config.csv` config file into a list of `RepoConfiguration` for each repository to analyze. * [`JsonParser`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/parser/JsonParser.java): Abstract generic class for JSON parsing functionality. The following class extends `JsonParser` class: * [`StandaloneConfigJsonParser`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/parser/StandaloneConfigJsonParser.java): Parses the `_reposense/config.json` config file into a `StandaloneConfig`. diff --git a/src/main/java/reposense/model/FileType.java b/src/main/java/reposense/model/FileType.java index 1d6ddad89e..cf00d30ca1 100644 --- a/src/main/java/reposense/model/FileType.java +++ b/src/main/java/reposense/model/FileType.java @@ -32,6 +32,10 @@ public FileType(String label, List paths) { setPaths(paths); } + /** + * Returns a list of {@code FileType} from {@code formats}, with each {@code FileType} + * containing the format name and associated files ending with the format. + */ public static List convertFormatStringsToFileTypes(List formats) { return formats.stream().map(FileType::convertStringFormatToFileType).collect(Collectors.toList()); } diff --git a/src/main/java/reposense/model/RepoConfiguration.java b/src/main/java/reposense/model/RepoConfiguration.java index 15a82abb3a..f0c31f1c7a 100644 --- a/src/main/java/reposense/model/RepoConfiguration.java +++ b/src/main/java/reposense/model/RepoConfiguration.java @@ -332,10 +332,18 @@ public void setBranch(String branch) { authorConfig.setBranch(branch); } + /** + * Updates the branch in the {@code displayName} to the + * current {@code branch}. + */ public void updateDisplayName(String branch) { this.displayName = displayName.substring(0, displayName.lastIndexOf('[') + 1) + branch + "]"; } + /** + * Updates the branch in the {@code outputFolderName} to the + * current {@code branch}. + */ public void updateOutputFolderName(String branch) { this.outputFolderName = outputFolderName.substring(0, outputFolderName.lastIndexOf('_') + 1) + branch; } diff --git a/src/main/java/reposense/system/CustomLogFormatter.java b/src/main/java/reposense/system/CustomLogFormatter.java index 76f0021abb..115d69481d 100644 --- a/src/main/java/reposense/system/CustomLogFormatter.java +++ b/src/main/java/reposense/system/CustomLogFormatter.java @@ -32,6 +32,10 @@ public CustomLogFormatter() { AnsiConsole.systemInstall(); } + /** + * Returns the string representation of the {@code record} with + * the timestamp in hh:mm:ss and the record severity level if applicable. + */ @Override public synchronized String format(LogRecord record) { StringBuilder builder = new StringBuilder(); diff --git a/src/main/java/reposense/system/LogsManager.java b/src/main/java/reposense/system/LogsManager.java index b4725f9977..eff90c8ef7 100644 --- a/src/main/java/reposense/system/LogsManager.java +++ b/src/main/java/reposense/system/LogsManager.java @@ -125,8 +125,9 @@ private static ConsoleHandler createConsoleHandler() { return consoleHandler; } - /** Sets the log folder location using {@code location} and adds file handler with this location to all the loggers - * created. + /** + * Sets the log folder location using {@code location} and adds file handler with this location to all the loggers + * created. */ public static void setLogFolderLocation(Path location) { logFolderLocation = location; diff --git a/src/main/java/reposense/system/StreamGobbler.java b/src/main/java/reposense/system/StreamGobbler.java index b4b74997be..7b5fcef114 100644 --- a/src/main/java/reposense/system/StreamGobbler.java +++ b/src/main/java/reposense/system/StreamGobbler.java @@ -24,6 +24,9 @@ public String getValue() { return value; } + /** + * Reads from input stream {@code is} and stores it into {@code value}. + */ @Override public void run() { try {