diff --git a/lib/base/asynctask.h b/lib/base/asynctask.h index 66d438be3..e05c1c343 100644 --- a/lib/base/asynctask.h +++ b/lib/base/asynctask.h @@ -35,6 +35,9 @@ public: typedef shared_ptr > Ptr; typedef weak_ptr > WeakPtr; + /** + * A completion callback for an AsyncTask. + */ typedef function&)> CompletionCallback; /** diff --git a/lib/base/component.h b/lib/base/component.h index d87335f4b..f1c92bf22 100644 --- a/lib/base/component.h +++ b/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); diff --git a/lib/base/dictionary.cpp b/lib/base/dictionary.cpp index 7bf487028..9306b3fbc 100644 --- a/lib/base/dictionary.cpp +++ b/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& 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& b) { return a < b.first; diff --git a/lib/base/dictionary.h b/lib/base/dictionary.h index 43dbc61c9..fc5065eee 100644 --- a/lib/base/dictionary.h +++ b/lib/base/dictionary.h @@ -34,6 +34,9 @@ public: typedef shared_ptr Ptr; typedef weak_ptr WeakPtr; + /** + * An iterator that can be used to iterate over dictionary elements. + */ typedef map::iterator Iterator; Value Get(const char *key) const; @@ -56,7 +59,7 @@ public: cJSON *ToJson(void) const; private: - map m_Data; + map m_Data; /**< The data for the dictionary. */ }; inline Dictionary::Iterator range_begin(Dictionary::Ptr x) diff --git a/lib/base/dynamicobject.h b/lib/base/dynamicobject.h index e2e465263..364210529 100644 --- a/lib/base/dynamicobject.h +++ b/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 shared_ptr DynamicObjectFactory(const Dictionary::Ptr& serializedUpdate) { diff --git a/lib/base/exception.h b/lib/base/exception.h index 1e5bd19c5..b4ead45a8 100644 --- a/lib/base/exception.h +++ b/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 { diff --git a/lib/base/netstring.h b/lib/base/netstring.h index 3688ae33c..d32616e4c 100644 --- a/lib/base/netstring.h +++ b/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 */ diff --git a/lib/base/object.h b/lib/base/object.h index c58a877cf..038819ac7 100644 --- a/lib/base/object.h +++ b/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 operator shared_ptr(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 operator weak_ptr(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 vector m_HeldObjects; + static boost::mutex m_Mutex; /**< Mutex which protects static members + of the Object class. */ + static vector m_HeldObjects; /**< Currently held + objects. */ #ifdef _DEBUG - static set m_AliveObjects; + static set m_AliveObjects; /**< Currently alive objects - + for debugging purposes. */ #endif /* _DEBUG */ }; /** * Compares a weak pointer with a raw pointer. + * + * @ingroup base */ template 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) { } /** diff --git a/lib/config/configcompiler.cpp b/lib/config/configcompiler.cpp index bf80ce0be..386a92012 100644 --- a/lib/config/configcompiler.cpp +++ b/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(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 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 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 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 ConfigCompiler::CompileFile(const String& path) { ifstream stream; @@ -82,18 +136,39 @@ vector ConfigCompiler::CompileFile(const String& path) return CompileStream(path, &stream); } -vector 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 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 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); diff --git a/lib/config/configcompiler.h b/lib/config/configcompiler.h index ef4c572a9..d214e446e 100644 --- a/lib/config/configcompiler.h +++ b/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 CompileStream(const String& path, istream *stream); + static vector CompileStream(const String& path, + istream *stream); static vector CompileFile(const String& path); - static vector CompileText(const String& path, const String& text); + static vector CompileText(const String& path, + const String& text); static vector HandleFileInclude(const String& include); diff --git a/lib/config/configitem.cpp b/lib/config/configitem.cpp index ff57bf966..927ef341d 100644 --- a/lib/config/configitem.cpp +++ b/lib/config/configitem.cpp @@ -25,6 +25,15 @@ ConfigItem::ItemMap ConfigItem::m_Items; boost::signal ConfigItem::OnCommitted; boost::signal 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& 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 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; diff --git a/lib/config/configitem.h b/lib/config/configitem.h index 0c1307dca..8bce29493 100644 --- a/lib/config/configitem.h +++ b/lib/config/configitem.h @@ -24,8 +24,8 @@ namespace icinga { /** - * A configuration item. Can be used to create a configuration object at - * runtime. + * A configuration item. Non-abstract configuration items can be used to + * 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 OnCommitted; static boost::signal OnRemoved; @@ -60,17 +61,20 @@ public: private: void CalculateProperties(const Dictionary::Ptr& dictionary) const; - String m_Type; - String m_Name; + String m_Type; /**< The object type. */ + String m_Name; /**< The name. */ ExpressionList::Ptr m_ExpressionList; - vector m_Parents; - DebugInfo m_DebugInfo; + vector m_Parents; /**< The names of parent configuration + items. */ + DebugInfo m_DebugInfo; /**< Debug information. */ - DynamicObject::WeakPtr m_DynamicObject; + DynamicObject::WeakPtr m_DynamicObject; /**< The instantiated version + of this configuration + item */ typedef map, ConfigItem::Ptr> ItemMap; - static ItemMap m_Items; + static ItemMap m_Items; /**< All registered configuration items. */ }; } diff --git a/lib/config/configitembuilder.cpp b/lib/config/configitembuilder.cpp index 36e3671b0..70963bcec 100644 --- a/lib/config/configitembuilder.cpp +++ b/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(m_Type, m_Name, exprl, m_Parents, m_DebugInfo); + return boost::make_shared(m_Type, m_Name, exprl, m_Parents, + m_DebugInfo); } diff --git a/lib/config/configitembuilder.h b/lib/config/configitembuilder.h index 9bd887b60..a857c3f11 100644 --- a/lib/config/configitembuilder.h +++ b/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_Name; - bool m_Local; - bool m_Abstract; - vector m_Parents; - ExpressionList::Ptr m_ExpressionList; - DebugInfo m_DebugInfo; + String m_Type; /**< The object type. */ + String m_Name; /**< The name. */ + bool m_Local; /**< Whether the item is local. */ + bool m_Abstract; /**< Whether the item is abstract. */ + vector m_Parents; /**< The names of parent configuration + items. */ + ExpressionList::Ptr m_ExpressionList; /**< Expressions for this item. */ + DebugInfo m_DebugInfo; /**< Debug information. */ }; } diff --git a/lib/config/debuginfo.h b/lib/config/debuginfo.h index 984c378aa..7918f70ad 100644 --- a/lib/config/debuginfo.h +++ b/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 << ": " diff --git a/lib/config/expression.cpp b/lib/config/expression.cpp index 66b37e2ab..fe88d2536 100644 --- a/lib/config/expression.cpp +++ b/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())); } diff --git a/lib/config/expression.h b/lib/config/expression.h index 533b0979f..378f1c94b 100644 --- a/lib/config/expression.h +++ b/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; diff --git a/lib/config/expressionlist.cpp b/lib/config/expressionlist.cpp index a22be1d61..54782f130 100644 --- a/lib/config/expressionlist.cpp +++ b/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) { diff --git a/lib/config/i2-config.h b/lib/config/i2-config.h index 868b7e66e..c378e182d 100644 --- a/lib/config/i2-config.h +++ b/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. */