Updating documentation

diff --git a/doc/index.org b/doc/index.org
index ea82e8d..4dde3c1 100644 (file)
--- a/doc/index.org
+++ b/doc/index.org
@@ -22,16 +22,109 @@
 - See [[https://www3.svjatoslav.eu/projects/cli-helper/apidocs/][JavaDoc]]
 
 * Library contents
-- See [[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/][JavaDoc]].
+- See also: [[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/][CLI Helper JavaDoc]].
 
-- Commandline Interface helper
-  : eu.svjatoslav.commons.cli_helper.CLIHelper
+This library is a collection of command-line interface (CLI) helper
+functions that simplifies the process of building and maintaining CLI
+applications. The library provides several different functionalities,
+such as:
 
-- Commandline arguments parser and validator.
-  : eu.svjatoslav.commons.cli_helper.parameter_parser
+- [[id:4fca35e4-fdf1-4675-a36f-6206d6fb72cb][Asking for user input]]
+- Handling application command-line arguments
 
-* Usage
-Instructions to embed svjatoslav-commons in your project as a library:
+
+** Ask for user input
+:PROPERTIES:
+:ID:       4fca35e4-fdf1-4675-a36f-6206d6fb72cb
+:END:
+
+- askBoolean() :: Asks the user to enter a boolean value (yes/no).
+- askLong() :: Asks the user to enter an integer.
+- askString() :: Asks the user to enter a string.
+
+** Command-line application CLI arguments processing
+*** Theory
+**** Commands and Arguments
+
+Every command-line application has a way of receiving input from
+users, usually in the form of command-line arguments. A command-line
+argument is a piece of information provided to the command-line
+application when it's invoked. These arguments are provided as an
+array of strings. The first element of the array (argument 0) is
+typically the name of the command itself.
+
+In the example below, 'my-video-coder' is our command, and the rest
+are arguments:
+
+#+BEGIN_SRC shell
+my-video-coder encode --input vid1.mp4 vid2.mp4 vid3.mp4 --quality 5
+#+END_SRC
+
+To better understand how these concepts work together, let's break
+down our example command:
+
+| argument # | type                   | values                     |
+|------------+------------------------+----------------------------|
+|          0 | command                | my-video-coder             |
+|          1 | subcommand             | encode                     |
+|          2 | option1                | --input                    |
+|    3, 4, 5 | parameters for option1 | vid1.mp4 vid2.mp4 vid3.mp4 |
+|          6 | option2                | --quality                  |
+|          7 | parameters for option2 | 5                          |
+
+**** Options
+
+Options are arguments that change the behavior of a command. They
+usually start with a dash (-) or double dash (--). For instance,
+'--input' and '--quality' are options in our example command.
+
+**** Parameters
+
+A parameter provides additional information to a command or
+option. For instance, 'vid1.mp4 vid2.mp4 vid3.mp4' are parameters for
+the '--input' option, and '5' is a parameter for the '--quality'
+option in our example command.
+
+**** Positional Parameters
+
+These are the arguments that follow the command and are usually
+required for the command to execute. In our example, 'encode' is a
+positional parameter.
+
+**** Subcommands
+
+Subcommands are more specific actions that a command can perform. They
+are often used with commands that have multiple functions. In our
+example, 'encode' is a subcommand of 'my-video-coder'.
+
+*** Implementation
+
+Parsing Command-line Arguments:
+- `Parameter` class is used for defining parameters with their
+  descriptions, types, and aliases. It also keeps track of whether the
+  specific parameter was present in the command line or not. This
+  information is used later in the processing.
+
+  - `DirectoryParameter`, `FileParameter`, `IntegerParameter`,
+    `StringParameter`, `NullParameter`, and `StringParameters` are
+    examples of Parameter classes, each one having unique
+    characteristics for handling specific types of parameters
+    (directories, files, integers, strings, etc.).
+
+- `ArgumentCount` class determines if a parameter can have any amount
+  of arguments (MULTI), exactly one argument (SINGLE), or no arguments
+  (NONE).
+
+- `Parser` class takes all these parameters and checks whether all
+  required arguments are provided and if they match the expected
+  format.
+
+**** Usage example
+
+TODO:
+
+* Getting the library
+Instructions to embed svjatoslav-commons library in your project:
 
 Maven pom.xml file snippet:
 

diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/ArgumentCount.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/ArgumentCount.java
index 1d830a3..3d8ed7f 100755 (executable)
--- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/ArgumentCount.java
+++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/ArgumentCount.java
@@ -6,8 +6,17 @@ package eu.svjatoslav.commons.cli_helper.parameter_parser;
 
 public enum ArgumentCount {
 
-    NONE, // parameter has no arguments
-    SINGLE, // parameter has one argument
-    MULTI // parameter can have multiple arguments
+    /**
+     * Parameter has no arguments.
+     */
+    NONE,
+    /**
+     * Parameter has exactly one argument.
+     */
+    SINGLE,
 
+    /**
+     * Parameter can have any amount of arguments.
+     */
+    MULTI
 }

diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Parameter.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Parameter.java
index 92c5c81..f360ddc 100755 (executable)
--- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Parameter.java
+++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Parameter.java
@@ -17,6 +17,9 @@ public abstract class Parameter<T, I extends Parameter> {
      */
     public final String description;
 
+    /**
+     * List of arguments for this parameter.
+     */
     public final List<String> arguments = new ArrayList<>();
     final ArgumentCount argumentCount;
     private final List<String> aliases = new ArrayList<>();