From: Svjatoslav Agejenko Date: Sun, 29 Oct 2023 21:21:15 +0000 (+0200) Subject: Add Javadoc comments to enhance code clarity X-Git-Tag: cli-helper-1.1~1 X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=b4b3152b0012f4e0b0b5d3e98cc8a7e4a12e8c18;p=cli-helper.git Add Javadoc comments to enhance code clarity Added Javadoc comments to Option and Parameter classes to provide a more detailed explanation of their functionalities. Changes include explanations for each method and variable in these classes. This aims to improve code readability and provide clearer direction for future development. --- diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Option.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Option.java index 9bcea3f..d591663 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Option.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Option.java @@ -12,6 +12,14 @@ import static java.lang.String.join; import static java.util.Collections.addAll; import static java.util.stream.Collectors.joining; +/** + * Represents an option that can be provided on CLI. + * This class allows specifying whether the option is mandatory, + * the parameter count, a description, and any aliases for the option. + * + * @param type of value that this option returns. + * @param type of this option. + */ public abstract class Option { /** @@ -43,6 +51,16 @@ public abstract class Option { */ private boolean isPresent; + /** + * Represents an option that can be provided on CLI. + * This class allows specifying whether the option is mandatory, + * the parameter count, a description, and any aliases for the option. + * + * @param mandatory indicates whether the option is mandatory + * @param parameterCount the number of parameters required for the option + * @param description a description of the option + * @param aliases2 any additional aliases for the option + */ public Option(final boolean mandatory, final ParameterCount parameterCount, final String description, final String... aliases2) { @@ -60,6 +78,12 @@ public abstract class Option { this.parameterCount = parameterCount; } + /** + * Adds additional aliases to the option. + * + * @param aliasArray an array of strings representing the aliases to be added + * @return the modified option object + */ @SuppressWarnings("unchecked") public I addAliases(final String... aliasArray) { @@ -117,7 +141,9 @@ public abstract class Option { } /** - * @return help for this option. + * Returns the help message for this parameter. + * + * @return the help message as a string. */ public String getHelp() { final StringBuilder result = new StringBuilder(); @@ -142,6 +168,11 @@ public abstract class Option { return result.toString(); } + /** + * Returns the value of the object. + * + * @return the value of the object. + */ public abstract T getValue(); public boolean isMandatory() { @@ -149,14 +180,17 @@ public abstract class Option { } /** - * @return the parameterSpecified + * @return true if this parameter was present in the commandline. */ public boolean isPresent() { return isPresent; } /** - * @param present the parameterSpecified to set + * Sets the present status of this parameter. + * + * @param present true if this parameter is present in the command line, + * false otherwise. */ protected void setPresent(final boolean present) { this.isPresent = present; @@ -192,6 +226,12 @@ public abstract class Option { return true; } + /** + * Sets the option as mandatory. This means that the option must be provided by the user + * in order for the program to run successfully. + * + * @return The updated instance of the option. + */ @SuppressWarnings("unchecked") public I setMandatory() { mandatory = true; diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/DirectoryOption.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/DirectoryOption.java index 718aa09..ee52751 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/DirectoryOption.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/DirectoryOption.java @@ -9,10 +9,22 @@ import eu.svjatoslav.commons.cli_helper.parameter_parser.Option; import java.io.File; + +/** + * This class is used to define commandline option which accepts directory as parameter. + */ public class DirectoryOption extends Option { + /** + * This enum is used to define if directory shall exist in filesystem or not. + */ private ExistenceType existenceType = ExistenceType.DOES_NOT_MATTER; + /** + * Constructor. + * + * @param description Description of the option. + */ public DirectoryOption(final String description) { super(description, ParameterCount.ONE); } @@ -29,6 +41,12 @@ public class DirectoryOption extends Option { } } + /** + * Retrieves the value of the option as a {@link File} object. + * + * @return The value of the option as a {@link File} object. + * @throws RuntimeException if the option does not have exactly 1 argument. + */ @Override public File getValue() { @@ -39,16 +57,32 @@ public class DirectoryOption extends Option { return new File(parameters.get(0)); } + /** + * This method sets that directory shall exist. + * + * @return This object. + */ public DirectoryOption mustExist() { existenceType = ExistenceType.MUST_EXIST; return this; } + /** + * This method sets that directory shall not exist. + * + * @return This object. + */ public DirectoryOption mustNotExist() { existenceType = ExistenceType.MUST_NOT_EXIST; return this; } + /** + * This method checks if a provided directory path is valid based on the specified existence type. + * + * @param value The directory path to validate. + * @return True if the directory path is valid according to the existence type, otherwise false. + */ @Override public boolean isValid(final java.lang.String value) { final File file = new File(value); diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/DirectoryOptions.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/DirectoryOptions.java index 2632174..d012cf9 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/DirectoryOptions.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/DirectoryOptions.java @@ -11,14 +11,32 @@ import java.io.File; import java.util.List; import java.util.stream.Collectors; +/** + * DirectoryOptions class represents a command-line option for one or more directories. + */ public class DirectoryOptions extends Option, DirectoryOptions> { + /** + * This enum is used to define if resource denoted by particular option parameter shall exist or not. + *

+ * This allows to specify for example if directory shall exist or not. + */ private ExistenceType existenceType = ExistenceType.DOES_NOT_MATTER; + /** + * Creates a new DirectoryOptions object with the given description. + * + * @param description The description of the directory options. + */ public DirectoryOptions(final String description) { super(description, ParameterCount.ONE_OR_MORE); } + /** + * Returns a string describing the format of the option. + * + * @return A string describing the format of the option. + */ @Override public String describeFormat() { switch (existenceType) { @@ -31,6 +49,11 @@ public class DirectoryOptions extends Option, DirectoryOptions> { } } + /** + * Returns the value of the option as a list of File objects. + * + * @return The value of the option as a list of File objects. + */ @Override public List getValue() { return parameters.stream().map(File::new).collect(Collectors.toList()); @@ -46,6 +69,7 @@ public class DirectoryOptions extends Option, DirectoryOptions> { return this; } + @Override public boolean isValid(final String value) { final File file = new File(value); diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/FileOption.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/FileOption.java index 935ea9f..c10ec1e 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/FileOption.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/FileOption.java @@ -9,6 +9,10 @@ import eu.svjatoslav.commons.cli_helper.parameter_parser.Option; import java.io.File; +/** + * This class represents commandline option which accepts exactly one parameter + * which is a file. + */ public class FileOption extends Option { private ExistenceType existenceType = ExistenceType.DOES_NOT_MATTER; @@ -61,11 +65,21 @@ public class FileOption extends Option { return new File(parameters.get(0)); } + /** + * This method sets that file shall exist. + * + * @return This object. + */ public FileOption mustExist() { existenceType = ExistenceType.MUST_EXIST; return this; } + /** + * This method sets that file shall not exist. + * + * @return This object. + */ public FileOption mustNotExist() { existenceType = ExistenceType.MUST_NOT_EXIST; return this; diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/FileOptions.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/FileOptions.java index 6c6e51c..9534224 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/FileOptions.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/FileOptions.java @@ -13,6 +13,10 @@ import java.util.stream.Collectors; import static eu.svjatoslav.commons.cli_helper.parameter_parser.parameter.FileOption.validateFile; +/** + * This class represents commandline option which accepts one or more parameters + * which are files. + */ public class FileOptions extends Option, FileOptions> { private ExistenceType existenceType = ExistenceType.DOES_NOT_MATTER; @@ -38,11 +42,21 @@ public class FileOptions extends Option, FileOptions> { return parameters.stream().map(File::new).collect(Collectors.toList()); } + /** + * This method is used to define that file shall exist in filesystem. + * + * @return This object. + */ public FileOptions mustExist() { existenceType = ExistenceType.MUST_EXIST; return this; } + /** + * This method is used to define that file shall not exist in filesystem. + * + * @return This object. + */ public FileOptions mustNotExist() { existenceType = ExistenceType.MUST_NOT_EXIST; return this; diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/IntegerOption.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/IntegerOption.java index 7a5b2b7..592ab00 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/IntegerOption.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/IntegerOption.java @@ -7,6 +7,10 @@ package eu.svjatoslav.commons.cli_helper.parameter_parser.parameter; import eu.svjatoslav.commons.cli_helper.parameter_parser.ParameterCount; import eu.svjatoslav.commons.cli_helper.parameter_parser.Option; +/** + * This class represents commandline option which accepts exactly one parameter + * which is an integer. + */ public class IntegerOption extends Option { public IntegerOption(final String description) { diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/NullOption.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/NullOption.java index a2a2e8e..9b5ad88 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/NullOption.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/NullOption.java @@ -7,6 +7,9 @@ package eu.svjatoslav.commons.cli_helper.parameter_parser.parameter; import eu.svjatoslav.commons.cli_helper.parameter_parser.ParameterCount; import eu.svjatoslav.commons.cli_helper.parameter_parser.Option; +/** + * This class represents commandline option which accepts exactly zero parameters. + */ public class NullOption extends Option { public NullOption(final String description) { diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/StringOption.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/StringOption.java index 25448dc..d7cb3e7 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/StringOption.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/StringOption.java @@ -7,6 +7,10 @@ package eu.svjatoslav.commons.cli_helper.parameter_parser.parameter; import eu.svjatoslav.commons.cli_helper.parameter_parser.ParameterCount; import eu.svjatoslav.commons.cli_helper.parameter_parser.Option; +/** + * This class represents commandline option which accepts exactly one parameter + * which is a string. + */ public class StringOption extends Option { public final String defaultValue; diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/StringOptions.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/StringOptions.java index ccbc39e..5b140bc 100644 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/StringOptions.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/parameter/StringOptions.java @@ -9,6 +9,10 @@ import eu.svjatoslav.commons.cli_helper.parameter_parser.Option; import java.util.List; +/** + * This class represents commandline option which accepts one or more parameters + * which are strings. + */ public class StringOptions extends Option, StringOptions> { public StringOptions(final String description) {