Updated documentation.

lib/base/asynctask.h

@@ -35,6 +35,9 @@ public:
 	typedef shared_ptr<AsyncTask<TClass, TResult> > Ptr;
 	typedef weak_ptr<AsyncTask<TClass, TResult> > WeakPtr;
 
+	/**
+	 * A completion callback for an AsyncTask.
+	 */
 	typedef function<void (const shared_ptr<TClass>&)> CompletionCallback;
 
 	/**

lib/base/component.h

@@ -41,7 +41,8 @@ protected:
 	DynamicObject::Ptr GetConfig(void) const;
 
 private:
-	DynamicObject *m_Config;
+	DynamicObject *m_Config; /**< The configuration object for this
+				      component. */
 
 	friend class Component;
 };
@@ -64,7 +65,8 @@ public:
 	static void AddSearchDir(const String& componentDirectory);
 
 private:
-	IComponent::Ptr m_Impl;
+	IComponent::Ptr m_Impl; /**< The implementation object for this
+				     component. */
 };
 
 typedef IComponent *(*CreateComponentFunction)(void);

lib/base/dictionary.cpp

@@ -23,15 +23,31 @@
 using namespace icinga;
 
 /**
- * Compares the keys of dictionary keys using the less operator.
+ * Compares dictionary keys using the less operator.
  */
 struct DictionaryKeyLessComparer
 {
+	/**
+	 * Compares two keys.
+	 *
+	 * @param a The first key.
+	 * @param b The second key.
+	 * @returns true if the first key is less than the second key, false
+	 *		 otherwise
+	 */
 	bool operator()(const pair<String, Value>& a, const char *b)
 	{
 		return a.first < b;
 	}
 
+	/**
+	 * Compares two keys.
+	 *
+	 * @param a The first key.
+	 * @param b The second key.
+	 * @returns true if the first key is less than the second key, false
+	 *		 otherwise
+	 */
 	bool operator()(const char *a, const pair<String, Value>& b)
 	{
 		return a < b.first;

lib/base/dictionary.h

@@ -34,6 +34,9 @@ public:
 	typedef shared_ptr<Dictionary> Ptr;
 	typedef weak_ptr<Dictionary> WeakPtr;
 
+	/**
+	 * An iterator that can be used to iterate over dictionary elements.
+	 */
 	typedef map<String, Value>::iterator Iterator;
 
 	Value Get(const char *key) const;
@@ -56,7 +59,7 @@ public:
 	cJSON *ToJson(void) const;
 
 private:
-	map<String, Value> m_Data;
+	map<String, Value> m_Data; /**< The data for the dictionary. */
 };
 
 inline Dictionary::Iterator range_begin(Dictionary::Ptr x)

lib/base/dynamicobject.h

@@ -25,6 +25,8 @@ namespace icinga
 
 /**
  * The type of an attribute for a DynamicObject.
+ *
+ * @ingroup base
  */
 enum DynamicAttributeType
 {
@@ -48,6 +50,8 @@ enum DynamicAttributeType
 
 /**
  * An attribute for a DynamicObject.
+ *
+ * @ingroup base
  */
 struct DynamicAttribute
 {
@@ -166,6 +170,11 @@ public:
 	}
 };
 
+/**
+ * Factory function for DynamicObject-based classes.
+ *
+ * @ingroup base
+ */
 template<typename T>
 shared_ptr<T> DynamicObjectFactory(const Dictionary::Ptr& serializedUpdate)
 {

lib/base/exception.h

@@ -86,6 +86,8 @@ DEFINE_EXCEPTION_CLASS(NotImplementedException);
 #ifdef _WIN32
 /**
  * A Win32 error encapsulated in an exception.
+ *
+ * @ingroup base
  */
 class Win32Exception : public Exception
 {
@@ -112,6 +114,8 @@ public:
 
 /**
  * A Posix error encapsulated in an exception.
+ *
+ * @ingroup base
  */
 class PosixException : public Exception
 {
@@ -137,6 +141,8 @@ public:
 
 /**
  * An OpenSSL error encapsulated in an exception.
+ *
+ * @ingroup base
  */
 class OpenSSLException : public Exception
 {

lib/base/netstring.h

@@ -24,9 +24,9 @@ namespace icinga
 {
 
 /**
- * Helper functions for reading/writing messages in the netString format.
+ * Helper functions for reading/writing messages in the netstring format.
  *
- * @see http://cr.yp.to/proto/netStrings.txt
+ * @see http://cr.yp.to/proto/netstrings.txt
  *
  * @ingroup base
  */

lib/base/object.h

@@ -42,14 +42,28 @@ public:
 
 	/**
 	 * Holds a shared pointer and provides support for implicit upcasts.
+	 *
+	 * @ingroup base
 	 */
 	class SharedPtrHolder
 	{
 	public:
+		/**
+		 * Constructor for the SharedPtrHolder class.
+		 *
+		 * @param object The shared pointer that should be used to
+		 *		 construct this shared pointer holder.
+		 */
 		explicit SharedPtrHolder(const Object::Ptr& object)
 			: m_Object(object)
 		{ }
 
+		/**
+		 * Retrieves a shared pointer for the object that is associated
+		 * this holder instance.
+		 *
+		 * @returns A shared pointer.
+		 */
 		template<typename T>
 		operator shared_ptr<T>(void) const
 		{
@@ -63,6 +77,12 @@ public:
 			return other;
 		}
 
+		/**
+		 * Retrieves a weak pointer for the object that is associated
+		 * with this holder instance.
+		 *
+		 * @returns A weak pointer.
+		 */
 		template<typename T>
 		operator weak_ptr<T>(void) const
 		{
@@ -70,7 +90,8 @@ public:
 		}
 
 	private:
-		Object::Ptr m_Object;
+		Object::Ptr m_Object; /**< The object that belongs to this
+					   holder instance */
 	};
 
 	SharedPtrHolder GetSelf(void);
@@ -88,23 +109,33 @@ private:
 	Object(const Object& other);
 	Object& operator=(const Object& rhs);
 
-	static boost::mutex m_Mutex;
+	static boost::mutex m_Mutex; /**< Mutex which protects static members
-	static vector<Object::Ptr> m_HeldObjects;
+					  of the Object class. */
+	static vector<Object::Ptr> m_HeldObjects; /**< Currently held
+						       objects. */
 #ifdef _DEBUG
-	static set<Object *> m_AliveObjects;
+	static set<Object *> m_AliveObjects; /**< Currently alive objects -
+						  for debugging purposes. */
 #endif /* _DEBUG */
 };
 
 /**
  * Compares a weak pointer with a raw pointer.
+ *
+ * @ingroup base
  */
 template<class T>
 struct WeakPtrEqual
 {
 private:
-	const void *m_Ref;
+	const void *m_Ref; /**< The object. */
 
 public:
+	/**
+	 * Constructor for the WeakPtrEqual class.
+	 *
+	 * @param ref The object that should be compared with the weak pointer.
+	 */
 	WeakPtrEqual(const void *ref) : m_Ref(ref) { }
 
 	/**

lib/config/configcompiler.cpp

@@ -23,38 +23,78 @@ using std::ifstream;
 
 using namespace icinga;
 
-ConfigCompiler::ConfigCompiler(const String& path, istream *input, HandleIncludeFunc includeHandler)
+/**
+ * Constructor for the ConfigCompiler class.
+ *
+ * @param path The path of the configuration file (or another name that
+ *	       identifies the source of the configuration text).
+ * @param input Input stream for the configuration file.
+ * @param includeHandler Handler function for #include directives.
+ */
+ConfigCompiler::ConfigCompiler(const String& path, istream *input,
+    HandleIncludeFunc includeHandler)
 	: m_Path(path), m_Input(input), m_HandleInclude(includeHandler)
 {
 	InitializeScanner();
 }
 
+/**
+ * Destructor for the ConfigCompiler class.
+ */
 ConfigCompiler::~ConfigCompiler(void)
 {
 	DestroyScanner();
 }
 
+/**
+ * Reads data from the input stream. Used internally by the lexer.
+ *
+ * @param buffer Where to store data.
+ * @param max_size The maximum number of bytes to read from the stream.
+ * @returns The actual number of bytes read.
+ */
 size_t ConfigCompiler::ReadInput(char *buffer, size_t max_size)
 {
 	m_Input->read(buffer, max_size);
 	return static_cast<size_t>(m_Input->gcount());
 }
 
+/**
+ * Retrieves the scanner object.
+ *
+ * @returns The scanner object.
+ */
 void *ConfigCompiler::GetScanner(void) const
 {
 	return m_Scanner;
 }
 
+/**
+ * Retrieves the result from the compiler.
+ *
+ * @returns A list of configuration items.
+ */
 vector<ConfigItem::Ptr> ConfigCompiler::GetResult(void) const
 {
 	return m_Result;
 }
 
+/**
+ * Retrieves the path for the input file.
+ *
+ * @returns The path.
+ */
 String ConfigCompiler::GetPath(void) const
 {
 	return m_Path;
 }
 
+/**
+ * Handles an include directive by calling the include handler callback
+ * function.
+ *
+ * @param include The path from the include directive.
+ */
 void ConfigCompiler::HandleInclude(const String& include)
 {
 	String path = Utility::DirName(GetPath()) + "/" + include;
@@ -62,13 +102,27 @@ void ConfigCompiler::HandleInclude(const String& include)
 	std::copy(items.begin(), items.end(), back_inserter(m_Result));
 }
 
-vector<ConfigItem::Ptr> ConfigCompiler::CompileStream(const String& path, istream *stream)
+/**
+ * Compiles a stream.
+ *
+ * @param path A name identifying the stream.
+ * @param stream The input stream.
+ * @returns Configuration items.
+ */
+vector<ConfigItem::Ptr> ConfigCompiler::CompileStream(const String& path,
+    istream *stream)
 {
 	ConfigCompiler ctx(path, stream);
 	ctx.Compile();
 	return ctx.GetResult();
 }
 
+/**
+ * Compiles a file.
+ *
+ * @param path The path.
+ * @returns Configuration items.
+ */
 vector<ConfigItem::Ptr> ConfigCompiler::CompileFile(const String& path)
 {
 	ifstream stream;
@@ -82,18 +136,39 @@ vector<ConfigItem::Ptr> ConfigCompiler::CompileFile(const String& path)
 	return CompileStream(path, &stream);
 }
 
-vector<ConfigItem::Ptr> ConfigCompiler::CompileText(const String& path, const String& text)
+/**
+ * Compiles a snippet of text.
+ *
+ * @param path A name identifying the text.
+ * @param text The text.
+ * @returns Configuration items.
+ */
+vector<ConfigItem::Ptr> ConfigCompiler::CompileText(const String& path,
+    const String& text)
 {
 	stringstream stream(text);
 	return CompileStream(path, &stream);
 }
 
+/**
+ * Default include handler. Includes the file and returns a list of
+ * configuration items.
+ *
+ * @param include The path from the include directive.
+ * @returns A list of configuration objects.
+ */
 vector<ConfigItem::Ptr> ConfigCompiler::HandleFileInclude(const String& include)
 {
 	/* TODO: implement wildcard includes */
 	return CompileFile(include);
 }
 
+/**
+ * Adds an object to the result.
+ *
+ * @param object The configuration item.
+ */
+ * 
 void ConfigCompiler::AddObject(const ConfigItem::Ptr& object)
 {
 	m_Result.push_back(object);

lib/config/configcompiler.h

@@ -25,7 +25,7 @@ namespace icinga
 
 /**
  * The configuration compiler can be used to compile a configuration file
- * into a number of configuration objects.
+ * into a number of configuration items.
  *
  * @ingroup config
  */
@@ -40,9 +40,11 @@ public:
 
 	void Compile(void);
 
-	static vector<ConfigItem::Ptr> CompileStream(const String& path, istream *stream);
+	static vector<ConfigItem::Ptr> CompileStream(const String& path,
+	    istream *stream);
 	static vector<ConfigItem::Ptr> CompileFile(const String& path);
-	static vector<ConfigItem::Ptr> CompileText(const String& path, const String& text);
+	static vector<ConfigItem::Ptr> CompileText(const String& path,
+	    const String& text);
 
 	static vector<ConfigItem::Ptr> HandleFileInclude(const String& include);
 

lib/config/configitem.cpp

@@ -25,6 +25,15 @@ ConfigItem::ItemMap ConfigItem::m_Items;
 boost::signal<void (const ConfigItem::Ptr&)> ConfigItem::OnCommitted;
 boost::signal<void (const ConfigItem::Ptr&)> ConfigItem::OnRemoved;
 
+/**
+ * Constructor for the ConfigItem class.
+ *
+ * @param type The object type.
+ * @param name The name of the item.
+ * @param exprl Expression list for the item.
+ * @param parents Parent objects for the item.
+ * @param debuginfo Debug information.
+ */
 ConfigItem::ConfigItem(const String& type, const String& name,
     const ExpressionList::Ptr& exprl, const vector<String>& parents,
     const DebugInfo& debuginfo)
@@ -33,31 +42,63 @@ ConfigItem::ConfigItem(const String& type, const String& name,
 {
 }
 
+/**
+ * Retrieves the type of the configuration item.
+ *
+ * @returns The type.
+ */
 String ConfigItem::GetType(void) const
 {
 	return m_Type;
 }
 
+/**
+ * Retrieves the name of the configuration item.
+ *
+ * @returns The name.
+ */
 String ConfigItem::GetName(void) const
 {
 	return m_Name;
 }
 
+/**
+ * Retrieves the debug information for the configuration item.
+ *
+ * @returns The debug information.
+ */
 DebugInfo ConfigItem::GetDebugInfo(void) const
 {
 	return m_DebugInfo;
 }
 
+/**
+ * Retrieves the expression list for the configuration item.
+ *
+ * @returns The expression list.
+ */
 ExpressionList::Ptr ConfigItem::GetExpressionList(void) const
 {
 	return m_ExpressionList;
 }
 
+/**
+ * Retrieves the list of parents for the configuration item.
+ *
+ * @returns The list of parents.
+ */
 vector<String> ConfigItem::GetParents(void) const
 {
 	return m_Parents;
 }
 
+/**
+ * Calculates the object's properties based on parent objects and the object's
+ * expression list.
+ *
+ * @param dictionary The dictionary that should be used to store the
+ *		     properties.
+ */
 void ConfigItem::CalculateProperties(const Dictionary::Ptr& dictionary) const
 {
 	BOOST_FOREACH(const String& name, m_Parents) {
@@ -65,7 +106,8 @@ void ConfigItem::CalculateProperties(const Dictionary::Ptr& dictionary) const
 
 		if (!parent) {
 			stringstream message;
-			message << "Parent object '" << name << "' does not exist (" << m_DebugInfo << ")";
+			message << "Parent object '" << name << "' does not"
+			    " exist (" << m_DebugInfo << ")";
 			throw_exception(domain_error(message.str()));
 		}
 
@@ -75,6 +117,12 @@ void ConfigItem::CalculateProperties(const Dictionary::Ptr& dictionary) const
 	m_ExpressionList->Execute(dictionary);
 }
 
+/**
+ * Commits the configuration item by creating or updating a DynamicObject
+ * object.
+ *
+ * @returns The DynamicObject that was created/updated.
+ */
 DynamicObject::Ptr ConfigItem::Commit(void)
 {
 	DynamicObject::Ptr dobj = m_DynamicObject.lock();
@@ -125,6 +173,9 @@ DynamicObject::Ptr ConfigItem::Commit(void)
 	return dobj;
 }
 
+/**
+ * Unregisters the configuration item.
+ */
 void ConfigItem::Unregister(void)
 {
 	DynamicObject::Ptr dobj = m_DynamicObject.lock();
@@ -141,11 +192,23 @@ void ConfigItem::Unregister(void)
 	OnRemoved(GetSelf());
 }
 
+/**
+ * Retrieves the DynamicObject that belongs to the configuration item.
+ *
+ * @returns The DynamicObject.
+ */
 DynamicObject::Ptr ConfigItem::GetDynamicObject(void) const
 {
 	return m_DynamicObject.lock();
 }
 
+/**
+ * Retrieves a configuration item by type and name.
+ *
+ * @param type The type of the ConfigItem that is to be looked up.
+ * @param name The name of the ConfigItem that is to be looked up.
+ * @returns The configuration item.
+ */
 ConfigItem::Ptr ConfigItem::GetObject(const String& type, const String& name)
 {
 	ConfigItem::ItemMap::iterator it;

lib/config/configitem.h

@@ -24,8 +24,8 @@ namespace icinga
 {
 
 /**
- * A configuration item. Can be used to create a configuration object at
+ * A configuration item. Non-abstract configuration items can be used to
- * runtime.
+ * create configuration objects at runtime.
  *
  * @ingroup config
  */
@@ -52,7 +52,8 @@ public:
 
 	DebugInfo GetDebugInfo(void) const;
 
-	static ConfigItem::Ptr GetObject(const String& type, const String& name);
+	static ConfigItem::Ptr GetObject(const String& type,
+	    const String& name);
 
 	static boost::signal<void (const ConfigItem::Ptr&)> OnCommitted;
 	static boost::signal<void (const ConfigItem::Ptr&)> OnRemoved;
@@ -60,17 +61,20 @@ public:
 private:
 	void CalculateProperties(const Dictionary::Ptr& dictionary) const;
 
-	String m_Type;
+	String m_Type; /**< The object type. */
-	String m_Name;
+	String m_Name; /**< The name. */
 
 	ExpressionList::Ptr m_ExpressionList;
-	vector<String> m_Parents;
+	vector<String> m_Parents; /**< The names of parent configuration
-	DebugInfo m_DebugInfo;
+				       items. */
+	DebugInfo m_DebugInfo; /**< Debug information. */
 
-	DynamicObject::WeakPtr m_DynamicObject;
+	DynamicObject::WeakPtr m_DynamicObject; /**< The instantiated version
+						     of this configuration
+						     item */
 
 	typedef map<pair<String, String>, ConfigItem::Ptr> ItemMap;
-	static ItemMap m_Items;
+	static ItemMap m_Items; /**< All registered configuration items. */
 };
 
 }

lib/config/configitembuilder.cpp

@@ -68,7 +68,8 @@ void ConfigItemBuilder::AddExpression(const Expression& expr)
 	m_ExpressionList->AddExpression(expr);
 }
 
-void ConfigItemBuilder::AddExpression(const String& key, ExpressionOperator op, const Value& value)
+void ConfigItemBuilder::AddExpression(const String& key, ExpressionOperator op,
+    const Value& value)
 {
 	Expression expr(key, op, value, m_DebugInfo);
 	AddExpression(expr);
@@ -101,5 +102,6 @@ ConfigItem::Ptr ConfigItemBuilder::Compile(void)
 	Expression abstractExpr("__abstract", OperatorSet, m_Abstract, m_DebugInfo);
 	exprl->AddExpression(abstractExpr);
 
-	return boost::make_shared<ConfigItem>(m_Type, m_Name, exprl, m_Parents, m_DebugInfo);
+	return boost::make_shared<ConfigItem>(m_Type, m_Name, exprl, m_Parents,
+	    m_DebugInfo);
 }

lib/config/configitembuilder.h

@@ -46,19 +46,21 @@ public:
 	void AddParent(const String& parent);
 
 	void AddExpression(const Expression& expr);
-	void AddExpression(const String& key, ExpressionOperator op, const Value& value);
+	void AddExpression(const String& key, ExpressionOperator op,
+	    const Value& value);
 	void AddExpressionList(const ExpressionList::Ptr& exprl);
 
 	ConfigItem::Ptr Compile(void);
 
 private:
-	String m_Type;
+	String m_Type; /**< The object type. */
-	String m_Name;
+	String m_Name; /**< The name. */
-	bool m_Local;
+	bool m_Local; /**< Whether the item is local. */
-	bool m_Abstract;
+	bool m_Abstract; /**< Whether the item is abstract. */
-	vector<String> m_Parents;
+	vector<String> m_Parents; /**< The names of parent configuration
-	ExpressionList::Ptr m_ExpressionList;
+				       items. */
-	DebugInfo m_DebugInfo;
+	ExpressionList::Ptr m_ExpressionList; /**< Expressions for this item. */
+	DebugInfo m_DebugInfo; /**< Debug information. */
 };
 
 }

lib/config/debuginfo.h

@@ -57,6 +57,13 @@ struct DebugInfo
 	};
 };
 
+/**
+ * Outputs a DebugInfo struct to a stream.
+ *
+ * @param out The output stream.
+ * @param val The DebugInfo struct.
+ * @returns The output stream.
+ */
 inline ostream& operator<<(ostream& out, const DebugInfo& val)
 {
 	out << "in " << val.Path << ": "

lib/config/expression.cpp

@@ -21,7 +21,8 @@
 
 using namespace icinga;
 
-Expression::Expression(const String& key, ExpressionOperator op, const Value& value, const DebugInfo& debuginfo)
+Expression::Expression(const String& key, ExpressionOperator op,
+    const Value& value, const DebugInfo& debuginfo)
 	: m_Key(key), m_Operator(op), m_Value(value), m_DebugInfo(debuginfo)
 {
 }
@@ -69,7 +70,10 @@ void Expression::Execute(const Dictionary::Ptr& dictionary) const
 			if (!dict) {
 				if (!oldValue.IsEmpty()) {
 					stringstream message;
-					message << "Wrong argument types for += (non-dictionary and dictionary) (" << m_DebugInfo << ")";
+					message << "Wrong argument types for"
+					    " += (non-dictionary and"
+					    " dictionary) ("
+					        << m_DebugInfo << ")";
 					throw_exception(domain_error(message.str()));
 				}
 
@@ -88,7 +92,8 @@ void Expression::Execute(const Dictionary::Ptr& dictionary) const
 				}
 			} else {
 				stringstream message;
-				message << "+= only works for dictionaries (" << m_DebugInfo << ")";
+				message << "+= only works for dictionaries ("
+					<< m_DebugInfo << ")";
 				throw_exception(domain_error(message.str()));
 			}
 

lib/config/expression.h

@@ -46,7 +46,8 @@ enum ExpressionOperator
 struct I2_CONFIG_API Expression
 {
 public:
-	Expression(const String& key, ExpressionOperator op, const Value& value, const DebugInfo& debuginfo);
+	Expression(const String& key, ExpressionOperator op, const Value& value,
+	    const DebugInfo& debuginfo);
 
 	void Execute(const Dictionary::Ptr& dictionary) const;
 

lib/config/expressionlist.cpp

@@ -21,16 +21,32 @@
 
 using namespace icinga;
 
+/**
+ * Adds an expression to an expression list.
+ *
+ * @param expression The expression that should be added.
+ */
 void ExpressionList::AddExpression(const Expression& expression)
 {
 	m_Expressions.push_back(expression);
 }
 
+/**
+ * Returns the number of items currently contained in the expression list.
+ *
+ * @returns The length of the list.
+ */
 size_t ExpressionList::GetLength(void) const
 {
 	return m_Expressions.size();
 }
 
+/**
+ * Executes the expression list.
+ *
+ * @param dictionary The dictionary that should be manipulated by the
+ *		     expressions.
+ */
 void ExpressionList::Execute(const Dictionary::Ptr& dictionary) const
 {
 	BOOST_FOREACH(const Expression& expression, m_Expressions) {

lib/config/i2-config.h

@@ -24,7 +24,7 @@
  * @defgroup config Configuration library
  *
  * The configuration library implements a compiler for Icinga 2's configuration
- * format. It also provides functionality to create configuration objects
+ * format. It also provides functionality for creating configuration objects
  * at runtime.
  */