C++: improved documentation

Also renamed some functions (preserving old names as deprecated aliases)

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

@@ -39,11 +39,11 @@
 #endif
 
 
-/// store for (local) IUs. TODO Stores need to be unified more
+/// Store for local IUs (used in OutputBuffer)
 IPAACA_HEADER_EXPORT class IUStore: public std::map<std::string, boost::shared_ptr<IU> >
 {
 };
-/// store for RemotePushIUs. TODO Stores need to be unified more
+/// Store for RemotePushIUs (used in InputBuffer)
 IPAACA_HEADER_EXPORT class RemotePushIUStore: public std::map<std::string, boost::shared_ptr<RemotePushIU> > // TODO genericize to all remote IU types
 {
 };
@@ -64,6 +64,7 @@ IPAACA_HEADER_EXPORT class SmartLinkMap {//{{{
 
 	protected:
 		IPAACA_MEMBER_VAR_EXPORT LinkMap _links;
+		/// The empty link set is returned if undefined links are read for an IU.
 		IPAACA_MEMBER_VAR_EXPORT static LinkSet empty_link_set;
 		IPAACA_HEADER_EXPORT void _add_and_remove_links(const LinkMap& add, const LinkMap& remove);
 		IPAACA_HEADER_EXPORT void _replace_links(const LinkMap& links);
@@ -185,7 +186,7 @@ IPAACA_HEADER_EXPORT class Buffer { //: public boost::enable_shared_from_this<Bu
 		IPAACA_HEADER_EXPORT inline const std::string& unique_name() { return _unique_name; }
 		/// This version of register_handler takes a set of several category interests instead of just one.
 		IPAACA_HEADER_EXPORT void register_handler(IUEventHandlerFunction function, IUEventType event_mask, const std::set<std::string>& categories);
-		/** \brief Register a user-specified handler for IU events.
+		/** \brief Register a user-specified handler for IU events. Unless specified, it triggers for all event types for all category interests of the buffer.
 		 *
 		 * \param function A function [object] that can be converted to #IUEventHandlerFunction (examples below)
 		 * \param event_mask Which event types to relay to the user (default: all)
@@ -195,7 +196,7 @@ IPAACA_HEADER_EXPORT class Buffer { //: public boost::enable_shared_from_this<Bu
 		 *
 		 * Adding a plain function as a handler:<br/>
 		 *     <pre>
-		 *     void global_iu_handler(IUInterface::ptr iu, IUEventType type, bool local) { ... }
+		 *     void global_iu_handler(IUInterface::ptr iu, IUEventType type, bool local) { do_something(); }
 		 *     ...
 		 *     int main() {
 		 *         OutputBuffer::ptr outbuf = OutputBuffer::create("mybufname");
@@ -208,7 +209,7 @@ IPAACA_HEADER_EXPORT class Buffer { //: public boost::enable_shared_from_this<Bu
 		 *     <pre>
 		 *     class MyClass {
 		 *         protected:
-		 *             void my_internal_iu_handler(IUInterface::ptr iu, IUEventType type, bool local) { ... }
+		 *             void my_internal_iu_handler(IUInterface::ptr iu, #IUEventType type, bool local) { do_something(); }
 		 *             InputBuffer::ptr inbuf;
 		 *         public:
 		 *             MyClass() {
@@ -218,6 +219,13 @@ IPAACA_HEADER_EXPORT class Buffer { //: public boost::enable_shared_from_this<Bu
 		 *     };
 		 *     </pre>
 		 *
+		 * Adding a lambda function as a handler (C++11):<br/>
+		 *     <pre>
+		 *     inbuf->register_handler([](IUInterface::ptr iu, #IUEventType event_type, bool local) {
+		 *         do_something();
+		 *     });
+		 *     </pre>
+		 *
 		 */
 		IPAACA_HEADER_EXPORT void register_handler(IUEventHandlerFunction function, IUEventType event_mask = IU_ALL_EVENTS, const std::string& category="");
 		//_IPAACA_ABSTRACT_ virtual void add(boost::shared_ptr<IUInterface> iu) = 0;

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

@@ -125,6 +125,7 @@ IPAACA_HEADER_EXPORT class Abort: public std::exception//{{{
 		}
 };//}}}
 
