refactor: improve documentation

Author: marcosbento

libs/core/src/ecflow/core/Base64.hpp

@@ -16,37 +16,37 @@
 
 namespace ecf {
 
-/**
- * @brief Decode a base64 encoded string.
- *
- * @param value the base64 encoded string
- * @return the decoded string
- *
- * @throws std::invalid_argument if the input string has size not multiple of 4
- * @throws std::invalid_argument if any character in the input string is invalid (not in A-Za-z0-9+/ or '=' for padding)
- * @throws std::invalid_argument if padding is invalid (more than 2 '=', or non-padding characters after first '=')
- */
+///
+/// @brief Decode a base64 encoded string.
+///
+/// @param value the base64 encoded string
+/// @return the decoded string
+///
+/// @throws std::invalid_argument if the input has size not multiple of 4
+/// @throws std::invalid_argument if any character in the input is invalid (not in A-Za-z0-9+/ or '=' for padding)
+/// @throws std::invalid_argument if padding is invalid (more than 2 '=', or non-padding characters after first '=')
+///
 std::string decode_base64(std::string_view value);
 
-/**
- * @brief Encode a string to base64.
- *
- * @param value the string to encode
- * @return the base64 encoded string
- */
+///
+/// @brief Encode a string to base64.
+///
+/// @param value the string to encode
+/// @return the base64 encoded string
+///
 std::string encode_base64(std::string_view value);
 
-/**
- * @brief Simple validation of base64 encoded string.
- *
- * Checks the following conditions:
- * - length has to be multiple of 4 (n.b. 0 if a valid lenght)
- * - valid characters are A-Za-z0-9+/
- * - '=' can be used for padding (0, 1, or 2 characters) at the end of string
- *
- * @param value the base64 encoded string
- * @return true if valid, false otherwise
- */
+///
+/// @brief Simple validation of base64 encoded string.
+///
+/// Checks the following conditions:
+/// - length has to be multiple of 4 (n.b. 0 if a valid lenght)
+/// - valid characters are A-Za-z0-9+/
+/// - '=' can be used for padding (0, 1, or 2 characters) at the end of string
+///
+/// @param value the base64 encoded string
+/// @return true if valid, false otherwise
+///
 bool validate_base64(std::string_view value);
 
 } // namespace ecf

libs/core/src/ecflow/core/CommandLine.hpp

@@ -15,50 +15,53 @@
 #include <string>
 #include <vector>
 
