docu: improve utilities and general stuff

Author: torbjoernk

include/pfasst/config.hpp

@@ -1,3 +1,7 @@
+/**
+ * @file pfasst/config.hpp
+ * @since v0.3.0
+ */
 #ifndef _PFASST__CONFIG_HPP_
 #define _PFASST__CONFIG_HPP_
 
@@ -13,15 +17,25 @@ namespace po = boost::program_options;
 
 namespace pfasst
 {
+  /**
+   * @since v0.3.0
+   */
   namespace config
   {
     /**
+     * runtime config options provider.
+     *
+     * This singleton provides easy access to command line parameters at runtime.
+     *
      * @note This uses the Singleton Pattern, and hence pfasst::options::get_instance() is
      *    thread-safe with C++11.
+     * @since v0.3.0
+     * @ingroup Internals
      */
     class options
     {
       public:
+        /// line width of help and usage information
         static const size_t LINE_WIDTH = 100;
 
       private:
@@ -31,34 +45,140 @@ namespace pfasst
         vector<string> unrecognized_args;
         bool initialized = false;
 
+        //! @{
         options();
         options(const options&) = delete;
         void operator=(const options&) = delete;
+        //! @}
 
       public:
+        //! @{
+        /**
+         * accessor to the singleton instance.
+         *
+         * @returns singleton config::options instance
+         */
         static options& get_instance();
         po::variables_map& get_variables_map();
         po::options_description& get_all_options();
         vector<string>& get_unrecognized_args();
+        //! @}
+
+        //! @{
+        /**
+         * adds a new boolean flag.
+         *
+         * @param[in] group string identifying the parameter group
+         * @param[in] option Name of the command line parameter.
+         *   It is possible to specify a long and optional short option name by comma-separation.
+         *   Short option names are identified by being only a single character.
+         *   They are automatically parsed as '`-[SHORT]`' by `boost::program_options` in contrast 
+         *   to '`--[LONG]`'.
+         * @param[in] help help text to be displayed in the help and usage information
+         */
         static void add_option(const string& group, const string& option, const string& help);
 
+        /**
+         * adds a new parameter with an expected value of type @p T.
+         *
+         * @tparam T type of the specified parameter
+         * @param[in] group string identifying the parameter group
+         * @param[in] option Name of the command line parameter.
+         *   It is possible to specify a long and optional short option name by comma-separation.
+         *   Short option names are identified by being only a single character.
+         *   They are automatically parsed as '`-[SHORT]`' by `boost::program_options` in contrast 
+         *   to '`--[LONG]`'.
+         * @param[in] help help text to be displayed in the help and usage information
+         *
+         * @overload
+         */
         template<typename T>
         static void add_option(const string& group, const string& option, const string& help);
+        //! @}
 
+        /**
+         * initialize program options.
+         *
+         * This initializes `boost::program_options` with all previously added options and groups.
+         */
         void init();
     };
 
+    /**
+     * get value of specific type @p T
+     *
+     * @tparam T type of the retreived value
+     * @param[in] name Name of the (long) option as defined with @p option in options::add_option()
+     * @returns Value of type @p T of desired option.
+     * @throws boost::bad_any_cast if option is not given.
+     *
+     * @see
+     *   [boost::any::bad_any_cast]
+     *   (http://www.boost.org/doc/libs/1_57_0/doc/html/boost/bad_any_cast.html)
+     */
     template<typename T>
-    static T get_value(const string& name, const T& default_val);
+    inline T get_value(const string& name)
+    {
+      return options::get_instance().get_variables_map()[name].as<T>();
+    }
 
+    /**
+     * get value of specific type @p T with default value.
+     *
+     * @tparam T type of the retreived value
+     *
+     * @overload
+     */
     template<typename T>
-    static T get_value(const string& name);
+    inline T get_value(const string& name, const T& default_val)
+    {
+      return options::get_instance().get_variables_map().count(name)
+              ? options::get_instance().get_variables_map()[name].as<T>() : default_val;
+    }
 
     /**
-     * @returns empty string if params are set and `if_no_params` is `true`
+     * compile basic help and usage information.
+     *
+     * Depending on @p if_no_params and presence of given command line parameters the help and
+     * usage information is compiled.
+     * In case @p if_no_params is `true` and there are no parameters given on the command line or
+     * @p if_no_params is `false` no matter whether parameters are given, the help message is
+     * generated.
+     *
+     * @param[in] if_no_params flag governing compilation of help and usage information
+     * @returns string containing basic help and usage information; string may be empty
      */
-    static string print_help(bool if_no_params = false);
+    static string print_help(bool if_no_params = false)
+    {
+      bool no_params_given = options::get_instance().get_variables_map().empty();
+
+      if (!if_no_params || (if_no_params && no_params_given)) {
+        stringstream s;
+        s << options::get_instance().get_all_options() << endl;
+        s << "Logging options:" << endl
+          << "  -v [ --verbose ]       activates maximum verbosity" << endl
+          << "  --v=arg                activates verbosity upto verbose level `arg`" << endl
+          << "                         (valid range: 0-9)" << endl
+          << "  -vmodule=arg           actives verbose logging for specific module" << endl
+          << "                         (see [1] for details)" << endl << endl
+          << "[1]: https://github.com/easylogging/easyloggingpp#vmodule" << endl;
+        return s.str();
+      } else {
+        return string();
+      }
+    }
 
+    /**
+     * read and parse command line parameters.
+     *
+     * @param[in] argc Number of command line arguments as provided by `%main(int, char**)`.
+     * @param[in] argv List of command line arguments as provided by `%main(int, char**)`.
+     * @param[in] exit_on_help Whether to exit the program after displaying help and usage
+     *   information.
+     *
+     * @note Will call `std::exit` in case the `help` parameter has been provided and
+     *   @p exit_on_help is `true`.
+     */
     static inline void read_commandline(int argc, char* argv[], bool exit_on_help = true)
     {
       po::parsed_options parsed = po::command_line_parser(argc, argv)
@@ -76,7 +196,15 @@ namespace pfasst
     }
 
     /**
+     * read config parameters from file.
+     *
+     * @param[in] file_name name of the INI-like file containing config parameters;
+     *   path/name may be relative
      * @throws invalid_argument if the given file could not be opened
+     *
+     * @see
+     *   [Boost Program Options Documentation on supported INI-like file format]
+     *   (http://www.boost.org/doc/libs/1_57_0/doc/html/program_options/overview.html#idp343292240)
      */
     static inline void read_config_file(const string& file_name)
     {
@@ -90,6 +218,20 @@ namespace pfasst
       }
     }
 
+    /**
+     * initialize options detection and parsing.
+     *
+     * Prepopulates following groups and parameters:
+     *
+     * Group      | Parameter     | Type
+     * -----------|---------------|---------
+     * Global     | `h`, `help`   | `bool`
+     * Duration   | `dt`          | `double`
+     * Duration   | `tend`        | `double`
+     * Duration   | `num_iters`   | `size_t`
+     * Tolerances | `abs_res_tol` | `double`
+     * Tolerances | `rel_res_tol` | `double`
+     */
     static inline void init()
     {
       options::add_option("Global", "help,h", "display this help message");

include/pfasst/globals.hpp

@@ -1,30 +1,36 @@
+/**
+ * @file pfasst/globals.hpp
+ * @since v0.2.0
+ */
 #ifndef _GLOBALS__HPP_
 #define _GLOBALS__HPP_
 
 /**
- * denoting unused function parameters for omitting compiler warnings
+ * denoting unused function parameters for omitting compiler warnings.
  *
  * To denote an unused function parameter just use this makro on it in the function body:
- *
- * ~~~{.cpp}
- * void func(auto p) {
- *   UNUSED(p);
+ * @code{.cpp}
+ * void foo(T bar) {
+ *   UNUSED(bar);
+ *   // some logic not using parameter `bar`
  * }
- * ~~~
- *
+ * @endcode
  * which renders to
- *
- * ~~~{.cpp}
- * void func(auto p) {
- *   (void)(p);
+ * @code{.cpp}
+ * void foo(T bar) {
+ *   (void)(bar);
+ *   // some logic not using parameter `bar`
  * }
- * ~~~
- *
+ * @endcode
  * which is the standard and compiler independet way of omitting warnings on unused parameters while
  * still being able to fully document the parameter with Doxygen.
  *
  * @param[in] expr parameter to be denoted as unused
+ * @since v0.2.0
+ * @ingroup Utilities
  */
-#define UNUSED(expr) (void)(expr)
+#define UNUSED(expr) \
+  (void)(expr)
+
 
 #endif  // _GLOBALS__HPP_