+/// IU was not found in a buffer
 IPAACA_HEADER_EXPORT class IUNotFoundError: public Exception//{{{
 {
 	public:
@@ -133,6 +134,7 @@ IPAACA_HEADER_EXPORT class IUNotFoundError: public Exception//{{{
 			_description = "IUNotFoundError";
 		}
 };//}}}
+/// IU was already published
 IPAACA_HEADER_EXPORT class IUPublishedError: public Exception//{{{
 {
 	public:
@@ -141,6 +143,7 @@ IPAACA_HEADER_EXPORT class IUPublishedError: public Exception//{{{
 			_description = "IUPublishedError";
 		}
 };//}}}
+/// IU had already been committed to
 IPAACA_HEADER_EXPORT class IUCommittedError: public Exception//{{{
 {
 	public:
@@ -149,6 +152,7 @@ IPAACA_HEADER_EXPORT class IUCommittedError: public Exception//{{{
 			_description = "IUCommittedError";
 		}
 };//}}}
+/// Remote IU update failed because it had been modified in the mean time
 IPAACA_HEADER_EXPORT class IUUpdateFailedError: public Exception//{{{
 {
 	public:
@@ -157,6 +161,7 @@ IPAACA_HEADER_EXPORT class IUUpdateFailedError: public Exception//{{{
 			_description = "IUUpdateFailedError";
 		}
 };//}}}
+/// Requested resend of old IU due to malformed channel specification
 IPAACA_HEADER_EXPORT class IUResendRequestFailedError: public Exception//{{{
 {
 	public:
@@ -165,6 +170,7 @@ IPAACA_HEADER_EXPORT class IUResendRequestFailedError: public Exception//{{{
 			_description = "IUResendRequestFailedError";
 		}
 };//}}}
+/// Write operation failed because IU had been set read-only
 IPAACA_HEADER_EXPORT class IUReadOnlyError: public Exception//{{{
 {
 	public:
@@ -173,6 +179,7 @@ IPAACA_HEADER_EXPORT class IUReadOnlyError: public Exception//{{{
 			_description = "IUReadOnlyError";
 		}
 };//}}}
+/// Buffer::add() failed because the IU had been previously placed in another buffer
 IPAACA_HEADER_EXPORT class IUAlreadyInABufferError: public Exception//{{{
 {
 	public:
@@ -181,6 +188,7 @@ IPAACA_HEADER_EXPORT class IUAlreadyInABufferError: public Exception//{{{
 			_description = "IUAlreadyInABufferError";
 		}
 };//}}}
+/// A request was made that is only valid for an already published IU
 IPAACA_HEADER_EXPORT class IUUnpublishedError: public Exception//{{{
 {
 	public:
@@ -189,6 +197,7 @@ IPAACA_HEADER_EXPORT class IUUnpublishedError: public Exception//{{{
 			_description = "IUUnpublishedError";
 		}
 };//}}}
+/// IU had already been allocated a UID
 IPAACA_HEADER_EXPORT class IUAlreadyHasAnUIDError: public Exception//{{{
 {
 	public:
@@ -197,6 +206,7 @@ IPAACA_HEADER_EXPORT class IUAlreadyHasAnUIDError: public Exception//{{{
 			_description = "IUAlreadyHasAnUIDError";
 		}
 };//}}}
+/// IU had already been allocated an owner name
 IPAACA_HEADER_EXPORT class IUAlreadyHasAnOwnerNameError: public Exception//{{{
 {
 	public:
@@ -205,6 +215,7 @@ IPAACA_HEADER_EXPORT class IUAlreadyHasAnOwnerNameError: public Exception//{{{
 			_description = "IUAlreadyHasAnOwnerNameError";
 		}
 };//}}}
+/// UID generation failed (Windows only)
 IPAACA_HEADER_EXPORT class UUIDGenerationError: public Exception//{{{
 {
 	public:
@@ -213,6 +224,7 @@ IPAACA_HEADER_EXPORT class UUIDGenerationError: public Exception//{{{
 			_description = "UUIDGenerationError";
 		}
 };//}}}
+/// Not implemented (e.g. invalid request parameters via backend)
 IPAACA_HEADER_EXPORT class NotImplementedError: public Exception//{{{
 {
 	public:
@@ -221,6 +233,7 @@ IPAACA_HEADER_EXPORT class NotImplementedError: public Exception//{{{
 			_description = "NotImplementedError";
 		}
 };//}}}