-/**
- * CommandLine is a thin wrapper/container for the contents of an ecFlow client command line.
- *
- * Note: This class is related to class ArgvCreator, which takes the vector of the command
- * line tokens and converts them into argc+argv.
- */
+///
+/// @brief CommandLine is a thin wrapper/container for the contents of an ecFlow client command line.
+///
+/// Note: This class is related to class ArgvCreator, which takes the vector of the command
+/// line tokens and converts them into argc+argv.
+///
 class CommandLine {
 public:
     using cl_t     = std::string;
     using tokens_t = std::vector<std::string>;
     using size_t   = tokens_t::size_type;
 
 public:
-    /**
-     * Create a Command Line instance based on argc + argv
-     *
-     * @param argc the number of tokens in the command line
-     * @param argv the tokens in the command line
-     */
+    ///
+    /// @brief Create a Command Line instance based on argc + argv
+    ///
+    /// @param argc the number of tokens in the command line
+    /// @param argv the tokens in the command line
+    ///
     CommandLine(int argc, char** argv);
     CommandLine(int argc, const char** argv);
 
-    /**
-     * Create a Command Line instance based on a sequence of characters,
-     * considering that it might include single/double quotes.
-     *
-     * @param cl the command line as a sequence of characters
-     */
+    ///
+    /// @brief Create a Command Line instance based on a sequence of characters,
+    ///        considering that it might include single/double quotes.
+    ///
+    /// @param cl the command line as a sequence of characters
+    /// @throws std::runtime_error if the command line contains an invalid escape sequence
+    ///         or unmatched quotation marks
+    ///
     explicit CommandLine(const cl_t& cl);
 
-    /**
-     * Create a Command Line instance based on a sequence of tokens.
-     *
-     * @param tokens the command line as a sequence of tokens
-     */
+    ///
+    /// @brief Create a Command Line instance based on a sequence of tokens.
+    ///
+    /// @param tokens the command line as a sequence of tokens
+    ///
     explicit CommandLine(tokens_t tokens);
 
-    /**
-     * Create a Command Line instance based on multiple tokens.
-     * Tokens can be either strings or collections of strings. In the latter case, the collection of strings are
-     * added to the command line element-by-element.
-     *
-     * @param tokens the command line as multiple tokens
-     */
+    ///
+    /// @brief Create a Command Line instance based on multiple tokens.
+    ///        Tokens can be either strings or collections of strings. In the latter case, the collection of strings are
+    ///        added to the command line element-by-element.
+    ///
+    /// @param tokens the command line as multiple tokens
+    /// @return a CommandLine instance composed of the provided tokens
+    ///
     template <typename... TOKENS>
     static CommandLine make_command_line(TOKENS... tokens) {
         auto push = Overload{
@@ -72,28 +75,34 @@ class CommandLine {
         return CommandLine(ts);
     }
 
-    /**
-     * Access the original content of the command line.
-     */
+    ///
+    /// @brief Access the original content of the command line.
+    ///
+    /// @return the command line as a single string, with tokens separated by spaces
+    ///
     [[nodiscard]] cl_t original() const;
 
-    /**
-     * Access the number of tokens composing the command line.
-     *
-     * @return the number of tokens
-     */
+    ///
+    /// @brief Access the number of tokens composing the command line.
+    ///
+    /// @return the number of tokens
+    ///
     [[nodiscard]] size_t size() const;
 
-    /**
-     * Access the sequence of tokens composing the command line.
-     *
-     * @return the command line tokens
-     */
+    ///
+    /// @brief Access the sequence of tokens composing the command line.
+    ///
+    /// @return the command line tokens
+    ///
     [[nodiscard]] const tokens_t& tokens() const;
 
-    /**
-     * Pretty print the command line
-     */
+    ///
+    /// @brief Pretty print the command line
+    ///
+    /// @param os the output stream to write to
+    /// @param cl the command line to print
+    /// @return the output stream @p os
+    ///
     friend std::ostream& operator<<(std::ostream& os, const CommandLine& cl);
 
 private:

libs/core/src/ecflow/core/Enumerate.hpp

@@ -24,39 +24,44 @@ namespace ecf {
 
 namespace detail {
 
-/**
- * EnumTraits defines the mapping between a set of enum values and their designation.
- *
- * EnumTraits must define:
- *  - the mapping `map`, provided as a std::array composed of a std::pair<E, const char *> for each enum value
- *  - the `size`, holding the number os entries in `map`
- *
- * @tparam E
- */
-
+///
+/// @brief EnumTraits defines the mapping between a set of enum values and their designation.
+///
+/// EnumTraits must define:
+///  - the mapping `map`, provided as a std::array composed of a std::pair<E, const char *> for each enum value
+///  - the `size`, holding the number of entries in `map`
+///
+/// @tparam E the enum type for which the traits are defined
+///
 template <typename E>
 struct EnumTraits
 {
 };
 
 } // namespace detail
 
+///
+/// @brief Enumerate provides bidirectional mapping between enum values and their string designations.
+///
+/// @tparam E      the enum type to map
+/// @tparam TRAITS the traits type providing the mapping; defaults to detail::EnumTraits<E>
+///
 template <typename E, typename TRAITS = detail::EnumTraits<E>>
 struct Enumerate
 {
 public:
     using enum_t   = E;
     using string_t = std::string_view;
 
-    /**
-     * Convert the given enum value to its designation
-     *
-     * This is an "unsafe" operation, as it assumes that the given enum value exists in the mapping.
-     * If the enum value does not exist, an assertion failure is raised.
-     *
-     * @param e the enum value
-     * @return the associated designation
-     */
+    ///
+    /// @brief Convert the given enum value to its designation.
+    ///
+    /// This is an "unsafe" operation, as it assumes that the given enum value exists in the mapping.
+    /// If the enum value does not exist, an assertion failure is raised.
+    ///
+    /// @param e the enum value
+    /// @return the associated designation
+    ///
     static constexpr string_t as_string(enum_t e) noexcept {
         auto found = std::find_if(
             std::begin(TRAITS::map), std::end(TRAITS::map), [&](const auto& item) { return item.first == e; });
@@ -66,12 +71,12 @@ struct Enumerate
         return found->second;
     }
 
-    /**
-     * Convert the given enum value to its designation
-     *
-     * @param e the enum value
-     * @return the associated designation, in case it exists; an empty optional, otherwise
-     */
+    ///
+    /// @brief Convert the given enum value to its designation.
+    ///
+    /// @param e the enum value
+    /// @return the associated designation, in case it exists; an empty optional, otherwise
+    ///
     static constexpr std::optional<string_t> to_string(enum_t e) noexcept {
         if (auto found = std::find_if(
                 std::begin(TRAITS::map), std::end(TRAITS::map), [&](const auto& item) { return item.first == e; });
@@ -82,12 +87,12 @@ struct Enumerate
         return std::nullopt;
     }
 
-    /**
-     * Convert the given designation to the related enum value
-     *
-     * @param s the designation
-     * @return the enum value, in case it exists; an empty optional, otherwise
-     */
+    ///
+    /// @brief Convert the given designation to the related enum value.
+    ///
+    /// @param s the designation
+    /// @return the enum value, in case it exists; an empty optional, otherwise
+    ///
     static constexpr std::optional<E> to_enum(string_t s) noexcept {
         if (auto found = std::find_if(
                 std::begin(TRAITS::map), std::end(TRAITS::map), [&](const auto& item) { return item.second == s; });
@@ -98,26 +103,28 @@ struct Enumerate
         return std::nullopt;
     }
 
-    /**
-     * Checks if the given designation is valid (i.e. has a related enum value)
-     *
-     * @param s the designation
-     * @return true, if valid; false, otherwise
-     */
+    ///
+    /// @brief Check if the given designation is valid (i.e. has a related enum value).
+    ///
+    /// @param s the designation
+    /// @return true, if valid; false, otherwise
+    ///
     static constexpr bool is_valid(string_t s) {
         auto found = std::find_if(
             std::begin(TRAITS::map), std::end(TRAITS::map), [&](const auto& item) { return item.second == s; });
         return found != std::end(TRAITS::map);
     }
 
-    /**
-     * The number of mapped enum values
-     */
+    ///
+    /// @brief The number of mapped enum values.
+    ///
     static const size_t size = TRAITS::size;
 
-    /**
-     * The vector of mapped enum values
-     */
+    ///
+    /// @brief Collect all mapped enum values.
+    ///
+    /// @return a vector containing all mapped enum values
+    ///
     static auto enums() {
         std::vector<E> result;
         result.reserve(TRAITS::size);
@@ -128,9 +135,11 @@ struct Enumerate
         return result;
     }
 
-    /**
-     * The vector of mapped designations
-     */
+    ///
+    /// @brief Collect all mapped designations.
+    ///
+    /// @return a vector containing all mapped designations
+    ///
     static auto designations() {
         std::vector<std::string> result;
         result.reserve(TRAITS::size);