Added missing doc strings.

diff --git a/lib/base/application.cpp b/lib/base/application.cpp
index 4f5be7e2e01b5844b555c3b9328be3a660a71287..66a337b1743da56822482f91c35b2c4c36dd911d 100644 (file)
--- a/lib/base/application.cpp
+++ b/lib/base/application.cpp
@@ -212,11 +212,19 @@ bool Application::IsDebugging(void)
        return m_Debugging;
 }
 
+/**
+ * Checks whether we're currently on the main thread.
+ *
+ * @returns true if this is the main thread, false otherwise
+ */
 bool Application::IsMainThread(void)
 {
        return (boost::this_thread::get_id() == m_MainThreadID);
 }
 
+/**
+ * Sets the main thread to the currently running thread.
+ */
 void Application::SetMainThread(void)
 {
        m_MainThreadID = boost::this_thread::get_id();
@@ -313,6 +321,11 @@ int Application::Run(int argc, char **argv)
        return result;
 }
 
+/**
+ * Grabs the PID file lock and updates the PID.
+ *
+ * @param filename The name of the PID file.
+ */
 void Application::UpdatePidFile(const String& filename)
 {
        ClosePidFile();
@@ -344,6 +357,9 @@ void Application::UpdatePidFile(const String& filename)
        fflush(m_PidFile);
 }
 
+/**
+ * Closes the PID file. Does nothing if the PID file is not currently open.
+ */
 void Application::ClosePidFile(void)
 {
        if (m_PidFile != NULL)

diff --git a/lib/base/component.cpp b/lib/base/component.cpp
index c28847d84a9729d08b8ee4e7d5d19f2130b42adc..70652aab97b79226974bd1f45bb6b28f41b5a3ec 100644 (file)
--- a/lib/base/component.cpp
+++ b/lib/base/component.cpp
@@ -99,6 +99,9 @@ Component::Component(const Dictionary::Ptr& properties)
        m_Impl = impl;
 }
 
