Working on C++ documentation (for doxygen)

Create doxygen documentation thus:
$ cd docs
$ doxygen ipaacaCpp.Doxyfile

.gitignore

 .DS_Store
 generatedsrc
 build
-docs
+docs/doxygen_generated
 lib
 test/lib
 report

docs/.gitignore

+doxygen_generated
+.*.sw?
+

ipaacalib/cpp/include/ipaaca/ipaaca-buffers.h

@@ -51,6 +51,7 @@ IPAACA_HEADER_EXPORT class RemotePushIUStore: public std::map<std::string, boost
 typedef std::set<std::string> LinkSet;
 typedef std::map<std::string, LinkSet> LinkMap;
 
+/// Container for IU links that gracefully returns the empty set if required
 IPAACA_HEADER_EXPORT class SmartLinkMap {//{{{
 	friend std::ostream& operator<<(std::ostream& os, const SmartLinkMap& obj);
 	friend class IUInterface;
@@ -70,6 +71,7 @@ IPAACA_HEADER_EXPORT class SmartLinkMap {//{{{
 
 IPAACA_MEMBER_VAR_EXPORT const LinkSet EMPTY_LINK_SET;
 
+/// Configuration object that can be passed to Buffer constructors.
 IPAACA_HEADER_EXPORT class BufferConfiguration//{{{
 {
 	protected:
@@ -88,6 +90,7 @@ IPAACA_HEADER_EXPORT class BufferConfiguration//{{{
 		IPAACA_HEADER_EXPORT inline BufferConfiguration& set_channel(const std::string& channel) { _channel = channel; return *this; }
 };//}}}
 
+/// Builder object for BufferConfiguration, not required for C++ [DEPRECATED]
 IPAACA_HEADER_EXPORT class BufferConfigurationBuilder: private BufferConfiguration//{{{
 {
 	public:
@@ -110,9 +113,11 @@ IPAACA_HEADER_EXPORT class BufferConfigurationBuilder: private BufferConfigurati
 
 };//}}}
 
+/// Type of user-space functions that can be registered on a Buffer to receive IU events.
 IPAACA_HEADER_EXPORT typedef boost::function<void (boost::shared_ptr<IUInterface>, IUEventType, bool)> IUEventHandlerFunction;
 
-IPAACA_HEADER_EXPORT class IUEventHandler {//{{{
+/// Internal handler type (wraps used-specified IUEventHandlerFunction)
+IPAACA_LOG_LEVEL_NONE, IPAACA_HEADER_EXPORT class IUEventHandler {//{{{
 	protected:
 		IPAACA_MEMBER_VAR_EXPORT IUEventHandlerFunction _function;
 		IPAACA_MEMBER_VAR_EXPORT IUEventType _event_mask;
@@ -131,6 +136,11 @@ IPAACA_HEADER_EXPORT class IUEventHandler {//{{{
 	typedef boost::shared_ptr<IUEventHandler> ptr;
 };//}}}
 
+/**
+ * \brief Buffer base class
+ *
+ * This class is never instantiated directly (use OutputBuffer and InputBuffer, respectively).
+ */
 IPAACA_HEADER_EXPORT class Buffer { //: public boost::enable_shared_from_this<Buffer> {//{{{
 	friend class IU;
 	friend class RemotePushIU;
@@ -173,6 +183,17 @@ IPAACA_HEADER_EXPORT class Buffer { //: public boost::enable_shared_from_this<Bu
 };
 //}}}
 
+/**
+ * \brief A buffer to which own IUs can be added to publish them
+ *
+ * Use OutputBuffer::create() to obtain a smart pointer to a new output buffer.
+ * 
+ * Use OutputBuffer::add() to add (= publish) an IU.
+ *
+ * Use OutputBuffer::remove() to remove (= retract) an IU.
+ *
+ * Use Buffer::register_handler() to register a handler that will respond to remote changes to own published IUs.
+ */
 IPAACA_HEADER_EXPORT class OutputBuffer: public Buffer { //, public boost::enable_shared_from_this<OutputBuffer>  {//{{{
 	friend class IU;
 	friend class RemotePushIU;
@@ -220,6 +241,15 @@ IPAACA_HEADER_EXPORT class OutputBuffer: public Buffer { //, public boost::enabl
 };
 //}}}
 
+/**
+ * \brief A buffer in which remote IUs (and changes to them) are received.
+ *
+ * Use InputBuffer::create() to obtain a smart pointer to a new input buffer.
+ *
+ * Set category interests (IU filter) via the different versions of create().
+ *
+ * Use Buffer::register_handler() to register a handler that will respond to relevant remote IUs.
+ */
 IPAACA_HEADER_EXPORT class InputBuffer: public Buffer { //, public boost::enable_shared_from_this<InputBuffer>  {//{{{
 	friend class IU;
 	friend class RemotePushIU;
@@ -268,6 +298,7 @@ IPAACA_HEADER_EXPORT class InputBuffer: public Buffer { //, public boost::enable
 		IPAACA_MEMBER_VAR_EXPORT bool triggerResend;
 
 	public:
+		/// Specify whether old, but previously unknown, IUs should be requested to be sent to the buffer over a hidden channel.
 		IPAACA_HEADER_EXPORT void set_resend(bool resendActive);
 		IPAACA_HEADER_EXPORT bool get_resend();
 		IPAACA_HEADER_EXPORT static boost::shared_ptr<InputBuffer> create(const BufferConfiguration& bufferconfiguration);
@@ -286,6 +317,7 @@ IPAACA_HEADER_EXPORT class InputBuffer: public Buffer { //, public boost::enable
 };
 //}}}
 
+/// Internal, transport-independent, representation of payload updates
 IPAACA_HEADER_EXPORT class IUPayloadUpdate {//{{{
 	public:
 		IPAACA_MEMBER_VAR_EXPORT std::string uid;
@@ -299,6 +331,7 @@ IPAACA_HEADER_EXPORT class IUPayloadUpdate {//{{{
 	typedef boost::shared_ptr<IUPayloadUpdate> ptr;
 };//}}}
 
+/// Internal, transport-independent, representation of link updates
 IPAACA_HEADER_EXPORT class IULinkUpdate {//{{{
 	public:
 		IPAACA_MEMBER_VAR_EXPORT std::string uid;

ipaacalib/cpp/include/ipaaca/ipaaca-definitions.h

@@ -31,6 +31,17 @@
  * Excellence Initiative.
  */
 
+/**
+ * \file   ipaaca-definitions.h
+ *
+ * \brief Header file for data and exception types and helper functions.
+ *
+ * Users should not include this file directly, but use ipaaca.h
+ *
+ * \author Ramin Yaghoubzadeh (ryaghoubzadeh@uni-bielefeld.de)
+ * \date   March, 2015
+ */
+
 #ifndef __ipaaca_definitions_h_INCLUDED__
 #define __ipaaca_definitions_h_INCLUDED__
 
@@ -43,7 +54,7 @@
 
 typedef uint32_t revision_t;
 
-/// Type of the IU event. Realized as an integer to enable bit masks for filters.
+/// Type of the IU event. Realized as an integer to enable bit masks for filters. One of: IU_ADDED, IU_COMMITTED, IU_DELETED, IU_RETRACTED, IU_UPDATED, IU_LINKSUPDATED, IU_MESSAGE
 typedef uint32_t IUEventType;
 #define IU_ADDED         1
 #define IU_COMMITTED     2
@@ -52,7 +63,7 @@ typedef uint32_t IUEventType;
 #define IU_UPDATED      16
 #define IU_LINKSUPDATED 32
 #define IU_MESSAGE      64
-/// Bit mask for receiving all events
+/// Bit mask for receiving all IU events  \see IUEventType
 #define IU_ALL_EVENTS  127
 
 /// Ipaaca (console) log levels
@@ -78,7 +89,7 @@ IPAACA_HEADER_EXPORT inline std::string iu_event_type_to_str(IUEventType type)
 	}
 }
 
-/// IU access mode: PUSH means that updates are broadcast; REMOTE means that reads are RPC calls; MESSAGE means a fire-and-forget message
+/// IU access mode: PUSH means that updates are broadcast; REMOTE means that reads are RPC calls (currently NOT implemented); MESSAGE means a fire-and-forget message
 IPAACA_HEADER_EXPORT enum IUAccessMode {
 	IU_ACCESS_PUSH,
 	IU_ACCESS_REMOTE,
@@ -88,8 +99,8 @@ IPAACA_HEADER_EXPORT enum IUAccessMode {
 /// generate a UUID as an ASCII string
 IPAACA_HEADER_EXPORT std::string generate_uuid_string();
 
-/*
- *  Exceptions and errors
+/**
+ * Exception with string description
  */
 IPAACA_HEADER_EXPORT class Exception: public std::exception//{{{
 {
@@ -251,10 +262,16 @@ IPAACA_HEADER_EXPORT class PayloadIteratorInvalidError: public Exception//{{{
 		}
 };//}}}
 
-/// Static library initialization
+/** \brief Static library initialization for backend
+ *
+ * This static class (singleton) is called once (explicitly or on-demand).
+ * Unless called manually, it is initialized when ipaaca is first used
+ * (i.e. the first Buffer is created).
+ */
 IPAACA_HEADER_EXPORT class Initializer
 {
 	public:
+		/// Explicitly initialize the backend.
 		IPAACA_HEADER_EXPORT static void initialize_ipaaca_rsb_if_needed();
 		IPAACA_HEADER_EXPORT static void initialize_updated_default_config();
 		IPAACA_HEADER_EXPORT static bool initialized();
@@ -265,6 +282,24 @@ IPAACA_HEADER_EXPORT class Initializer
 
 // in ipaaca-cmdline-parser.cc
 // additional misc classes ( Command line options )//{{{
+/** \brief Command line argument container for CommandLineParser
+ *
+ * Contains the results of argument parsing from CommandLineParser::parse()
+ *
+ * The parser is preconfigured to handle some standard options:
+ *
+ * Option                          | Function
+ * --------------------------------|------------------------------------------------------------------------------
+ * --help                          | Print list of available options
+ * --verbose                       | Set verbose flag
+ * --character-name <name>         | Set character name (legacy)
+ * --component-name <name>         | Set component name (legacy)
+ * --ipaaca-payload-type <type>    | Set default ipaaca payload type (default JSON, set STR for legacy protocol)
+ * --ipaaca-default-channel <name> | Set default channel name (default 'default')
+ * --ipaaca-enable-logging <level> | Set console log level, one of NONE, DEBUG, INFO, WARNING, ERROR, CRITICAL
+ * --rsb-enable-logging <level>    | Set rsb (transport) log level
+ *
+ */
 IPAACA_HEADER_EXPORT class CommandLineOptions {
 	public:
 		IPAACA_HEADER_EXPORT inline CommandLineOptions()
@@ -277,7 +312,9 @@ IPAACA_HEADER_EXPORT class CommandLineOptions {
 		IPAACA_MEMBER_VAR_EXPORT std::map<std::string, bool> param_set;
 	public:
 		IPAACA_HEADER_EXPORT void set_option(const std::string& name, bool expect, const char* optarg);
+		/// Get the option argument or default value (if the option expected an argument)
 		IPAACA_HEADER_EXPORT std::string get_param(const std::string& o);
+		/// Check whether option has been set
 		IPAACA_HEADER_EXPORT bool is_set(const std::string& o);
 		IPAACA_HEADER_EXPORT void dump();
 	public:
@@ -290,6 +327,23 @@ IPAACA_HEADER_EXPORT class CommandLineOptions {
 	typedef boost::shared_ptr<CommandLineOptions> ptr;
 };
 
+/**
+ * \brief Command line parser for ipaaca programs.
+ *
+ * The parser is preconfigured to handle some standard options:
+ *
+ * Option                          | Function
+ * --------------------------------|------------------------------------------------------------------------------
+ * --help                          | Print list of available options
+ * --verbose                       | Set verbose flag
+ * --character-name <name>         | Set character name (legacy)
+ * --component-name <name>         | Set component name (legacy)
+ * --ipaaca-payload-type <type>    | Set default ipaaca payload type (default JSON, set STR for legacy protocol)
+ * --ipaaca-default-channel <name> | Set default channel name (default 'default')
+ * --ipaaca-enable-logging <level> | Set console log level, one of NONE, DEBUG, INFO, WARNING, ERROR, CRITICAL
+ * --rsb-enable-logging <level>    | Set rsb (transport) log level
+ *
+ */
 class CommandLineParser {
 	protected:
 		IPAACA_MEMBER_VAR_EXPORT std::map<char, std::string> longopt; // letter->name
@@ -303,13 +357,26 @@ class CommandLineParser {
 		IPAACA_HEADER_EXPORT bool consume_library_option(const std::string& name, bool expect, const char* optarg);
 	public:
 		IPAACA_HEADER_EXPORT inline ~CommandLineParser() { }
+		/// Create a new parser object reference.
 		IPAACA_HEADER_EXPORT static inline boost::shared_ptr<CommandLineParser> create() {
 			return boost::shared_ptr<CommandLineParser>(new CommandLineParser());
 		}
 		IPAACA_HEADER_EXPORT void initialize_parser_defaults();
 		IPAACA_HEADER_EXPORT void dump_options();
+		/** \brief Add a user-defined option
+		 *
+		 * \param optname      The long option name, e.g. verbose for --verbose
+		 * \param shortn       The short option (or \0 for none)
+		 * \param expect_param Whether an argument is expected for the option
+		 * \param defaultv     The default string value (unused if expect_param is false)
+		 */
 		IPAACA_HEADER_EXPORT void add_option(const std::string& optname, char shortn, bool expect_param, const std::string& defaultv);
 		IPAACA_HEADER_EXPORT void ensure_defaults_in( CommandLineOptions::ptr clo );
+		/** \brief Parse argument list and return result.
+		 *
+		 * Parse argument list (e.g. from main()) with the parser, consuming the internal options.
+		 * The remaining options are packaged into a CommandLineOptions object.
+		 */
 		IPAACA_HEADER_EXPORT CommandLineOptions::ptr parse(int argc, char* const* argv);
 	typedef boost::shared_ptr<CommandLineParser> ptr;
 };

ipaacalib/cpp/include/ipaaca/ipaaca-forwards.h

@@ -31,6 +31,17 @@
  * Excellence Initiative.
  */
 
+/**
+ * \file   ipaaca-forwards.h
+ *
+ * \brief Header file for forward definitions.
+ *
+ * Users should not include this file directly, but use ipaaca.h
+ *
+ * \author Ramin Yaghoubzadeh (ryaghoubzadeh@uni-bielefeld.de)
+ * \date   March, 2015
+ */
+
 #ifndef __ipaaca_forwards_h_INCLUDED__
 #define __ipaaca_forwards_h_INCLUDED__
 

ipaacalib/cpp/include/ipaaca/ipaaca-internal.h

@@ -31,6 +31,24 @@
  * Excellence Initiative.
  */
 
+/**
+ * \file   ipaaca-internal.h
+ *
+ * \brief Header file for internal transport implementation (RSB).
+ *
+ * Users should not include this file directly, but use ipaaca.h
+ *
+ * \b Note: This file is only included during compilation of ipaaca,
+ * for regular use, the full internal API is not exposed.
+ * Users generally need never touch the internal transport layer.
+ *
+ * The file provides callback glue from RSB, and wire converters
+ * for the respective ipaaca classes.
+ *
+ * \author Ramin Yaghoubzadeh (ryaghoubzadeh@uni-bielefeld.de)
+ * \date   March, 2015
+ */
+
 #ifndef __ipaaca_internal_h_INCLUDED__
 #define __ipaaca_internal_h_INCLUDED__
 

ipaacalib/cpp/include/ipaaca/ipaaca-ius.h

@@ -31,6 +31,17 @@
  * Excellence Initiative.
  */
 
+/**
+ * \file   ipaaca-ius.h
+ *
+ * \brief Header file for IU (incremental unit) classes.
+ *
+ * Users should not include this file directly, but use ipaaca.h
+ *
+ * \author Ramin Yaghoubzadeh (ryaghoubzadeh@uni-bielefeld.de)
+ * \date   March, 2015
+ */
+
 #ifndef __ipaaca_ius_h_INCLUDED__
 #define __ipaaca_ius_h_INCLUDED__
 

ipaacalib/cpp/include/ipaaca/ipaaca-json.h

@@ -31,6 +31,17 @@
  * Excellence Initiative.
  */
 
+/**
+ * \file   ipaaca-json.h
+ *
+ * \brief Header file for JSON tests. [superfluous]
+ *
+ * Users should not include this file directly, but use ipaaca.h
+ *
+ * \author Ramin Yaghoubzadeh (ryaghoubzadeh@uni-bielefeld.de)
+ * \date   March, 2015
+ */
+
 #ifndef __ipaaca_json_H__
 #define __ipaaca_json_H__