From 8f4ca38c69e2b03d84f78ef868a71afec02b570d Mon Sep 17 00:00:00 2001
From: Martchus <martchus@gmx.net>
Date: Sun, 26 Jun 2022 11:45:13 +0200
Subject: [PATCH] Update documentation of argument parser

---
 application/argumentparser.cpp |  8 ++++----
 application/argumentparser.h   | 21 ++++++++++++---------
 2 files changed, 16 insertions(+), 13 deletions(-)

diff --git a/application/argumentparser.cpp b/application/argumentparser.cpp
index fde521c..b5d58dc 100644
--- a/application/argumentparser.cpp
+++ b/application/argumentparser.cpp
@@ -469,7 +469,7 @@ inline bool notEmpty(const char *str)
  * Instances of the Argument class are used as definition when parsing command line
  * arguments. Arguments can be assigned to an ArgumentParser using
  * ArgumentParser::setMainArguments() and to another Argument instance using
- * Argument::setSecondaryArguments().
+ * Argument::setSubArguments().
  */
 
 /*!
@@ -629,7 +629,7 @@ Argument *firstPresentUncombinableArg(const ArgumentVector &args, const Argument
  *
  * \sa secondaryArguments()
  * \sa addSecondaryArgument()
- * \sa hasSecondaryArguments()
+ * \sa hasSubArguments()
  */
 void Argument::setSubArguments(const ArgumentInitializerList &secondaryArguments)
 {
@@ -652,8 +652,8 @@ void Argument::setSubArguments(const ArgumentInitializerList &secondaryArguments
  * \brief Adds \a arg as a secondary argument for this argument.
  *
  * \sa secondaryArguments()
- * \sa setSecondaryArguments()
- * \sa hasSecondaryArguments()
+ * \sa setSubArguments()
+ * \sa hasSubArguments()
  */
 void Argument::addSubArgument(Argument *arg)
 {
diff --git a/application/argumentparser.h b/application/argumentparser.h
index c012ef9..af677fe 100644
--- a/application/argumentparser.h
+++ b/application/argumentparser.h
@@ -267,13 +267,16 @@ class CPP_UTILITIES_EXPORT Argument {
 public:
     typedef std::function<void(const ArgumentOccurrence &)> CallbackFunction;
 
+    /// \brief The Flags enum specifies options for treating the argument in a special way.
     enum class Flags : std::uint64_t {
-        None = 0x0,
-        Combinable = 0x1,
-        Implicit = 0x2,
-        Operation = 0x4,
-        Deprecated = 0x8,
-        Greedy = 0x10,
+        None = 0x0, /**< No flags are present. The default for Argument(). */
+        Combinable
+        = 0x1, /**< It is no error if this argument occurs besides other arguments on the same level. The default for ConfigValueArgument. */
+        Implicit = 0x2, /**< The argument is assumed to be present if its values are present. Only one argument can be implicit at the same level. */
+        Operation = 0x4, /**< The argument is an operation, so no `--` prefix is required when specifying it. The default for OperationArgument(). */
+        Deprecated = 0x8, /**< The argument is considered deprecated and therefore excluded from the help. */
+        Greedy
+        = 0x10, /**< The argument is "greedy" so when Argument::varValueCount is used all subsequent arguments will be considered values of that argument. This is useful to pass remaining arguments down to another argument parser as-is. */
     };
 
     Argument(const char *name, char abbreviation = '\0', const char *description = nullptr, const char *example = nullptr);
@@ -952,8 +955,8 @@ inline void Argument::setCallback(Argument::CallbackFunction callback)
 /*!
  * \brief Returns the secondary arguments for this argument.
  *
- * \sa setSecondaryArguments()
- * \sa hasSecondaryArguments()
+ * \sa setSubArguments()
+ * \sa hasSubArguments()
  */
 inline const ArgumentVector &Argument::subArguments() const
 {
@@ -964,7 +967,7 @@ inline const ArgumentVector &Argument::subArguments() const
  * \brief Returns an indication whether the argument has secondary arguments.
  *
  * \sa secondaryArguments()
- * \sa setSecondaryArguments()
+ * \sa setSubArguments()
  */
 inline bool Argument::hasSubArguments() const
 {