+/**
+ * Destructor for the Component class.
+ */
 Component::~Component(void)
 {
        if (m_Impl)

diff --git a/lib/base/dictionary.cpp b/lib/base/dictionary.cpp
index 6fcfeaf594fd503b38374050548edb1c36b421a0..e9442b1831b04a35d8f84f09fa89afb649990cef 100644 (file)
--- a/lib/base/dictionary.cpp
+++ b/lib/base/dictionary.cpp
@@ -22,6 +22,9 @@
 
 using namespace icinga;
 
+/**
+ * Compares the keys of dictionary keys using the less operator.
+ */
 struct DictionaryKeyLessComparer
 {
        bool operator()(const pair<String, Value>& a, const char *b)

diff --git a/lib/base/event.cpp b/lib/base/event.cpp
index d72b184ae6dee7226d84e1367bc6ce9673c9a368..803662e8626ecd308b58b148dc88e203e39fb26b 100644 (file)
--- a/lib/base/event.cpp
+++ b/lib/base/event.cpp
@@ -25,14 +25,27 @@ vector<Event> Event::m_Events;
 condition_variable Event::m_EventAvailable;
 boost::mutex Event::m_Mutex;
 
+/**
+ * Constructor for the Event class
+ *
+ * @param callback The callback function for the new event object.
+ */
 Event::Event(const Event::Callback& callback)
        : m_Callback(callback)
 { }
 
+/**
+ * Waits for events using the specified timeout value and processes
+ * them.
+ *
+ * @param wait_until The wait timeout.
+ */
 void Event::ProcessEvents(const system_time& wait_until)
 {
        vector<Event> events;
 
+       assert(Application::IsMainThread());
+
        {
                boost::mutex::scoped_lock lock(m_Mutex);
 
@@ -59,6 +72,12 @@ void Event::ProcessEvents(const system_time& wait_until)
        }
 }
 
+/**
+ * Appends an event to the event queue. Events will be processed in FIFO
+ * order on the main thread.
+ *
+ * @param callback The callback function for the event.
+ */
 void Event::Post(const Event::Callback& callback)
 {
        if (Application::IsMainThread()) {

diff --git a/lib/base/logger.cpp b/lib/base/logger.cpp
index edd2a3d7cb4537b3a1792fb34f1d82accaf439a3..ff3c5bd4a415ca262dfd626be72b9c55f5306e23 100644 (file)
--- a/lib/base/logger.cpp
+++ b/lib/base/logger.cpp
@@ -126,6 +126,11 @@ void Logger::ForwardLogEntry(const LogEntry& entry)
                StreamLogger::ProcessLogEntry(std::cout, entry);
 }
 
+/**
+ * Converts a severity enum value to a string.
+ *
+ * @param severity The severity value.
+ */
 String Logger::SeverityToString(LogSeverity severity)
 {
        switch (severity) {
@@ -142,6 +147,11 @@ String Logger::SeverityToString(LogSeverity severity)
        }
 }
 
+/**
+ * Converts a string to a severity enum value.
+ *
+ * @param severity The severity.
+ */
 LogSeverity Logger::StringToSeverity(const String& severity)
 {
        if (severity == "debug")

diff --git a/lib/base/object.cpp b/lib/base/object.cpp
index da68ed0fadb60242f0bf39587e7521923e25ebcb..d0e221f4eb9d18935619ca90a15cb331f7711cf8 100644 (file)
--- a/lib/base/object.cpp
+++ b/lib/base/object.cpp
@@ -69,18 +69,31 @@ void Object::ClearHeldObjects(void)
        m_HeldObjects.clear();
 }
 
+/**
+ * Returns a reference-counted pointer to this object.
+ *
+ * @returns A shared_ptr object that points to this object
+ */
 Object::SharedPtrHolder Object::GetSelf(void)
 {
        return Object::SharedPtrHolder(shared_from_this());
 }
 
 #ifdef _DEBUG
+/**
+ * Retrieves the number of currently alive objects.
+ *
+ * @returns The number of alive objects.
+ */
 int Object::GetAliveObjects(void)
 {
        boost::mutex::scoped_lock lock(m_Mutex);
        return m_AliveObjects.size();
 }
 
+/**
+ * Dumps a memory histogram to the "dictionaries.dump" file.
+ */
 void Object::PrintMemoryProfile(void)
 {
        map<String, int> types;

diff --git a/lib/base/process.cpp b/lib/base/process.cpp
index 1a8e8aed89f13b50fe832003fad17017649db513..0686d0c79670fdedfee8207077cd98997c4e8a5e 100644 (file)
--- a/lib/base/process.cpp
+++ b/lib/base/process.cpp
@@ -212,6 +212,11 @@ bool Process::RunTask(void)
        return false;
 }
 
+/**
+ * Retrives the stdout file descriptor for the child process.
+ *
+ * @returns The stdout file descriptor.
+ */
 int Process::GetFD(void) const
 {
        return fileno(m_FP);

diff --git a/lib/base/socket.cpp b/lib/base/socket.cpp
index db8737fcca4c0cf5802383ba5d5997fbacb23746..dd6240e39ba1b798726f63737b1c8bd6298554ea 100644 (file)
--- a/lib/base/socket.cpp
+++ b/lib/base/socket.cpp
@@ -37,6 +37,9 @@ Socket::~Socket(void)
        CloseInternal(true);
 }
 
+/**
+ * Starts I/O processing for this socket.
+ */
 void Socket::Start(void)
 {
        assert(!m_ReadThread.joinable() && !m_WriteThread.joinable());
@@ -256,6 +259,10 @@ SocketException::SocketException(const String& message, int errorCode)
        SetMessage(msg.CStr());
 }
 
+/**
+ * Read thread procedure for sockets. This function waits until the
+ * socket is readable and processes inbound data.
+ */
 void Socket::ReadThreadProc(void)
 {
        boost::mutex::scoped_lock lock(m_SocketMutex);
@@ -310,6 +317,10 @@ void Socket::ReadThreadProc(void)
        }
 }
 
+/**
+ * Write thread procedure for sockets. This function waits until the socket
+ * is writable and processes outbound data.
+ */
 void Socket::WriteThreadProc(void)
 {
        boost::mutex::scoped_lock lock(m_SocketMutex);
@@ -358,16 +369,30 @@ void Socket::WriteThreadProc(void)
        }
 }
 
+/**
+ * Sets whether the socket is fully connected.
+ *
+ * @param connected Whether the socket is connected
+ */
 void Socket::SetConnected(bool connected)
 {
        m_Connected = connected;
 }
 
+/**
+ * Checks whether the socket is fully connected.
+ *
+ * @returns true if the socket is connected, false otherwise
+ */
 bool Socket::IsConnected(void) const
 {
        return m_Connected;
 }
 
+/**
+ * Checks whether an exception is available for this socket. Should be called
+ * by user-supplied handlers for the OnClosed signal.
+ */
 void Socket::CheckException(void)
 {
        if (m_Exception)

diff --git a/lib/base/tcpclient.cpp b/lib/base/tcpclient.cpp
index 6680763d7c9b567b089b3ac3356555daaed75d47..c21a438cd3615e5ca3ef352243d5513188e882de 100644 (file)
--- a/lib/base/tcpclient.cpp
+++ b/lib/base/tcpclient.cpp
@@ -102,6 +102,9 @@ void TcpClient::Connect(const String& node, const String& service)
                throw_exception(runtime_error("Could not create a suitable socket."));
 }
 
+/**
+ * Processes data that is available for this socket.
+ */
 void TcpClient::HandleWritable(void)
 {
        int rc;
@@ -180,6 +183,9 @@ void TcpClient::Write(const void *buffer, size_t count)
        m_SendQueue->Write(buffer, count);
 }
 
+/**
+ * Processes data that can be written for this socket.
+ */
 void TcpClient::HandleReadable(void)
 {
        if (!IsConnected()) {

diff --git a/lib/base/value.cpp b/lib/base/value.cpp
index 90446c8310b1869e654e624b51d586a941c6312f..f29be13c4d3120cd7c1108413c311c7bf473bd00 100644 (file)
--- a/lib/base/value.cpp
+++ b/lib/base/value.cpp
@@ -34,16 +34,31 @@ bool Value::IsEmpty(void) const
        return (m_Value.type() == typeid(boost::blank));
 }
 
+/**
+ * Checks whether the variant is scalar (i.e. not an object and not empty).
+ *
+ * @returns true if the variant is scalar, false otherwise.
+ */
 bool Value::IsScalar(void) const
 {
        return !IsEmpty() && !IsObject();
 }
 
+/**
+ * Checks whether the variant is a non-null object.
+ *
+ * @returns true if the variant is a non-null object, false otherwise.
+ */
 bool Value::IsObject(void) const
 {
        return !IsEmpty() && (m_Value.type() == typeid(Object::Ptr));
 }
 
+/**
+ * Converts a JSON object into a variant.
+ *
+ * @param json The JSON object.
+ */
 Value Value::FromJson(cJSON *json)
 {
        if (json->type == cJSON_Number)
@@ -62,6 +77,11 @@ Value Value::FromJson(cJSON *json)
                throw_exception(invalid_argument("Unsupported JSON type."));
 }
 
+/**
+ * Serializes a variant into a string.
+ *
+ * @returns A string representing this variant.
+ */
 String Value::Serialize(void) const
 {
        cJSON *json = ToJson();
@@ -82,6 +102,11 @@ String Value::Serialize(void) const
        return result;
 }
 
+/**
+ * Serializes the variant.
+ *
+ * @returns A JSON object representing this variant.
+ */
 cJSON *Value::ToJson(void) const
 {
        if (m_Value.type() == typeid(long)) {
@@ -105,6 +130,12 @@ cJSON *Value::ToJson(void) const
        }
 }
 
+/**
+ * Deserializes the string representation of a variant.
+ *
+ * @params jsonString A JSON string obtained from Value::Serialize
+ * @returns The newly deserialized variant.
+ */
 Value Value::Deserialize(const String& jsonString)
 {
        cJSON *json = cJSON_Parse(jsonString.CStr());