From ee66c569058d40df321ac92bb1e1a85208c73bfb Mon Sep 17 00:00:00 2001
From: Martchus <martchus@gmx.net>
Date: Sat, 30 Sep 2017 18:42:34 +0200
Subject: [PATCH] Improve documentation

---
 application/argumentparser.cpp | 14 +++++++++++++-
 application/argumentparser.h   |  6 ++++++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/application/argumentparser.cpp b/application/argumentparser.cpp
index 582d41a..d0b50ba 100644
--- a/application/argumentparser.cpp
+++ b/application/argumentparser.cpp
@@ -36,10 +36,16 @@ enum ArgumentDenotationType : unsigned char {
 };
 
 /*!
- * \brief The ArgReader struct internally encapsulates the process of reading command line arguments.
+ * \class ArgumentReader
+ * \brief The ArgumentReader class internally encapsulates the process of reading command line arguments.
  * \remarks
  * - For meaning of parameter see documentation of corresponding member variables.
  * - Results are stored in specified \a args and assigned sub arguments.
+ * - This class is explicitely *not* part of the public API.
+ */
+
+/*!
+ * \brief Initializes the internal reader for the specified \a parser and arguments.
  */
 ArgumentReader::ArgumentReader(ArgumentParser &parser, const char *const *argv, const char *const *end, bool completionMode)
     : parser(parser)
@@ -260,6 +266,12 @@ void ArgumentReader::read(ArgumentVector &args)
     } // while(argv != end)
 }
 
+/*!
+ * \class Wrapper
+ * \brief The Wrapper class is internally used print text which might needs to be wrapped preserving the indentation.
+ * \remarks This class is explicitely *not* part of the public API.
+ */
+
 ostream &operator<<(ostream &os, const Wrapper &wrapper)
 {
     // determine max. number of columns
diff --git a/application/argumentparser.h b/application/argumentparser.h
index 557e68f..b438655 100644
--- a/application/argumentparser.h
+++ b/application/argumentparser.h
@@ -67,6 +67,12 @@ enum class UnknownArgumentBehavior {
 
 /*!
  * \brief The ValueCompletionBehavior enum specifies the items to be considered when generating completion for an argument value.
+ * \remarks
+ * - The enumeration items are meant to be combined using the |-operator.
+ * - ValueCompletionBehavior::InvokeCallback is meant to initialize pre-defined values only when required in the callback assigned
+ *   via Argument::setCallback(). Hence it makes sense to combine it with ValueCompletionBehavior::PreDefinedValues.
+ * - When ValueCompletionBehavior::InvokeCallback is present, the callback assigned via Argument::setCallback() might be called
+ *   even when not all constraints are fulfilled. So, for instance, there might not be all required values present.
  */
 enum class ValueCompletionBehavior : unsigned char {
     None = 0, /**< no auto-completion */