Updated documentation.

Cleaned up Dictionary class.

base/application.cpp

@@ -446,20 +446,18 @@ static void ApplicationSigIntHandler(int signum)
 #endif /* _WIN32 */
 
 /**
- * Runs the specified application.
+ * Runs the application.
  *
  * @param argc The number of arguments.
  * @param argv The arguments that should be passed to the application.
- * @param instance The application instance.
  * @returns The application's exit code.
  */
-int icinga::RunApplication(int argc, char **argv, Application::Ptr instance)
+int Application::Run(int argc, char **argv)
 {
 	int result;
 
 	assert(!Application::Instance);
-
+	Application::Instance = static_pointer_cast<Application>(shared_from_this());
-	Application::Instance = instance;
 
 #ifndef _WIN32
 	struct sigaction sa;
@@ -476,14 +474,18 @@ int icinga::RunApplication(int argc, char **argv, Application::Ptr instance)
 	for (int i = 0; i < argc; i++)
 		args.push_back(string(argv[i]));
 
-	Application::Instance->SetArguments(args);
+	SetArguments(args);
 
-	if (Application::Instance->IsDebugging()) {
+	if (IsDebugging()) {
-		result = Application::Instance->Main(args);
+		result = Main(args);
+
+		Application::Instance.reset();
 	} else {
 		try {
-			result = Application::Instance->Main(args);
+			result = Main(args);
 		} catch (const Exception& ex) {
+			Application::Instance.reset();
+
 			Application::Log("---");
 			Application::Log("Exception: " + Utility::GetTypeName(ex));
 			Application::Log("Message: " + ex.GetMessage());

base/application.h

@@ -26,6 +26,9 @@ class Component;
 
 DEFINE_EXCEPTION_CLASS(ComponentLoadException);
 
+/**
+ * Abstract base class for applications.
+ */
 class I2_BASE_API Application : public Object {
 private:
 	bool m_ShuttingDown;
@@ -47,6 +50,8 @@ public:
 	Application(void);
 	~Application(void);
 
+	int Run(int argc, char **argv);
+
 	virtual int Main(const vector<string>& args) = 0;
 
 	void SetArguments(const vector<string>& arguments);
@@ -68,8 +73,6 @@ public:
 	bool IsDebugging(void) const;
 };
 
-int I2_EXPORT RunApplication(int argc, char **argv, Application::Ptr instance);
-
 }
 
 #endif /* APPLICATION_H */

base/component.h

@@ -23,6 +23,10 @@
 namespace icinga
 {
 
+/**
+ * An application extension that can be dynamically loaded
+ * at run-time.
+ */
 class I2_BASE_API Component : public Object
 {
 private:

base/configcollection.h

@@ -25,6 +25,9 @@ namespace icinga
 
 class ConfigHive;
 
+/**
+ * A collection of configuration objects that each have the same type.
+ */
 class I2_BASE_API ConfigCollection : public Object
 {
 private:

base/confighive.h

@@ -23,6 +23,9 @@
 namespace icinga
 {
 
+/**
+ * A collection of all configuration objects that belong to an application.
+ */
 class I2_BASE_API ConfigHive : public Object
 {
 public:

base/configobject.h

@@ -27,6 +27,9 @@ namespace icinga
 
 class ConfigHive;
 
+/**
+ * A configuration object that has arbitrary properties.
+ */
 class I2_BASE_API ConfigObject : public Dictionary
 {
 private:

base/dictionary.cpp

@@ -56,13 +56,6 @@ void Dictionary::SetProperty(string key, const Variant& value)
 	}
 
 	m_Data[key] = value;
-
-	PropertyChangedEventArgs dpce;
-	dpce.Source = shared_from_this();
-	dpce.Property = key;
-	dpce.OldValue = oldValue;
-	dpce.NewValue = value;
-	OnPropertyChanged(dpce);
 }
 
 /**

base/dictionary.h

@@ -26,13 +26,9 @@ namespace icinga
 typedef map<string, Variant>::const_iterator ConstDictionaryIterator;
 typedef map<string, Variant>::iterator DictionaryIterator;
 
-struct I2_BASE_API PropertyChangedEventArgs : public EventArgs
+/**
-{
+ * A container that holds key-value pairs.
-	string Property;
+ */
-	Variant OldValue;
-	Variant NewValue;
-};
-
 class I2_BASE_API Dictionary : public Object
 {
 private:
@@ -67,8 +63,6 @@ public:
 	void AddUnnamedPropertyObject(const Object::Ptr& value);
 
 	long GetLength(void) const;
-
-	Event<PropertyChangedEventArgs> OnPropertyChanged;
 };
 
 }

base/event.h

@@ -23,58 +23,64 @@
 namespace icinga
 {
 
+/**
+ * Base class for event arguments.
+ */
 struct I2_BASE_API EventArgs
 {
-	Object::Ptr Source;
+	Object::Ptr Source; /**< The source of the event. */
 };
 
+/**
+ * An observable event.
+ */
 template<class TArgs>
 class Event
 {
 public:
-	typedef function<int (const TArgs&)> DelegateType;
+	typedef function<int (const TArgs&)> ObserverType;
 
 private:
-	vector<DelegateType> m_Delegates;
+	vector<ObserverType> m_Observers;
 
 public:
 	/**
-	 * Adds a delegate to this event.
+	 * Adds an observer to this event.
 	 *
 	 * @param rhs The delegate.
 	 */
-	Event<TArgs>& operator +=(const DelegateType& rhs)
+	Event<TArgs>& operator +=(const ObserverType& rhs)
 	{
-		m_Delegates.push_back(rhs);
+		m_Observers.push_back(rhs);
 		return *this;
 	}
 
 	/**
-	 * Removes a delegate from this event.
+	 * Removes an observer from this event.
 	 *
 	 * @param rhs The delegate.
 	 */
-	Event<TArgs>& operator -=(const DelegateType& rhs)
+	Event<TArgs>& operator -=(const ObserverType& rhs)
 	{
-		m_Delegates.erase(rhs);
+		m_Observers.erase(rhs);
 		return *this;
 	}
 
 	/**
-	 * Invokes each delegate that is registered for this event. Any delegates
+	 * Invokes each observer function that is registered for this event. Any
-	 * which return -1 are removed.
+	 * observer function which returns -1 is removed.
 	 *
 	 * @param args Event arguments.
 	 */
 	void operator()(const TArgs& args)
 	{
-		typename vector<DelegateType>::iterator i;
+		typename vector<ObserverType>::iterator i;
 
-		for (i = m_Delegates.begin(); i != m_Delegates.end(); ) {
+		for (i = m_Observers.begin(); i != m_Observers.end(); ) {
 			int result = (*i)(args);
 
 			if (result == -1)
-				i = m_Delegates.erase(i);
+				i = m_Observers.erase(i);
 			else
 				i++;
 		}

base/exception.h

@@ -24,8 +24,6 @@ namespace icinga
 {
 
 /**
- * Exception
- *
  * Base class for all exceptions.
  */
 class I2_BASE_API Exception
@@ -41,7 +39,7 @@ public:
 	Exception(const string& message);
 
 	/**
-	 * Destructor for the Exception class. Required for RTTI.
+	 * Destructor for the Exception class. Must be virtual for RTTI to work.
 	 */
 	virtual ~Exception(void)
 	{
@@ -68,37 +66,82 @@ DEFINE_EXCEPTION_CLASS(NotImplementedException);
 DEFINE_EXCEPTION_CLASS(InvalidArgumentException);
 
 #ifdef _WIN32
+/**
+ * A Win32 error encapsulated in an exception.
+ */
 class Win32Exception : public Exception
 {
 public:
+	/**
+	 * Constructor for the Win32Exception class.
+	 *
+	 * @param message An error message.
+	 * @param errorCode A Win32 error code.
+	 */
 	inline Win32Exception(const string& message, int errorCode)
 	{
 		SetMessage(message + ": " + FormatErrorCode(errorCode));
 	}
 
+	/**
+	 * Returns a string that describes the Win32 error.
+	 *
+	 * @param code The Win32 error code.
+	 * @returns A description of the error.
+	 */
 	static string FormatErrorCode(int code);
 };
 #endif /* _WIN32 */
 
+/**
+ * A Posix error encapsulated in an exception.
+ */
 class PosixException : public Exception
 {
 public:
+	/**
+	 * Constructor for the PosixException class.
+	 *
+	 * @param message An error message.
+	 * @param errorCode A Posix (errno) error code.
+	 */
 	inline PosixException(const string& message, int errorCode)
 	{
 		SetMessage(message + ": " + FormatErrorCode(errorCode));
 	}
 
+	/**
+	 * Returns a string that describes the Posix error.
+	 *
+	 * @param code The Posix error code.
+	 * @returns A description of the error.
+	 */
 	static string FormatErrorCode(int code);
 };
 
+/**
+ * An OpenSSL error encapsulated in an exception.
+ */
 class OpenSSLException : public Exception
 {
 public:
+	/**
+	 * Constructor for the OpenSSLException class.
+	 *
+	 * @param message An error message.
+	 * @param errorCode An OpenSSL error code.
+	 */
 	inline OpenSSLException(const string& message, int errorCode)
 	{
 		SetMessage(message + ": " + FormatErrorCode(errorCode));
 	}
 
+	/**
+	 * Returns a string that describes the OpenSSL error.
+	 *
+	 * @param code The OpenSSL error code.
+	 * @returns A description of the error.
+	 */
 	static string FormatErrorCode(int code);
 };
 

base/fifo.h

@@ -23,6 +23,9 @@
 namespace icinga
 {
 
+/**
+ * A byte-based FIFO buffer.
+ */
 class I2_BASE_API FIFO : public Object
 {
 private:

base/socket.h

@@ -22,19 +22,22 @@
 
 namespace icinga {
 
+/**
+ * Event arguments for socket errors.
+ */
 struct I2_BASE_API SocketErrorEventArgs : public EventArgs
 {
-	typedef shared_ptr<SocketErrorEventArgs> Ptr;
+	int Code; /**< The error code. */
-	typedef weak_ptr<SocketErrorEventArgs> WeakPtr;
+	string Message; /**< A message describing the error. */
-
-	int Code;
-	string Message;
 };
 
+/**
+ * Base class for sockets.
+ */
 class I2_BASE_API Socket : public Object
 {
 private:
-	SOCKET m_FD;
+	SOCKET m_FD; /**< The socket descriptor. */
 
 	int ExceptionEventHandler(const EventArgs& ea);
 

base/tcpclient.h

@@ -23,12 +23,18 @@
 namespace icinga
 {
 
+/**
+ * The role of a TCP client object.
+ */
 enum I2_BASE_API TCPClientRole
 {
-	RoleInbound,
+	RoleInbound, /**< inbound socket, i.e. one that was returned from accept() */
-	RoleOutbound
+	RoleOutbound /**< outbound socket, i.e. one that is connect()'d to a remote socket */
 };
 
+/**
+ * A TCP client connection.
+ */
 class I2_BASE_API TCPClient : public TCPSocket
 {
 private:
@@ -61,6 +67,13 @@ public:
 	Event<EventArgs> OnDataAvailable;
 };
 
+/**
+ * Returns a new unconnected TCPClient object that has the specified
+ * connection role.
+ *
+ * @param role The role of the new object.
+ * @returns A new TCPClient object.
+ */
 TCPClient::Ptr TCPClientFactory(TCPClientRole role);
 
 }

base/tcpserver.h

@@ -23,14 +23,17 @@
 namespace icinga
 {
 
+/**
+ * Event arguments for the "new client" event.
+ */
 struct I2_BASE_API NewClientEventArgs : public EventArgs
 {
-	typedef shared_ptr<NewClientEventArgs> Ptr;
+	TCPSocket::Ptr Client; /**< The new client object. */
-	typedef weak_ptr<NewClientEventArgs> WeakPtr;
-
-	TCPSocket::Ptr Client;
 };
 
+/**
+ * A TCP server that listens on a TCP port and accepts incoming
+ * client connections. */
 class I2_BASE_API TCPServer : public TCPSocket
 {
 private:

base/tcpsocket.h

@@ -23,6 +23,9 @@
 namespace icinga
 {
 
+/**
+ * A TCP socket.
+ */
 class I2_BASE_API TCPSocket : public Socket
 {
 private:

base/timer.h

@@ -24,22 +24,25 @@
 
 namespace icinga {
 
+/**
+ * Event arguments for the "timer expired" event.
+ */
 struct I2_BASE_API TimerEventArgs : public EventArgs
 {
-	typedef shared_ptr<TimerEventArgs> Ptr;
+	EventArgs UserArgs; /**< User-specified event arguments. */
-	typedef weak_ptr<TimerEventArgs> WeakPtr;
-
-	EventArgs UserArgs;
 };
 
+/**
+ * A timer that periodically triggers an event.
+ */
 class I2_BASE_API Timer : public Object
 {
 private:
-	EventArgs m_UserArgs;
+	EventArgs m_UserArgs; /**< User-specified event arguments. */
-	unsigned int m_Interval;
+	unsigned int m_Interval; /**< The interval of the timer. */
-	time_t m_Next;
+	time_t m_Next; /**< When the next event should happen. */
 
-	static time_t NextCall;
+	static time_t NextCall; /**< When the next event should happen (for all timers). */
 
 	static void RescheduleTimers(void);
 

base/tlsclient.h

@@ -23,13 +23,21 @@
 namespace icinga
 {
 
+/**
+ * Event arguments for the "SSL certificate verification" event.
+ */
 struct I2_BASE_API VerifyCertificateEventArgs : public EventArgs
 {
-	bool ValidCertificate;
+	bool ValidCertificate; /**< Whether the certificate is valid, can be
-	X509_STORE_CTX *Context;
+			            changed by the event handler. */
-	shared_ptr<X509> Certificate;
+	X509_STORE_CTX *Context; /**< The X509 store context. */
+	shared_ptr<X509> Certificate; /**< The X509 certificate that should
+				           ve verified. */
 };
 
+/**
+ * A TLS client connection.
+ */
 class I2_BASE_API TLSClient : public TCPClient
 {
 private:

base/variant.h

@@ -23,6 +23,9 @@
 namespace icinga
 {
 
+/**
+ * The type of a Variant object.
+ */
 enum I2_BASE_API VariantType
 {
 	VariantEmpty,
@@ -31,14 +34,20 @@ enum I2_BASE_API VariantType
 	VariantObject
 };
 
+/**
+ * A type that can hold an arbitrary value.
+ */
 class I2_BASE_API Variant
 {
 private:
-	mutable VariantType m_Type;
+	mutable VariantType m_Type; /**< The type of the Variant. */
 
-	mutable long m_IntegerValue;
+	mutable long m_IntegerValue; /**< The value of the Variant
-	mutable string m_StringValue;
+				          if m_Type == VariantInteger */
-	mutable Object::Ptr m_ObjectValue;
+	mutable string m_StringValue; /**< The value of the Variant
+				           if m_Type == VariantString */
+	mutable Object::Ptr m_ObjectValue; /**< The value of the Variant
+					        if m_Type == VariantObject */
 
 	void Convert(VariantType newType) const;
 

icinga-app/icinga.cpp

@@ -21,8 +21,15 @@
 
 using namespace icinga;
 
+/**
+ * Entry point for the Icinga application.
+ *
+ * @params argc Number of command line arguments.
+ * @params argv Command line arguments.
+ * @returns The application's exit status.
+ */
 int main(int argc, char **argv)
 {
 	IcingaApplication::Ptr instance = make_shared<IcingaApplication>();
-	return icinga::RunApplication(argc, argv, instance);
+	return instance->Run(argc, argv);
 }