Updated doxygen documentation.

docs/Doxyfile.in

@@ -648,7 +648,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = @top_srcdir@/base @top_srcdir@/jsonrpc @top_srcdir@/icinga @top_srcdir@/components @top_srcdir@/icinga-app
+INPUT                  = lib/base lib/config lib/icinga lib/remoting components icinga-app
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is

lib/base/component.h

@@ -23,6 +23,11 @@
 namespace icinga
 {
 
+/**
+ * Interface for application extensions.
+ *
+ * @ingroup base
+ */
 class I2_BASE_API IComponent : public Object
 {
 public:

lib/base/dictionary.cpp

@@ -217,9 +217,8 @@ Dictionary::Ptr Dictionary::FromJson(cJSON *json)
 }
 
 /**
- * Converts a dictionary to a JSON object.
+ * Converts this dictionary to a JSON object.
  *
- * @param dictionary The dictionary.
  * @returns A JSON object that is equivalent to the dictionary. Values that
  *	    cannot be represented in JSON are omitted.
  */

lib/base/dynamicobject.h

@@ -23,6 +23,9 @@
 namespace icinga
 {
 
+/**
+ * The type of an attribute for a DynamicObject.
+ */
 enum DynamicAttributeType
 {
 	Attribute_Transient = 1,
@@ -43,6 +46,9 @@ enum DynamicAttributeType
 	Attribute_All = Attribute_Transient | Attribute_Local | Attribute_Replicated | Attribute_Config
 };
 
+/**
+ * An attribute for a DynamicObject.
+ */
 struct DynamicAttribute
 {
 	Value Data;
@@ -51,7 +57,8 @@ struct DynamicAttribute
 };
 
 /**
- * A dynamic object that can be instantiated from the configuration file.
+ * A dynamic object that can be instantiated from the configuration file
+ * and that supports attribute replication to remote application instances.
  *
  * @ingroup base
  */
@@ -147,6 +154,11 @@ private:
 	void InternalApplyUpdate(const Dictionary::Ptr& serializedUpdate, int allowedTypes, bool suppressEvents);
 };
 
+/**
+ * Helper class for registering DynamicObject implementation classes.
+ *
+ * @ingroup base
+ */
 class RegisterClassHelper
 {
 public:

lib/base/event.h

@@ -23,6 +23,11 @@
 namespace icinga
 {
 
+/**
+ * A thread-safe event that can be posted to the main thread's event queue.
+ *
+ * @ingroup base
+ */
 class I2_BASE_API Event
 {
 public:

lib/base/fifo.cpp

@@ -130,21 +130,6 @@ void FIFO::Read(void *buffer, size_t count)
 	Optimize();
 }
 
-/**
- * Returns a pointer to the start of the write buffer.
- *
- * @param count Minimum size of the buffer; on return this parameter
- *              contains the actual size of the available buffer which can
- *              be larger than the requested size.
- */
-/*void *FIFO::GetWriteBuffer(size_t *count)
-{
-	ResizeBuffer(m_Offset + m_DataSize + *count);
-	*count = m_AllocSize - m_Offset - m_DataSize;
-
-	return m_Buffer + m_Offset + m_DataSize;
-}*/
-
 /**
  * Implements IOQueue::Write.
  */

lib/base/ioqueue.h

@@ -25,6 +25,8 @@ namespace icinga
 
 /**
  * An I/O queue.
+ *
+ * @ingroup base
  */
 class IOQueue
 {
@@ -41,8 +43,8 @@ public:
 	 * to read more data than is available in the queue is a programming error.
 	 * Use GetBytesAvailable() to check how much data is available.
 	 *
-	 * @buffer The buffer where data should be stored. May be NULL if you're
-	 *		 not actually interested in the data.
+	 * @param buffer The buffer where data should be stored. May be NULL if
+	 *		 you're not actually interested in the data.
 	 * @param count The number of bytes to read from the queue.
 	 */
 	virtual void Peek(void *buffer, size_t count) = 0;

lib/base/logger.cpp

@@ -24,10 +24,9 @@ using namespace icinga;
 REGISTER_CLASS(Logger);
 
 /**
- * Constructor for the logger class.
+ * Constructor for the Logger class.
  *
- * @param minSeverity The minimum severity of log messages that should be sent
- *                    to this logger.
+ * @param properties A serialized dictionary containing attributes.
  */
 Logger::Logger(const Dictionary::Ptr& properties)
 	: DynamicObject(properties)

lib/base/logger.h

@@ -50,6 +50,8 @@ struct LogEntry {
 
 /**
  * Base class for all loggers.
+ *
+ * @ingroup base
  */
 class I2_BASE_API ILogger : public Object
 {
@@ -68,6 +70,11 @@ private:
 	friend class Logger;
 };
 
+/**
+ * A log provider. Can be instantiated from the config.
+ *
+ * @ingroup base
+ */
 class I2_BASE_API Logger : public DynamicObject
 {
 public:

lib/base/netstring.cpp

@@ -24,9 +24,9 @@ using namespace icinga;
 /**
  * Reads data from an IOQueue in netString format.
  *
- * @param fifo The IOQueue to read from.
- * @param[out] str The String that has been read from the FIFO.
- * @returns true if a complete String was read from the FIFO, false otherwise.
+ * @param queue The IOQueue to read from.
+ * @param[out] str The String that has been read from the IOQueue.
+ * @returns true if a complete String was read from the IOQueue, false otherwise.
  * @exception invalid_argument The input stream is invalid.
  * @see https://github.com/PeterScott/netString-c/blob/master/netString.c
  */
@@ -104,16 +104,16 @@ bool NetString::ReadStringFromIOQueue(IOQueue *queue, String *str)
 
 	free(buffer);
 
-	/* remove the data from the fifo */
+	/* remove the data from the IOQueue */
 	queue->Read(NULL, buffer_length);
 
 	return true;
 }
 
 /**
- * Writes data into a FIFO using the netString format.
+ * Writes data into an IOQueue using the netString format.
  *
- * @param fifo The FIFO.
+ * @param queue The IOQueue.
  * @param str The String that is to be written.
  */
 void NetString::WriteStringToIOQueue(IOQueue *queue, const String& str)

lib/base/process.h

@@ -23,6 +23,11 @@
 namespace icinga
 {
 
+/**
+ * The result of a Process task.
+ *
+ * @ingroup base
+ */
 struct ProcessResult
 {
 	double ExecutionStart;
@@ -31,6 +36,12 @@ struct ProcessResult
 	String Output;
 };
 
+/**
+ * A process task. Executes an external application and returns the exit
+ * code and console output.
+ *
+ * @ingroup base
+ */
 class I2_BASE_API Process : public AsyncTask<Process, ProcessResult>
 {
 public:

lib/base/qstring.cpp

@@ -1,3 +1,22 @@
+/******************************************************************************
+ * Icinga 2                                                                   *
+ * Copyright (C) 2012 Icinga Development Team (http://www.icinga.org/)        *
+ *                                                                            *
+ * This program is free software; you can redistribute it and/or              *
+ * modify it under the terms of the GNU General Public License                *
+ * as published by the Free Software Foundation; either version 2             *
+ * of the License, or (at your option) any later version.                     *
+ *                                                                            *
+ * This program is distributed in the hope that it will be useful,            *
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of             *
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the              *
+ * GNU General Public License for more details.                               *
+ *                                                                            *
+ * You should have received a copy of the GNU General Public License          *
+ * along with this program; if not, write to the Free Software Foundation     *
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.             *
+ ******************************************************************************/
+
 #include "i2-base.h"
 
 using namespace icinga;

lib/base/qstring.h

@@ -1,3 +1,22 @@
+/******************************************************************************
+ * Icinga 2                                                                   *
+ * Copyright (C) 2012 Icinga Development Team (http://www.icinga.org/)        *
+ *                                                                            *
+ * This program is free software; you can redistribute it and/or              *
+ * modify it under the terms of the GNU General Public License                *
+ * as published by the Free Software Foundation; either version 2             *
+ * of the License, or (at your option) any later version.                     *
+ *                                                                            *
+ * This program is distributed in the hope that it will be useful,            *
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of             *
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the              *
+ * GNU General Public License for more details.                               *
+ *                                                                            *
+ * You should have received a copy of the GNU General Public License          *
+ * along with this program; if not, write to the Free Software Foundation     *
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.             *
+ ******************************************************************************/
+
 #ifndef STRING_H
 #define STRING_H
 
@@ -6,7 +25,7 @@ namespace icinga {
 /**
  * String class.
  *
- * Rationale: The std::string class has an ambiguous assignment
+ * Rationale for having this: The std::string class has an ambiguous assignment
  * operator when used in conjunction with the Value class.
  */
 class I2_BASE_API String

lib/base/ringbuffer.h

@@ -23,6 +23,11 @@
 namespace icinga
 {
 
+/**
+ * A ring buffer that holds a pre-defined number of integers.
+ *
+ * @ingroup base
+ */
 class I2_BASE_API RingBuffer
 {
 public:

lib/base/scriptfunction.h

@@ -25,6 +25,11 @@ namespace icinga
 
 class ScriptTask;
 
+/**
+ * A script function that can be used to execute a script task.
+ *
+ * @ingroup base
+ */
 class I2_BASE_API ScriptFunction : public Object
 {
 public:

lib/base/scripttask.h

@@ -23,6 +23,11 @@
 namespace icinga
 {
 
+/**
+ * A script task.
+ *
+ * @ingroup base
+ */
 class I2_BASE_API ScriptTask : public AsyncTask<ScriptTask, Value>
 {
 public:

lib/base/streamlogger.cpp

@@ -13,7 +13,6 @@ StreamLogger::StreamLogger(void)
  * Constructor for the StreamLogger class.
  *
  * @param stream The stream.
- * @param minSeverity Minimum severity for log messages.
  */
 StreamLogger::StreamLogger(ostream *stream)
 	: ILogger(), m_Stream(stream), m_OwnsStream(false)

lib/base/streamlogger.h

@@ -5,7 +5,9 @@ namespace icinga
 {
 
 /**
- * A logger that logs to stdout.
+ * A logger that logs to an iostream.
+ *
+ * @ingroup base
  */
 class I2_BASE_API StreamLogger : public ILogger
 {

lib/base/sysloglogger.cpp

@@ -1,3 +1,22 @@
+/******************************************************************************
+ * Icinga 2                                                                   *
+ * Copyright (C) 2012 Icinga Development Team (http://www.icinga.org/)        *
+ *                                                                            *
+ * This program is free software; you can redistribute it and/or              *
+ * modify it under the terms of the GNU General Public License                *
+ * as published by the Free Software Foundation; either version 2             *
+ * of the License, or (at your option) any later version.                     *
+ *                                                                            *
+ * This program is distributed in the hope that it will be useful,            *
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of             *
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the              *
+ * GNU General Public License for more details.                               *
+ *                                                                            *
+ * You should have received a copy of the GNU General Public License          *
+ * along with this program; if not, write to the Free Software Foundation     *
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.             *
+ ******************************************************************************/
+
 #include "i2-base.h"
 
 #ifndef _WIN32

lib/base/sysloglogger.h

@@ -1,3 +1,22 @@
+/******************************************************************************
+ * Icinga 2                                                                   *
+ * Copyright (C) 2012 Icinga Development Team (http://www.icinga.org/)        *
+ *                                                                            *
+ * This program is free software; you can redistribute it and/or              *
+ * modify it under the terms of the GNU General Public License                *
+ * as published by the Free Software Foundation; either version 2             *
+ * of the License, or (at your option) any later version.                     *
+ *                                                                            *
+ * This program is distributed in the hope that it will be useful,            *
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of             *
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the              *
+ * GNU General Public License for more details.                               *
+ *                                                                            *
+ * You should have received a copy of the GNU General Public License          *
+ * along with this program; if not, write to the Free Software Foundation     *
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.             *
+ ******************************************************************************/
+
 #ifndef SYSLOGLOGGER_H
 #define SYSLOGLOGGER_H
 
@@ -7,6 +26,8 @@ namespace icinga
 
 /**
  * A logger that logs to syslog.
+ *
+ * @ingroup base
  */
 class I2_BASE_API SyslogLogger : public ILogger
 {

lib/base/tcpserver.h

@@ -39,7 +39,7 @@ public:
 
 	TcpServer(void);
 
-	void SetClientFactory(const ClientFactory& function);
+	void SetClientFactory(const ClientFactory& clientFactory);
 	ClientFactory GetFactoryFunction(void) const;
 
 	void Listen(void);

lib/base/utility.cpp

@@ -249,7 +249,7 @@ String Utility::BaseName(const String& path)
 /**
  * Null deleter. Used as a parameter for the shared_ptr constructor.
  *
- * @param -- The object that should be deleted.
+ * @param - The object that should be deleted.
  */
 void Utility::NullDeleter(void *)
 {

lib/base/utility.h

@@ -44,7 +44,7 @@ public:
 	static String DirName(const String& path);
 	static String BaseName(const String& path);
 
-	static void NullDeleter(void *obj);
+	static void NullDeleter(void *);
 
 	static double GetTime(void);
 

lib/base/value.cpp

@@ -133,7 +133,7 @@ cJSON *Value::ToJson(void) const
 /**
  * Deserializes the string representation of a variant.
  *
- * @params jsonString A JSON string obtained from Value::Serialize
+ * @param jsonString A JSON string obtained from Value::Serialize
  * @returns The newly deserialized variant.
  */
 Value Value::Deserialize(const String& jsonString)

lib/config/i2-config.h

@@ -21,10 +21,11 @@
 #define I2CONFIG_H
 
 /**
- * @defgroup config Dynamic object library
+ * @defgroup config Configuration library
  *
- * The dynamic object library implements serializable objects which support
- * inheritance.
+ * The configuration library implements a compiler for Icinga 2's configuration
+ * format. It also provides functionality to create configuration objects
+ * at runtime.
  */
 
 #include <i2-base.h>

lib/icinga/cib.h

@@ -23,6 +23,12 @@
 namespace icinga
 {
 
+/**
+ * Common Information Base class. Holds some statistics (and will likely be
+ * removed/refactored).
+ *
+ * @ingroup icinga
+ */
 class I2_ICINGA_API CIB
 {
 public:

lib/icinga/host.h

@@ -23,6 +23,11 @@
 namespace icinga
 {
 
+/**
+ * An Icinga host.
+ * 
+ * @ingroup icinga
+ */
 class I2_ICINGA_API Host : public DynamicObject
 {
 public:

lib/icinga/hostgroup.h

@@ -23,6 +23,11 @@
 namespace icinga
 {
 
+/**
+ * An Icinga host group.
+ *
+ * @ingroup icinga
+ */
 class I2_ICINGA_API HostGroup : public DynamicObject
 {
 public:

lib/icinga/i2-icinga.h

@@ -21,10 +21,10 @@
 #define I2ICINGA_H
 
 /**
- * @defgroup icinga Icinga application
+ * @defgroup icinga Icinga library
  *
- * The Icinga application is in charge of boot-strapping the Icinga
- * environment and loading additional components.
+ * The Icinga library implements all Icinga-specific functionality that is
+ * common to all components (e.g. hosts, services, etc.).
  */
 
 #include <i2-base.h>

lib/icinga/macroprocessor.h

@@ -23,6 +23,11 @@
 namespace icinga
 {
 
+/**
+ * Resolves macros.
+ *
+ * @ingroup icinga
+ */
 class I2_ICINGA_API MacroProcessor
 {
 public:

lib/icinga/nagioschecktask.h

@@ -23,6 +23,11 @@
 namespace icinga
 {
 
+/**
+ * Implements Nagios(TM)-style checks.
+ *
+ * @ingroup icinga
+ */
 class I2_ICINGA_API NagiosCheckTask
 {
 public:

lib/icinga/nullchecktask.h

@@ -23,6 +23,11 @@
 namespace icinga
 {
 
+/**
+ * Test class for additional check types. Implements the "null" check type.
+ *
+ * @ingroup icinga
+ */
 class I2_ICINGA_API NullCheckTask
 {
 public:

lib/icinga/service.h

@@ -23,6 +23,11 @@
 namespace icinga
 {
 
+/**
+ * The state of a service.
+ *
+ * @ingroup icinga
+ */
 enum ServiceState
 {
 	StateOK,
@@ -32,6 +37,11 @@ enum ServiceState
 	StateUncheckable,
 };
 
+/**
+ * The state type of a service.
+ *
+ * @ingroup icinga
+ */
 enum ServiceStateType
 {
 	StateTypeSoft,
@@ -41,6 +51,11 @@ enum ServiceStateType
 class CheckResultMessage;
 class ServiceStatusMessage;
 
+/**
+ * An Icinga service.
+ *
+ * @ingroup icinga
+ */
 class I2_ICINGA_API Service : public DynamicObject
 {
 public:

lib/icinga/servicegroup.h

@@ -23,6 +23,11 @@
 namespace icinga
 {
 
+/**
+ * An Icinga service group.
+ *
+ * @ingroup icinga
+ */
 class I2_ICINGA_API ServiceGroup : public DynamicObject
 {
 public:

lib/icinga/servicestatechangemessage.h

@@ -23,6 +23,11 @@
 namespace icinga
 {
 
+/**
+ * A state change message for a service.
+ *
+ * @ingroup icinga
+ */
 class I2_ICINGA_API ServiceStateChangeMessage : public MessagePart
 {
 public:

lib/remoting/endpoint.h

@@ -28,7 +28,7 @@ class EndpointManager;
 /**
  * An endpoint that can be used to send and receive messages.
  *
- * @ingroup icinga
+ * @ingroup remoting
  */
 class I2_REMOTING_API Endpoint : public DynamicObject
 {

lib/remoting/endpointmanager.h

@@ -26,7 +26,7 @@ namespace icinga
 /**
  * Forwards messages between endpoints.
  *
- * @ingroup icinga
+ * @ingroup remoting
  */
 class I2_REMOTING_API EndpointManager : public Object
 {
@@ -56,10 +56,6 @@ public:
 
 	void ProcessResponseMessage(const Endpoint::Ptr& sender, const ResponseMessage& message);
 
-//	void ForEachEndpoint(function<void (const EndpointManager::Ptr&, const Endpoint::Ptr&)> callback);
-//	Iterator Begin(void);
-//	Iterator End(void);
-
 	boost::signal<void (const EndpointManager::Ptr&, const Endpoint::Ptr&)> OnNewEndpoint;
 
 private:
@@ -78,7 +74,7 @@ private:
 	/**
 	 * Information about a pending API request.
 	 *
-	 * @ingroup icinga
+	 * @ingroup remoting
 	 */
 	struct I2_REMOTING_API PendingRequest
 	{

lib/remoting/i2-remoting.h

@@ -21,10 +21,10 @@
 #define I2REMOTING_H
 
 /**
- * @defgroup remoting JSON-RPC library
+ * @defgroup remoting Remoting library
  *
- * The JSON-RPC library implements server and client classes for the JSON-RPC
- * protocol.
+ * Implements server and client classes for the JSON-RPC protocol. Also
+ * supports endpoint-based communication using messages.
  */
 
 #include <i2-base.h>

lib/remoting/messagepart.cpp

@@ -63,7 +63,7 @@ Dictionary::Ptr MessagePart::GetDictionary(void) const
  * Retrieves a property's value.
  *
  * @param key The name of the property.
- * @param[out] The value.
+ * @param[out] value The value.
  * @returns true if the value was retrieved, false otherwise.
  */
 bool MessagePart::Get(String key, MessagePart *value) const

lib/remoting/messagepart.h

@@ -45,7 +45,7 @@ public:
 	 * Retrieves a property's value.
 	 *
 	 * @param key The name of the property.
-	 * @param[out] The value.
+	 * @param[out] value The value.
 	 * @returns true if the value was retrieved, false otherwise.
 	 */
 	template<typename T>