+/// PayloadEntryProxy requested type conversion failed (including lenient interpretation)
 IPAACA_HEADER_EXPORT class PayloadTypeConversionError: public Exception//{{{
 {
 	public:
@@ -229,6 +242,7 @@ IPAACA_HEADER_EXPORT class PayloadTypeConversionError: public Exception//{{{
 			_description = "PayloadTypeConversionError";
 		}
 };//}}}
+/// PayloadEntryProxy was addressed as list when not a list or as map when not a map
 IPAACA_HEADER_EXPORT class PayloadAddressingError: public Exception//{{{
 {
 	public:
@@ -237,6 +251,7 @@ IPAACA_HEADER_EXPORT class PayloadAddressingError: public Exception//{{{
 			_description = "PayloadAddressingError";
 		}
 };//}}}
+/// Malformed json was received for a Payload
 IPAACA_HEADER_EXPORT class JsonParsingError: public Exception//{{{
 {
 	public:
@@ -245,6 +260,7 @@ IPAACA_HEADER_EXPORT class JsonParsingError: public Exception//{{{
 			_description = "JsonParsingError";
 		}
 };//}}}
+/// PayloadEntryProxy invalidated (unused)
 IPAACA_HEADER_EXPORT class PayloadEntryProxyInvalidatedError: public Exception//{{{
 {
 	public:
@@ -253,6 +269,7 @@ IPAACA_HEADER_EXPORT class PayloadEntryProxyInvalidatedError: public Exception//
 			_description = "PayloadEntryProxyInvalidatedError";
 		}
 };//}}}
