From f6c88b3801d924e315c731a47e6b0cd4afb46040 Mon Sep 17 00:00:00 2001
From: gereon <gereon.kremer@rwth-aachen.de>
Date: Thu, 13 Dec 2012 16:34:29 +0100
Subject: [PATCH] fixing some more documentation, adding dummy implementation

---
 src/utility/settings.cpp | 24 ++++++++++--------------
 src/utility/settings.h   | 19 +++++++++++++++----
 2 files changed, 25 insertions(+), 18 deletions(-)

diff --git a/src/utility/settings.cpp b/src/utility/settings.cpp
index d8ff685bf..c7135539f 100644
--- a/src/utility/settings.cpp
+++ b/src/utility/settings.cpp
@@ -45,14 +45,14 @@ Settings::Settings(const int argc, const char* argv[], const char* filename)
 	Settings::binaryName = std::string(argv[0]);
 	try
 	{
-		//! Initially fill description objects and call register callbacks
+		// Initially fill description objects
 		this->initDescriptions();
 
-		//! Take care of positional arguments
+		// Take care of positional arguments
 		Settings::positional.add("trafile", 1);
 		Settings::positional.add("labfile", 1);
 
-		//! Check module triggers, add corresponding options
+		// Check module triggers, add corresponding options
 		std::map< std::string, std::list< std::string > > options;
 		
 		for (auto it : Settings::modules)
@@ -69,10 +69,10 @@ Settings::Settings(const int argc, const char* argv[], const char* filename)
 			;
 		}
 		
-		//! Perform first parse run
+		// Perform first parse run
 		this->firstRun(argc, argv, filename);
 		
-		//! Check module triggers
+		// Check module triggers
 		for (auto it : Settings::modules)
 		{
 			std::pair< std::string, std::string > trigger = it.first;
@@ -87,16 +87,16 @@ Settings::Settings(const int argc, const char* argv[], const char* filename)
 			
 		}
 		
-		//! Stop if help is set
+		// Stop if help is set
 		if ((this->vm.count("help") > 0) || (this->vm.count("help-config") > 0))
 		{
 			return;
 		}
 		
-		//! Perform second run and call checker callbacks
+		// Perform second run
 		this->secondRun(argc, argv, filename);
 		
-		//! Finalize parsed options, check for specified requirements
+		// Finalize parsed options, check for specified requirements
 		bpo::notify(this->vm);
 		LOG4CPLUS_DEBUG(logger, "Finished loading config.");
 	}
@@ -154,13 +154,11 @@ void Settings::initDescriptions()
  *	Perform a sloppy parsing run: parse command line and config file (if
  *	given), but allow for unregistered options, do not check requirements
  *	from options_description objects, do not check positional arguments.
- *
- *	Call all intermediate callbacks afterwards.
  */
 void Settings::firstRun(const int argc, const char* argv[], const char* filename)
 {
 	LOG4CPLUS_DEBUG(logger, "Performing first run.");
-	//! parse command line
+	// parse command line
 	bpo::store(bpo::command_line_parser(argc, argv).options(*(Settings::desc)).allow_unregistered().run(), this->vm);
 
 	/*
@@ -180,13 +178,11 @@ void Settings::firstRun(const int argc, const char* argv[], const char* filename
  *	Perform the second parser run: parse command line and config file (if
  *	given) and check for unregistered options, requirements from
  *	options_description objects and positional arguments.
- *
- *	Call all checker callbacks afterwards.
  */
 void Settings::secondRun(const int argc, const char* argv[], const char* filename)
 {
 	LOG4CPLUS_DEBUG(logger, "Performing second run.");
-	//! Parse command line
+	// Parse command line
 	bpo::store(bpo::command_line_parser(argc, argv).options(*(Settings::desc)).positional(this->positional).run(), this->vm);
 	/*
 	 *	load config file if specified
diff --git a/src/utility/settings.h b/src/utility/settings.h
index 41907c741..901e58a8b 100644
--- a/src/utility/settings.h
+++ b/src/utility/settings.h
@@ -87,19 +87,30 @@ namespace settings {
 			 *
 			 *	Furthermore, it will generate the option specified by the
 			 *	trigger.
+			 *
+			 *	The functions could look like this:
+			 *	@code
+			 *	static std::string getModuleName() { return "Backend A"; }
+			 *	static std::pair<std::string, std::string> getOptionTrigger() {
+			 *		return std::pair<std::string, std::string>("backend", "a");
+			 *	}
+			 *	static void putOptions(boost::program_options::options_description* desc) {
+			 *		desc->add_options()("foo", "bar");
+			 *	}
+			 *	@endcode
 			 */
 			template <typename T>
 			static void registerModule()
 			{
-				//! get trigger
+				// get trigger
 				std::pair< std::string, std::string > trigger = T::getOptionTrigger();
-				//! build description name
+				// build description name
 				std::stringstream str;
 				str << T::getModuleName() << " (" << trigger.first << " = " << trigger.second << ")";
 				bpo::options_description* desc = new bpo::options_description(str.str());
-				//! but options
+				// but options
 				T::putOptions(desc);
-				//! store
+				// store
 				Settings::modules[ trigger ] = desc;
 			}