YT-CPPAP-4: Extend argument description

- Added the `argument_parser::verbose` function which can be used to set the description verbosity mode
- Aligned the argument description generating to:
  - Align the argument help messages (when verbose=false)
  - Print the argument parameter values (when verbose=true)
- Added missing file doc comments

Author: SpectraL519

CMakeLists.txt

@@ -7,7 +7,7 @@ else()
 endif()
 
 project(cpp-ap
-    VERSION 2.0.2
+    VERSION 2.1.0
     DESCRIPTION "Command-line argument parser for C++20"
     HOMEPAGE_URL "https://github.com/SpectraL519/cpp-ap"
     LANGUAGES CXX

Doxyfile

@@ -48,7 +48,7 @@ PROJECT_NAME           = "CPP-AP"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2.0.2
+PROJECT_NUMBER         = 2.1.0
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

include/ap/action/detail/utility.hpp

@@ -2,6 +2,11 @@
 // This file is part of the CPP-AP project (https://github.com/SpectraL519/cpp-ap).
 // Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
+/**
+ * @file utility.hpp
+ * @brief Defines general action-related utility.
+ */
+
 #pragma once
 
 #include "ap/action/specifiers.hpp"

include/ap/action/predefined_actions.hpp

@@ -2,6 +2,8 @@
 // This file is part of the CPP-AP project (https://github.com/SpectraL519/cpp-ap).
 // Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
+/// @file predefined_actions.hpp
+
 #pragma once
 
 #include "ap/error/exceptions.hpp"

include/ap/action/specifiers.hpp

@@ -2,6 +2,11 @@
 // This file is part of the CPP-AP project (https://github.com/SpectraL519/cpp-ap).
 // Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
+/**
+ * @file specifiers.hpp
+ * @brief Defies the action specifier types.
+ */
+
 #pragma once
 
 #include "ap/detail/concepts.hpp"
@@ -10,11 +15,7 @@
 
 namespace ap::action_type {
 
-// TODO:
-// * on_read_action
-// * on_flag_action
-
-/*
+/**
  * @brief Represents a transformating action.
  *
  * Represents an argument action which transforms the parsed value and
@@ -25,7 +26,7 @@ struct transform {
     using type = std::function<T(const T&)>;
 };
 
-/*
+/**
  * @brief Represents a modifying action.
  *
  * Represents an argument action which modifies the value of an

include/ap/argument/default.hpp

@@ -2,6 +2,11 @@
 // This file is part of the CPP-AP project (https://github.com/SpectraL519/cpp-ap).
 // Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
+/**
+ * @file default.hpp
+ * @brief Defines the default argument discriminator types.
+ */
+
 #pragma once
 
 #include <cstdint>

include/ap/argument/optional.hpp

@@ -2,10 +2,13 @@
 // This file is part of the CPP-AP project (https://github.com/SpectraL519/cpp-ap).
 // Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
+/// @file optional.hpp
+
 #pragma once
 
 #include "ap/action/detail/utility.hpp"
 #include "ap/action/predefined_actions.hpp"
+#include "ap/detail/argument_descriptor.hpp"
 #include "ap/detail/argument_interface.hpp"
 #include "ap/detail/concepts.hpp"
 #include "ap/nargs/range.hpp"
@@ -55,7 +58,7 @@ class optional : public ap::detail::argument_interface {
      * @param help_msg The help message to set.
      * @return Reference to the optional argument.
      */
-    optional& help(std::string_view help_msg) noexcept override {
+    optional& help(std::string_view help_msg) noexcept {
         this->_help_msg = help_msg;
         return *this;
     }
@@ -200,6 +203,35 @@ class optional : public ap::detail::argument_interface {
         return this->_help_msg;
     }
 
+    /**
+     * @param verbose The verbosity mode value.
+     * @return An argument_descriptor instance for the argument.
+     */
+    [[nodiscard]] detail::argument_descriptor desc(const bool verbose) const noexcept override {
+        detail::argument_descriptor desc(this->_name.str(), this->_help_msg);
+
+        if (not verbose)
+            return desc;
+
+        desc.params.reserve(6);
+        if (this->_required)
+            desc.add_param("required", "true");
+        if (this->_bypass_required)
+            desc.add_param("bypass required", "true");
+        if (this->_nargs_range.has_value())
+            desc.add_param("nargs", this->_nargs_range.value());
+        if constexpr (detail::c_writable<value_type>) {
+            if (not this->_choices.empty())
+                desc.add_range_param("choices", this->_choices);
+            if (this->_default_value.has_value())
+                desc.add_param("default value", std::any_cast<value_type>(this->_default_value));
+            if (this->_implicit_value.has_value())
+                desc.add_param("implicit value", std::any_cast<value_type>(this->_implicit_value));
+        }
+
+        return desc;
+    }
+
     /// @return True if the optional argument is required, false otherwise.
     [[nodiscard]] bool is_required() const noexcept override {
         return this->_required;

include/ap/argument/positional.hpp

@@ -2,6 +2,8 @@
 // This file is part of the CPP-AP project (https://github.com/SpectraL519/cpp-ap).
 // Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
+/// @file positional.hpp
+
 #pragma once
 
 #include "ap/action/detail/utility.hpp"
@@ -53,7 +55,7 @@ class positional : public ap::detail::argument_interface {
      * @param help_msg The help message to set.
      * @return Reference to the positional argument.
      */
-    positional& help(std::string_view help_msg) noexcept override {
+    positional& help(std::string_view help_msg) noexcept {
         this->_help_msg = help_msg;
         return *this;
     }
@@ -106,7 +108,6 @@ class positional : public ap::detail::argument_interface {
         return this->_optional;
     }
 
-
     /// @brief Friend class declaration for access by argument_parser.
     friend class ::ap::argument_parser;
 
@@ -128,6 +129,24 @@ class positional : public ap::detail::argument_interface {
         return this->_help_msg;
     }
 
+    /**
+     * @param verbose The verbosity mode value.
+     * @return An argument_descriptor instance for the argument.
+     */
+    [[nodiscard]] detail::argument_descriptor desc(const bool verbose) const noexcept override {
+        detail::argument_descriptor desc(this->_name.str(), this->_help_msg);
+
+        if (not verbose)
+            return desc;
+
+        if constexpr (detail::c_writable<value_type>) {
+            if (not this->_choices.empty())
+                desc.add_range_param("choices", this->_choices);
+        }
+
+        return desc;
+    }
+
     /// @return True if the positional argument is required, false otherwise
     [[nodiscard]] bool is_required() const noexcept override {
         return this->_required;

include/ap/argument_parser.hpp

@@ -2,6 +2,11 @@
 // This file is part of the CPP-AP project (https://github.com/SpectraL519/cpp-ap).
 // Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
+/**
+ * @file argument_parser.hpp
+ * @brief Main library header file. Defines the `argument_parser` class.
+ */
+
 #pragma once
 
 #include "argument/default.hpp"
@@ -11,6 +16,7 @@
 #include "detail/concepts.hpp"
 
 #include <algorithm>
+#include <format>
 #include <ranges>
 #include <span>
 
@@ -68,6 +74,17 @@ class argument_parser {
         return *this;
     }
 
+    /**
+     * @brief Set the verbosity mode.
+     * @note The default verbosity mode value is `false`.
+     * @param v The verbosity mode value.
+     * @return Reference to the argument parser.
+     */
+    argument_parser& verbose(const bool v = true) noexcept {
+        this->_verbose = v;
+        return *this;
+    }
+
     /**
      * @brief Set default positional arguments.
      * @tparam AR Type of the positional argument discriminator range.
@@ -87,7 +104,7 @@ class argument_parser {
      * @return Reference to the argument parser.
      */
     argument_parser& default_positional_arguments(
-        std::initializer_list<argument::default_positional> arg_discriminator_list
+        const std::initializer_list<argument::default_positional> arg_discriminator_list
     ) noexcept {
         return this->default_positional_arguments<>(arg_discriminator_list);
     }
@@ -111,7 +128,7 @@ class argument_parser {
      * @return Reference to the argument parser.
      */
     argument_parser& default_optional_arguments(
-        std::initializer_list<argument::default_optional> arg_discriminator_list
+        const std::initializer_list<argument::default_optional> arg_discriminator_list
     ) noexcept {
         return this->default_optional_arguments<>(arg_discriminator_list);
     }
@@ -418,23 +435,41 @@ class argument_parser {
 
     /**
      * @brief Prints the argument parser's details to an output stream.
+     * @param verbose The verbosity mode value.
      * @param os Output stream.
-     * @param parser The argument parser to print.
-     * @return The modified output stream.
      */
-    friend std::ostream& operator<<(std::ostream& os, const argument_parser& parser) noexcept {
-        if (parser._program_name)
-            os << parser._program_name.value() << std::endl;
+    void print_config(const bool verbose, std::ostream& os = std::cout) const noexcept {
+        if (this->_program_name)
+            os << "Program: " << this->_program_name.value() << std::endl;
 
-        if (parser._program_description)
-            os << parser._program_description.value() << std::endl;
+        if (this->_program_description)
+            os << "\n"
+               << std::string(this->_indent_width, ' ') << this->_program_description.value()
+               << std::endl;
 
-        for (const auto& argument : parser._positional_args)
-            os << "\t" << *argument << std::endl;
+        if (not this->_positional_args.empty()) {
+            os << "\nPositional arguments:\n";
+            this->_print(os, this->_positional_args);
+        }
 
-        for (const auto& argument : parser._optional_args)
-            os << "\t" << *argument << std::endl;
+        if (not this->_optional_args.empty()) {
+            os << "\nOptional arguments: [--,-]\n";
+            this->_print(os, this->_optional_args);
+        }
+    }
 
+    /**
+     * @brief Prints the argument parser's details to an output stream.
+     *
+     * An `os << parser` operation is equivalent to a `parser.print_config(_verbose, os)` call,
+     * where `_verbose` is the inner verbosity mode, which can be set with the @ref verbose function.
+     *
+     * @param os Output stream.
+     * @param parser The argument parser to print.
+     * @return The modified output stream.
+     */
+    friend std::ostream& operator<<(std::ostream& os, const argument_parser& parser) noexcept {
+        parser.print_config(parser._verbose, os);
         return os;
     }
 
@@ -547,10 +582,10 @@ class argument_parser {
      */
     [[nodiscard]] bool _is_flag(const std::string& arg) const noexcept {
         if (arg.starts_with(this->_flag_prefix))
-            return this->_is_arg_name_used({arg.substr(this->_flag_prefix_length)});
+            return this->_is_arg_name_used({arg.substr(this->_primary_flag_prefxi_length)});
 
         if (arg.starts_with(this->_flag_prefix_char))
-            return this->_is_arg_name_used({arg.substr(this->_flag_prefix_char_length)});
+            return this->_is_arg_name_used({arg.substr(this->_secondary_flag_prefix_length)});
 
         return false;
     }
@@ -561,9 +596,9 @@ class argument_parser {
      */
     void _strip_flag_prefix(std::string& arg_flag) const noexcept {
         if (arg_flag.starts_with(this->_flag_prefix))
-            arg_flag.erase(0, this->_flag_prefix_length);
+            arg_flag.erase(0, this->_primary_flag_prefxi_length);
         else
-            arg_flag.erase(0, this->_flag_prefix_char_length);
+            arg_flag.erase(0, this->_secondary_flag_prefix_length);
     }
 
     /**
@@ -694,20 +729,55 @@ class argument_parser {
         return std::nullopt;
     }
 
+    /**
+     * @brief Print the given argument list to an output stream.
+     * @param os The output stream to print to.
+     * @param args The argument list to print.
+     */
+    void _print(std::ostream& os, const arg_ptr_list_t& args) const noexcept {
+        if (this->_verbose) {
+            for (const auto& arg : args)
+                os << '\n' << arg->desc(this->_verbose).get(this->_indent_width) << '\n';
+        }
+        else {
+            std::vector<detail::argument_descriptor> descriptors;
+            descriptors.reserve(args.size());
+
+            for (const auto& arg : args)
+                descriptors.emplace_back(arg->desc(this->_verbose));
+
+            std::size_t max_arg_name_length = 0ull;
+            for (const auto& desc : descriptors)
+                max_arg_name_length = std::max(max_arg_name_length, desc.name.length());
+
+            for (const auto& desc : descriptors)
+                os << '\n' << desc.get_basic(this->_indent_width, max_arg_name_length);
+
+            os << '\n';
+        }
+    }
+
     std::optional<std::string> _program_name;
     std::optional<std::string> _program_description;
+    bool _verbose = false;
 
     arg_ptr_list_t _positional_args;
     arg_ptr_list_t _optional_args;
 
-    static constexpr uint8_t _flag_prefix_char_length = 1u;
-    static constexpr uint8_t _flag_prefix_length = 2u;
+    static constexpr uint8_t _secondary_flag_prefix_length = 1u;
+    static constexpr uint8_t _primary_flag_prefxi_length = 2u;
     static constexpr char _flag_prefix_char = '-';
     static constexpr std::string _flag_prefix = "--";
+    static constexpr uint8_t _indent_width = 2;
 };
 
 namespace detail {
 
+/**
+ * @brief Adds a predefined/default positional argument to the parser.
+ * @param arg_discriminator The default argument discriminator.
+ * @param arg_parser The argument parser to which the argument will be added.
+ */
 inline void add_default_argument(
     const argument::default_positional arg_discriminator, argument_parser& arg_parser
 ) noexcept {
@@ -724,6 +794,11 @@ inline void add_default_argument(
     }
 }
 
+/**
+ * @brief Adds a predefined/default optional argument to the parser.
+ * @param arg_discriminator The default argument discriminator.
+ * @param arg_parser The argument parser to which the argument will be added.
+ */
 inline void add_default_argument(
     const argument::default_optional arg_discriminator, argument_parser& arg_parser
 ) noexcept {