+/// Iterator over Payload entries was invalidated by an intermediate IU update operation
 IPAACA_HEADER_EXPORT class PayloadIteratorInvalidError: public Exception//{{{
 {
 	public:
@@ -271,12 +288,15 @@ IPAACA_HEADER_EXPORT class PayloadIteratorInvalidError: public Exception//{{{
 IPAACA_HEADER_EXPORT class Initializer
 {
 	public:
-		/// Explicitly initialize the backend.
+		/// Initialize the backend [DEPRECATED] (old name, use initialize_backend() instead)
+		[[deprecated("Use initialize_backend() instead")]]
 		IPAACA_HEADER_EXPORT static void initialize_ipaaca_rsb_if_needed();
-		IPAACA_HEADER_EXPORT static void initialize_updated_default_config();
+		/// Explicitly initialize the backend. No effect if already initialized. Automatically called during first Buffer construction.
+		IPAACA_HEADER_EXPORT static void initialize_backend();
 		IPAACA_HEADER_EXPORT static bool initialized();
 		IPAACA_HEADER_EXPORT static void dump_current_default_config();
 	protected:
+		IPAACA_HEADER_EXPORT static void auto_configure_rsb();
 		IPAACA_MEMBER_VAR_EXPORT static bool _initialized;
 };
 
@@ -355,6 +375,7 @@ class CommandLineParser {
 		IPAACA_HEADER_EXPORT CommandLineParser();
 		IPAACA_MEMBER_VAR_EXPORT bool library_options_handled;
 		IPAACA_HEADER_EXPORT bool consume_library_option(const std::string& name, bool expect, const char* optarg);
+		IPAACA_HEADER_EXPORT void ensure_defaults_in( CommandLineOptions::ptr clo );
 	public:
 		IPAACA_HEADER_EXPORT inline ~CommandLineParser() { }
 		/// Create a new parser object reference.
@@ -371,7 +392,6 @@ class CommandLineParser {
 		 * \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.

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

@@ -118,7 +118,7 @@ IPAACA_HEADER_EXPORT template<> void pack_into_json_value(rapidjson::Value&, rap
 
 // FIXME TODO locking / invalidating proxy on first write of a payload entry
 
-/// Single payload entry wrapping a rapidjson::Document with some conversion glue. Also handles copy-on-write Document cloning.
+/// Single payload entry wrapping a rapidjson::Document with some conversion glue. Also handles copy-on-write Document cloning. <b>Internal type</b> - users generally do not see this.
 IPAACA_HEADER_EXPORT class PayloadDocumentEntry//{{{
 {
 	friend std::ostream& operator<<(std::ostream& os, std::shared_ptr<PayloadDocumentEntry> entry);
@@ -185,8 +185,6 @@ IPAACA_HEADER_EXPORT class Payload//{{{
 		IPAACA_HEADER_EXPORT PayloadEntryProxy operator[](const std::string& key);
 		/// Legacy / convenience function: interpret the payload map as a map string->string (casting all entries to string)
 		IPAACA_HEADER_EXPORT operator std::map<std::string, std::string>();
-		/// set or overwrite a single payload entry with a PayloadDocumentEntry object (typically \b not called by users - use PayloadEntryProxy::operator=() instead).
-		IPAACA_HEADER_EXPORT inline void set(const std::string& k, PayloadDocumentEntry::ptr entry) { _internal_set(k, entry); }
 		/// remove a single payload entry
 		IPAACA_HEADER_EXPORT inline void remove(const std::string& k) { _internal_remove(k); }
 		// FIXME: json: these two must support a bunch of standard types, not [only] json (users touch them)
@@ -197,6 +195,8 @@ IPAACA_HEADER_EXPORT class Payload//{{{
 		/// Legacy / convenience function: set the whole payload map from a map string->string (all JSON types are also set as string, no interpretation)
 		IPAACA_HEADER_EXPORT void set(const std::map<std::string, std::string>& all_elems);
 	protected:
+		/// set or overwrite a single payload entry with a PayloadDocumentEntry object (used by PayloadEntryProxy::operator=()).
+		IPAACA_HEADER_EXPORT inline void set(const std::string& k, PayloadDocumentEntry::ptr entry) { _internal_set(k, entry); }
 		IPAACA_HEADER_EXPORT PayloadDocumentEntry::ptr get_entry(const std::string& k); // json, changed str to proxy here, too
 	public:
 		[[deprecated("Use operator[] and operator std::string() instead")]]
@@ -205,7 +205,6 @@ IPAACA_HEADER_EXPORT class Payload//{{{
 	protected:
 		IPAACA_MEMBER_VAR_EXPORT unsigned long internal_revision;
 		IPAACA_MEMBER_VAR_EXPORT inline void mark_revision_change() { internal_revision++; }
-	public:
 		IPAACA_HEADER_EXPORT inline bool revision_changed(unsigned long reference_revision) { return internal_revision != reference_revision; }
 	public:
 		/// obtain a standard iterator marking the first entry in the payload
@@ -473,13 +472,17 @@ IPAACA_HEADER_EXPORT class PayloadEntryProxy//{{{
 			return result;
 		}
 		// FIXME why are these needed again?
+		/// [DECPRECATED] use normal type conversion syntax instead
 		[[deprecated("Use operator std::string() instead (i.e. explicit or implicit cast)")]]
 		IPAACA_HEADER_EXPORT std::string to_str();
 		//long to_int() { return operator long(); ;
+		/// [DECPRECATED] use normal type conversion syntax instead
 		[[deprecated("Use operator long() instead (i.e. explicit or implicit cast)")]]
 		IPAACA_HEADER_EXPORT long to_long();
+		/// [DECPRECATED] use normal type conversion syntax instead
 		[[deprecated("Use operator double() instead (i.e. explicit or implicit cast)")]]
 		IPAACA_HEADER_EXPORT double to_float();
+		/// [DECPRECATED] use normal type conversion syntax instead
 		[[deprecated("Use operator bool() instead (i.e. explicit or implicit cast)")]]
 		IPAACA_HEADER_EXPORT bool to_bool();
 		// getters  (not needed since conversions are enough?)

ipaacalib/cpp/src/ipaaca-buffers.cc

@@ -302,7 +302,7 @@ IPAACA_EXPORT void OutputBuffer::_initialize_server()
 }
 IPAACA_EXPORT OutputBuffer::ptr OutputBuffer::create(const std::string& basename)
 {
-	Initializer::initialize_ipaaca_rsb_if_needed();
+	Initializer::initialize_backend();
 	return OutputBuffer::ptr(new OutputBuffer(basename));
 }
 IPAACA_EXPORT IUInterface::ptr OutputBuffer::get(const std::string& iu_uid)
@@ -532,37 +532,37 @@ IPAACA_EXPORT InputBuffer::InputBuffer(const std::string& basename, const std::s
 
 IPAACA_EXPORT InputBuffer::ptr InputBuffer::create(const BufferConfiguration& bufferconfiguration)
 {
-	Initializer::initialize_ipaaca_rsb_if_needed();
+	Initializer::initialize_backend();
 	return InputBuffer::ptr(new InputBuffer(bufferconfiguration));
 }
 IPAACA_EXPORT InputBuffer::ptr InputBuffer::create(const std::string& basename, const std::set<std::string>& category_interests)
 {
-	Initializer::initialize_ipaaca_rsb_if_needed();
+	Initializer::initialize_backend();
 	return InputBuffer::ptr(new InputBuffer(basename, category_interests));
 }
 IPAACA_EXPORT InputBuffer::ptr InputBuffer::create(const std::string& basename, const std::vector<std::string>& category_interests)
 {
-	Initializer::initialize_ipaaca_rsb_if_needed();
+	Initializer::initialize_backend();
 	return InputBuffer::ptr(new InputBuffer(basename, category_interests));
 }
 IPAACA_EXPORT InputBuffer::ptr InputBuffer::create(const std::string& basename, const std::string& category_interest1)
 {
-	Initializer::initialize_ipaaca_rsb_if_needed();
+	Initializer::initialize_backend();
 	return InputBuffer::ptr(new InputBuffer(basename, category_interest1));
 }
 IPAACA_EXPORT InputBuffer::ptr InputBuffer::create(const std::string& basename, const std::string& category_interest1, const std::string& category_interest2)
 {
-	Initializer::initialize_ipaaca_rsb_if_needed();
+	Initializer::initialize_backend();
 	return InputBuffer::ptr(new InputBuffer(basename, category_interest1, category_interest2));
 }
 IPAACA_EXPORT InputBuffer::ptr InputBuffer::create(const std::string& basename, const std::string& category_interest1, const std::string& category_interest2, const std::string& category_interest3)
 {
-	Initializer::initialize_ipaaca_rsb_if_needed();
+	Initializer::initialize_backend();
 	return InputBuffer::ptr(new InputBuffer(basename, category_interest1, category_interest2, category_interest3));
 }
 IPAACA_EXPORT InputBuffer::ptr InputBuffer::create(const std::string& basename, const std::string& category_interest1, const std::string& category_interest2, const std::string& category_interest3, const std::string& category_interest4)
 {
-	Initializer::initialize_ipaaca_rsb_if_needed();
+	Initializer::initialize_backend();
 	return InputBuffer::ptr(new InputBuffer(basename, category_interest1, category_interest2, category_interest3, category_interest4));
 }
 

ipaacalib/cpp/src/ipaaca-internal.cc

@@ -43,12 +43,16 @@ using namespace rsb::patterns;
 // static library Initializer
 IPAACA_EXPORT bool Initializer::_initialized = false;
 IPAACA_EXPORT bool Initializer::initialized() { return _initialized; }
-IPAACA_EXPORT void Initializer::initialize_ipaaca_rsb_if_needed()//{{{
+IPAACA_EXPORT void Initializer::initialize_ipaaca_rsb_if_needed()
+{
+	initialize_backend();
+}
+IPAACA_EXPORT void Initializer::initialize_backend()//{{{
 {
 	if (_initialized) return;
 
-	//IPAACA_INFO("Calling initialize_updated_default_config()")
-	initialize_updated_default_config();
+	//IPAACA_INFO("Calling auto_configure_rsb()")
+	auto_configure_rsb();
 
 	// RYT FIXME This configuration stuff has been simply removed in rsb!
 	//ParticipantConfig config = ParticipantConfig::fromConfiguration();
@@ -97,7 +101,7 @@ IPAACA_EXPORT void Initializer::dump_current_default_config()//{{{
 	//inprocess.setEnabled(true);
 	//config.addTransport(inprocess);
 }//}}}
-IPAACA_EXPORT void Initializer::initialize_updated_default_config()//{{{
+IPAACA_EXPORT void Initializer::auto_configure_rsb()//{{{
 {
 	// quick hack to iterate through the pwd parents
 	// and find the closest rsb plugin dir

ipaacalib/cpp/src/ipaaca-json.cc

@@ -192,6 +192,7 @@ int json_testbed_main(int argc, char** argv)//{{{
 }
 //}}}
 
+/*
 int fakeiu_main(int argc, char** argv)//{{{
 {
 	//if (argc<2) {
@@ -317,6 +318,7 @@ int fakeiu_main(int argc, char** argv)//{{{
 	return 0;
 }
 //}}}
+*/
 
 int legacy_iu_main(int argc, char** argv)//{{{
 {