From e7c2ad96ad56116b2bfca1000f425287b1a02da2 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Rafa=C5=82=20D=C5=82ugo=C5=82=C4=99cki?=
 <rafal@dlugolecki.net.pl>
Date: Wed, 6 May 2015 18:33:43 +0200
Subject: [PATCH] Documentation improvements.

---
 include/argument.h  |  8 ++++----
 include/option.h    |  8 ++++----
 include/parameter.h | 13 ++++++++++++-
 include/required.h  | 19 ++++++++++++++-----
 4 files changed, 34 insertions(+), 14 deletions(-)

diff --git a/include/argument.h b/include/argument.h
index dfaea65..5690e5d 100644
--- a/include/argument.h
+++ b/include/argument.h
@@ -14,9 +14,9 @@ namespace command {
      * Arguments are non-named parameters of program.
      *
      * Example:
-     *  ./myprog ARGUMENT
-     *  ./myprog /path/to/file
-     *  ./myprog "some argument"
+     *  - ./myprog ARGUMENT
+     *  - ./myprog /path/to/file
+     *  - ./myprog "some argument"
      */
     template<typename ParameterType>
     class Argument : public Parameter, public Callable<ParameterType> {
@@ -41,7 +41,7 @@ namespace command {
         virtual ~Argument() { }
 
         /**
-         *
+         * \inheritdoc
          */
         virtual void handle() {
             this->call(value);
diff --git a/include/option.h b/include/option.h
index 963d662..516fce0 100644
--- a/include/option.h
+++ b/include/option.h
@@ -13,9 +13,9 @@ namespace command {
      * Options are named parameters of program.
      *
      * Example:
-     *  ./myprog OptionName=OptionValue
-     *  ./myprog -f=/some/file
-     *  ./myprog --level=15
+     *  - ./myprog OptionName=OptionValue
+     *  - ./myprog -f=/some/file
+     *  - ./myprog --level=15
      */
     template<typename ParameterType>
     class Option
@@ -51,7 +51,7 @@ namespace command {
         virtual ~Option() { }
 
         /**
-         *
+         * \inheritdoc
          */
         virtual void handle() {
             this->call(value);
diff --git a/include/parameter.h b/include/parameter.h
index a54a967..443111d 100644
--- a/include/parameter.h
+++ b/include/parameter.h
@@ -32,23 +32,34 @@ namespace command {
         virtual ~Parameter() { }
 
         /**
-         * Method used for handling method calls linked with Argument or Option
+         * Method used for handling method calls linked with this Parameter
          */
         virtual void handle() = 0;
 
         /**
          * Method used for checking if the given user value understandable for
          * parameter.
+         *
+         * @return true if passed value is understandable by current Parameter.
+         *      False otherwise.
          */
         virtual bool understand(const std::string & ) = 0;
 
         /**
          * Indicates if current Parameter is required
+         *
+         * @return false, as all Parameters are non-required by default. If you
+         *      want to make Parameter as required, wrap it using Required class
          */
         virtual bool isRequired() {
             return false;
         };
 
+        /**
+         * Indicates if current Parameter has been already used
+         *
+         * @return true if current Parameter has been already used. False otherwise.
+         */
         virtual bool isUsed() {
             return used;
         }
diff --git a/include/required.h b/include/required.h
index bdb6299..a4e0622 100644
--- a/include/required.h
+++ b/include/required.h
@@ -32,17 +32,20 @@ namespace command {
         }
 
         /**
-         * Method used for handling method calls to linked Parameter
+         * Wrapper method around passed Parameter::handle().
+         *
+         * \inheritdoc
          */
         virtual void handle() {
             parameter->handle();
         }
 
         /**
-         * Method used for checking if the given user value is understandable by
-         * parameter.
+         * Wrapper method around passed Parameter::understand()
+         *
+         * @param argv command line value against which test will be made
          *
-         * @param value value from argv to check against
+         * \inheritdoc
          */
         virtual bool understand(const std::string & value) {
             return parameter->understand(value);
@@ -50,13 +53,19 @@ namespace command {
 
         /**
          * Indicates if current Parameter is required
+         *
+         * @return true, as all Parameters wrapped in Required class are set as
+         *      required. In order to make them non-required do not use
+         *      Required class
          */
         virtual bool isRequired() {
             return true;
         };
 
         /**
-         * Indicates if current Parameter is already used
+         * Wrapper method around passed Parameter::isUsed().
+         *
+         * \inheritdoc
          */
         virtual bool isUsed() {
             return parameter->isUsed();
-- 
2.30.2