From: Gunnar Beutner Date: Mon, 17 Sep 2012 11:35:55 +0000 (+0200) Subject: Updated doxygen documentation. X-Git-Tag: v0.0.1~80^2~16 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=fee4246f5512343ce7d6f9faea0412295f9be3fa;p=icinga2 Updated doxygen documentation. --- diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 914126ca6..90be6a95b 100644 --- a/docs/Doxyfile.in +++ b/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 diff --git a/lib/base/component.h b/lib/base/component.h index ce6f6d3b0..d87335f4b 100644 --- a/lib/base/component.h +++ b/lib/base/component.h @@ -23,6 +23,11 @@ namespace icinga { +/** + * Interface for application extensions. + * + * @ingroup base + */ class I2_BASE_API IComponent : public Object { public: diff --git a/lib/base/dictionary.cpp b/lib/base/dictionary.cpp index e9442b183..7bf487028 100644 --- a/lib/base/dictionary.cpp +++ b/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. */ diff --git a/lib/base/dynamicobject.h b/lib/base/dynamicobject.h index 6ff8b77ac..42619e29b 100644 --- a/lib/base/dynamicobject.h +++ b/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: diff --git a/lib/base/event.h b/lib/base/event.h index 06ebe1f32..8a64b2ed6 100644 --- a/lib/base/event.h +++ b/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: diff --git a/lib/base/fifo.cpp b/lib/base/fifo.cpp index 755bf1768..5f9e59bfd 100644 --- a/lib/base/fifo.cpp +++ b/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. */ diff --git a/lib/base/ioqueue.h b/lib/base/ioqueue.h index 3ec17185c..842e9461f 100644 --- a/lib/base/ioqueue.h +++ b/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; diff --git a/lib/base/logger.cpp b/lib/base/logger.cpp index ff3c5bd4a..9d9f003c7 100644 --- a/lib/base/logger.cpp +++ b/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) diff --git a/lib/base/logger.h b/lib/base/logger.h index 49a61863d..1b642fb59 100644 --- a/lib/base/logger.h +++ b/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: diff --git a/lib/base/netstring.cpp b/lib/base/netstring.cpp index ff23cd275..3519580ca 100644 --- a/lib/base/netstring.cpp +++ b/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) diff --git a/lib/base/process.h b/lib/base/process.h index 36fb486a2..10fa8d33d 100644 --- a/lib/base/process.h +++ b/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 { public: diff --git a/lib/base/qstring.cpp b/lib/base/qstring.cpp index a979002a7..03f0a3cf5 100644 --- a/lib/base/qstring.cpp +++ b/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; diff --git a/lib/base/qstring.h b/lib/base/qstring.h index c76fcf6a2..b5fe1c87c 100644 --- a/lib/base/qstring.h +++ b/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 diff --git a/lib/base/ringbuffer.h b/lib/base/ringbuffer.h index fc85a8cbe..217788246 100644 --- a/lib/base/ringbuffer.h +++ b/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: diff --git a/lib/base/scriptfunction.h b/lib/base/scriptfunction.h index 94bbc7138..86a459415 100644 --- a/lib/base/scriptfunction.h +++ b/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: diff --git a/lib/base/scripttask.h b/lib/base/scripttask.h index 7f55910d3..71d5912cf 100644 --- a/lib/base/scripttask.h +++ b/lib/base/scripttask.h @@ -23,6 +23,11 @@ namespace icinga { +/** + * A script task. + * + * @ingroup base + */ class I2_BASE_API ScriptTask : public AsyncTask { public: diff --git a/lib/base/streamlogger.cpp b/lib/base/streamlogger.cpp index c35da60da..758484a14 100644 --- a/lib/base/streamlogger.cpp +++ b/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) diff --git a/lib/base/streamlogger.h b/lib/base/streamlogger.h index c06a4777c..541e5869d 100644 --- a/lib/base/streamlogger.h +++ b/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 { diff --git a/lib/base/sysloglogger.cpp b/lib/base/sysloglogger.cpp index 8b66997b9..838d461f1 100644 --- a/lib/base/sysloglogger.cpp +++ b/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 diff --git a/lib/base/sysloglogger.h b/lib/base/sysloglogger.h index 19fa6d02e..291658d70 100644 --- a/lib/base/sysloglogger.h +++ b/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 { diff --git a/lib/base/tcpserver.h b/lib/base/tcpserver.h index 3ac03f08f..27aa3e34c 100644 --- a/lib/base/tcpserver.h +++ b/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); diff --git a/lib/base/utility.cpp b/lib/base/utility.cpp index 710655d90..b64e6b145 100644 --- a/lib/base/utility.cpp +++ b/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 *) { diff --git a/lib/base/utility.h b/lib/base/utility.h index 11687691b..7ff9a2ab2 100644 --- a/lib/base/utility.h +++ b/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); diff --git a/lib/base/value.cpp b/lib/base/value.cpp index f29be13c4..f74bb7f3a 100644 --- a/lib/base/value.cpp +++ b/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) diff --git a/lib/config/i2-config.h b/lib/config/i2-config.h index ce4cd4e69..868b7e66e 100644 --- a/lib/config/i2-config.h +++ b/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 diff --git a/lib/icinga/cib.h b/lib/icinga/cib.h index f9353cda7..fc4bc5392 100644 --- a/lib/icinga/cib.h +++ b/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: diff --git a/lib/icinga/host.h b/lib/icinga/host.h index 1c130befe..26d06bac0 100644 --- a/lib/icinga/host.h +++ b/lib/icinga/host.h @@ -23,6 +23,11 @@ namespace icinga { +/** + * An Icinga host. + * + * @ingroup icinga + */ class I2_ICINGA_API Host : public DynamicObject { public: diff --git a/lib/icinga/hostgroup.h b/lib/icinga/hostgroup.h index 29303da08..b0e854103 100644 --- a/lib/icinga/hostgroup.h +++ b/lib/icinga/hostgroup.h @@ -23,6 +23,11 @@ namespace icinga { +/** + * An Icinga host group. + * + * @ingroup icinga + */ class I2_ICINGA_API HostGroup : public DynamicObject { public: diff --git a/lib/icinga/i2-icinga.h b/lib/icinga/i2-icinga.h index 6e4ec6c81..d5f8e2766 100644 --- a/lib/icinga/i2-icinga.h +++ b/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 diff --git a/lib/icinga/macroprocessor.h b/lib/icinga/macroprocessor.h index 3f430f7ab..e015e9e82 100644 --- a/lib/icinga/macroprocessor.h +++ b/lib/icinga/macroprocessor.h @@ -23,6 +23,11 @@ namespace icinga { +/** + * Resolves macros. + * + * @ingroup icinga + */ class I2_ICINGA_API MacroProcessor { public: diff --git a/lib/icinga/nagioschecktask.h b/lib/icinga/nagioschecktask.h index ce6e575cf..c23cb1476 100644 --- a/lib/icinga/nagioschecktask.h +++ b/lib/icinga/nagioschecktask.h @@ -23,6 +23,11 @@ namespace icinga { +/** + * Implements Nagios(TM)-style checks. + * + * @ingroup icinga + */ class I2_ICINGA_API NagiosCheckTask { public: diff --git a/lib/icinga/nullchecktask.h b/lib/icinga/nullchecktask.h index d9a0a59ad..13b268180 100644 --- a/lib/icinga/nullchecktask.h +++ b/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: diff --git a/lib/icinga/service.h b/lib/icinga/service.h index 92c22ea18..8391cd6b6 100644 --- a/lib/icinga/service.h +++ b/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: diff --git a/lib/icinga/servicegroup.h b/lib/icinga/servicegroup.h index 9552e29a2..48f2c4f6e 100644 --- a/lib/icinga/servicegroup.h +++ b/lib/icinga/servicegroup.h @@ -23,6 +23,11 @@ namespace icinga { +/** + * An Icinga service group. + * + * @ingroup icinga + */ class I2_ICINGA_API ServiceGroup : public DynamicObject { public: diff --git a/lib/icinga/servicestatechangemessage.h b/lib/icinga/servicestatechangemessage.h index 575855c2b..be8733db2 100644 --- a/lib/icinga/servicestatechangemessage.h +++ b/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: diff --git a/lib/remoting/endpoint.h b/lib/remoting/endpoint.h index b03778253..bfa6a9236 100644 --- a/lib/remoting/endpoint.h +++ b/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 { diff --git a/lib/remoting/endpointmanager.h b/lib/remoting/endpointmanager.h index 9796dd8e5..878cf368e 100644 --- a/lib/remoting/endpointmanager.h +++ b/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 callback); -// Iterator Begin(void); -// Iterator End(void); - boost::signal OnNewEndpoint; private: @@ -78,7 +74,7 @@ private: /** * Information about a pending API request. * - * @ingroup icinga + * @ingroup remoting */ struct I2_REMOTING_API PendingRequest { diff --git a/lib/remoting/i2-remoting.h b/lib/remoting/i2-remoting.h index a54d94350..132a2314b 100644 --- a/lib/remoting/i2-remoting.h +++ b/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 diff --git a/lib/remoting/messagepart.cpp b/lib/remoting/messagepart.cpp index 7c04a951a..f5a5280da 100644 --- a/lib/remoting/messagepart.cpp +++ b/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 diff --git a/lib/remoting/messagepart.h b/lib/remoting/messagepart.h index defff4357..f7a4f819d 100644 --- a/lib/remoting/messagepart.h +++ b/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