Comments of public API

5 files changed, 340 insertions, 4 deletions

diff --git a/src/CommonAPI/Attribute.h b/src/CommonAPI/Attribute.h
index a466e78..8295a3e 100644
--- a/src/CommonAPI/Attribute.h
+++ b/src/CommonAPI/Attribute.h
@@ -18,6 +18,11 @@
 
 namespace CommonAPI {
 
+/**
+ * \brief Class representing a read only attribute
+ *
+ * Class representing a read only attribute
+ */
 template <typename _ValueType>
 class ReadonlyAttribute {
  public:
@@ -26,10 +31,32 @@ class ReadonlyAttribute {
 
 	virtual ~ReadonlyAttribute() { }
 
+	/**
+	 * \brief Get value of attribute, usually from remote. Synchronous call.
+	 *
+	 * Get value of attribute, usually from remote. Synchronous call.
+	 *
+	 * @param value Reference to be filled with value.
+	 * @return Call status of the operation.
+	 */
 	virtual CallStatus getValue(_ValueType& value) const = 0;
+
+	/**
+     * \brief Get value of attribute, usually from remote. Asynchronous call.
+     *
+     * Get value of attribute, usually from remote. Asynchronous call.
+     *
+     * @param attributeAsyncCallback std::function object for the callback to be invoked.
+     * @return std::future containing the call status of the operation.
+     */
 	virtual std::future<CallStatus> getValueAsync(AttributeAsyncCallback attributeAsyncCallback) = 0;
 };
 
+/**
+ * \brief Class representing a read and writable attribute
+ *
+ * Class representing a read and writable attribute
+ */
 template <typename _ValueType>
 class Attribute: public ReadonlyAttribute<_ValueType> {
  public:
@@ -38,11 +65,35 @@ class Attribute: public ReadonlyAttribute<_ValueType> {
 
 	virtual ~Attribute() { }
 
+    /**
+     * \brief Set value of attribute, usually to remote. Synchronous call.
+     *
+     * Set value of attribute, usually to remote. Synchronous call.
+     *
+     * @param requestValue Value to be set
+     * @param callStatus call status reference will be filled with status of the operation
+     * @param responseValue Reference which will contain the actuall value set by the remote.
+     */
 	virtual void setValue(const _ValueType& requestValue, CallStatus& callStatus, _ValueType& responseValue) = 0;
+
+	/**
+     * \brief Set value of attribute, usually to remote. Asynchronous call.
+     *
+     * Set value of attribute, usually to remote. Asynchronous call.
+     *
+     * @param requestValue Value to be set
+     * @param attributeAsyncCallback std::function object for the callback to be invoked.
+     * @return std::future containing the call status of the operation.
+     */
 	virtual std::future<CallStatus> setValueAsync(const _ValueType& requestValue,
 												  AttributeAsyncCallback attributeAsyncCallback) = 0;
 };
 
+/**
+ * \brief Class representing an observable attribute
+ *
+ * Class representing an observable attribute
+ */
 template <typename _AttributeBaseClass>
 class _ObservableAttributeImpl: public _AttributeBaseClass {
  public:
@@ -52,6 +103,13 @@ class _ObservableAttributeImpl: public _AttributeBaseClass {
 
 	virtual ~_ObservableAttributeImpl() { }
 
+	/**
+	 * \brief Returns the event handler for the remote change notifiaction event
+	 *
+	 * Returns the event handler for the remote change notifiaction event
+	 *
+	 * @return The event handler object
+	 */
 	virtual ChangedEvent& getChangedEvent() = 0;
 };
 
diff --git a/src/CommonAPI/Event.h b/src/CommonAPI/Event.h
index 956ea8d..6c7c1cf 100644
--- a/src/CommonAPI/Event.h
+++ b/src/CommonAPI/Event.h
@@ -19,7 +19,11 @@ enum class SubscriptionStatus {
 	CANCEL
 };
 
-
+/**
+ * \brief Class representing an event
+ *
+ * Class representing an event
+ */
 template <typename... _Arguments>
 class Event {
  public:
@@ -31,8 +35,34 @@ class Event {
 
 	class CancellableListenerWrapper;
 
+	/**
+	 * \brief Subscribe a listener to this event
+	 *
+	 * Subscribe a listener to this event
+	 *
+	 * @param listener A listener to be added
+	 * @return A token identifying this subscription
+	 */
 	inline Subscription subscribe(Listener listener);
+
+	/**
+     * \brief Subscribe a cancellable listener to this event
+     *
+     * Subscribe a cancellable listener to this event
+     *
+     * @param listener A cancellable listener to be added
+     * @return A token identifying this subscription
+     */
 	Subscription subscribeCancellableListener(CancellableListener listener);
+
+	/**
+     * \brief Remove a listener from this event
+     *
+     * Remove a listener from this event
+     * Note: Do not call this inside a listener notification callback it will deadlock! Use cancellable listeners instead.
+     *
+     * @param listenerSubscription A listener token to be removed
+     */
 	void unsubscribe(Subscription listenerSubscription);
 
 	virtual ~Event() {}
diff --git a/src/CommonAPI/Factory.h b/src/CommonAPI/Factory.h
index 47dda82..7f167a1 100644
--- a/src/CommonAPI/Factory.h
+++ b/src/CommonAPI/Factory.h
@@ -35,9 +35,20 @@ struct DefaultAttributeProxyFactoryHelper;
 template<template<typename ...> class _ProxyClass, template<typename> class _AttributeExtension>
 std::shared_ptr<typename DefaultAttributeProxyFactoryHelper<_ProxyClass, _AttributeExtension>::class_t> createProxyWithDefaultAttributeExtension(Factory* specificFactory, const std::string& participantId, const std::string& domain);
 
-
+/**
+ * \brief The main CommonAPI access class. A factory is responsible for creation and destruction of service objects.
+ *
+ * The main CommonAPI access class. A factory is responsible for creation and destruction of service objects.
+ * This includes proxies and stubs. It also provides service discovery methods.
+ */
 class Factory {
  public:
+
+    /**
+     * \brief Creates factory. Don't call manually.
+     *
+     * Creates factory. Don't call manually.
+     */
     Factory(const std::shared_ptr<Runtime> runtime,
             const MiddlewareInfo* middlewareInfo):
                 runtime_(runtime),
@@ -46,6 +57,17 @@ class Factory {
 
     virtual ~Factory() {}
 
+    /**
+     * \brief Build a proxy for the specified address
+     *
+     * Build a proxy for the specified address.
+     * Template this method call for the desired proxy type and attribute extension.
+     *
+     * @param participantId The participant ID of the common API address (last part)
+     * @param serviceName The service name of the common API address (middle part)
+     * @param domain The domain of the common API address (first part)
+     * @return a shared pointer to the constructed proxy
+     */
     template<template<typename ...> class _ProxyClass, typename ... _AttributeExtensions>
     std::shared_ptr<_ProxyClass<_AttributeExtensions...> >
     buildProxy(const std::string& participantId,
@@ -56,6 +78,15 @@ class Factory {
     	return std::make_shared<_ProxyClass<_AttributeExtensions...>>(abstractMiddlewareProxy);
     }
 
+    /**
+     * \brief Build a proxy for the specified address
+     *
+     * Build a proxy for the specified address.
+     * Template this method call for the desired proxy type and attribute extension.
+     *
+     * @param serviceAddress The common API address
+     * @return a shared pointer to the constructed proxy
+     */
     template<template<typename ...> class _ProxyClass, typename ... _AttributeExtensions >
     std::shared_ptr<_ProxyClass<_AttributeExtensions...> >
     buildProxy(const std::string& serviceAddress) {
@@ -70,6 +101,17 @@ class Factory {
 		return buildProxy<_ProxyClass, _AttributeExtensions...>(participantId, serviceName, domain);
     }
 
+    /**
+     * \brief Build a proxy for the specified address with one extension for all attributes
+     *
+     * Build a proxy for the specified address with one extension for all attributes
+     * Template this method call for the desired proxy type attribute extension.
+     *
+     * @param participantId The participant ID of the common API address (last part)
+     * @param serviceName The service name of the common API address (middle part)
+     * @param domain The domain of the common API address (first part)
+     * @return a shared pointer to the constructed proxy
+     */
     template <template<typename ...> class _ProxyClass, template<typename> class _AttributeExtension>
     std::shared_ptr<typename DefaultAttributeProxyFactoryHelper<_ProxyClass, _AttributeExtension>::class_t>
     buildProxyWithDefaultAttributeExtension(const std::string& participantId,
@@ -80,6 +122,15 @@ class Factory {
     	return std::make_shared<typename DefaultAttributeProxyFactoryHelper<_ProxyClass, _AttributeExtension>::class_t>(abstractMiddlewareProxy);
     }
 
+    /**
+     * \brief Build a proxy for the specified address with one extension for all attributes
+     *
+     * Build a proxy for the specified address with one extension for all attributes
+     * Template this method call for the desired proxy type attribute extension.
+     *
+     * @param serviceAddress The common API address
+     * @return a shared pointer to the constructed proxy
+     */
     template <template<typename ...> class _ProxyClass, template<typename> class _AttributeExtension>
     std::shared_ptr<typename DefaultAttributeProxyFactoryHelper<_ProxyClass, _AttributeExtension>::class_t>
     buildProxyWithDefaultAttributeExtension(const std::string& serviceAddress) {
@@ -94,10 +145,28 @@ class Factory {
 		return buildProxyWithDefaultAttributeExtension<_ProxyClass, _AttributeExtension>(participantId, serviceName, domain);
     }
 
+    /**
+     * \brief Get a pointer to the runtime of this factory.
+     *
+     * Get a pointer to the runtime of this factory.
+     *
+     * @return the Runtime
+     */
     inline std::shared_ptr<Runtime> getRuntime() {
         return runtime_;
     }
 
+    /**
+     * \brief Register a service stub under a specified address
+     *
+     * Register a service stub under a specified address
+     *
+     * @param stub The stub pointer
+     * @param participantId The participant ID of the common API address (last part)
+     * @param serviceName The service name of the common API address (middle part)
+     * @param domain The domain of the common API address (first part)
+     * @return Was the registration successful
+     */
     template<typename _Stub>
     bool registerService(std::shared_ptr<_Stub> stub,
     				     const std::string& participantId,
@@ -108,6 +177,15 @@ class Factory {
 		return registerAdapter(stubBase, _Stub::StubAdapterType::getInterfaceId(), participantId, serviceName, domain);
     }
 
+    /**
+     * \brief Register a service stub under a specified address
+     *
+     * Register a service stub under a specified address
+     *
+     * @param stub The stub pointer
+     * @param serviceAddress The common API address
+     * @return Was the registration successful
+     */
     template<typename _Stub>
     bool registerService(std::shared_ptr<_Stub> stub, const std::string& serviceAddress) {
 		std::string domain;
@@ -120,7 +198,26 @@ class Factory {
 		return registerService<_Stub>(stub, participantId, serviceName, domain);
     }
 
+    /**
+     * \brief Unregister a service stub associated with a specified address
+     *
+     * Unregister a service stub associated with a specified address
+     *
+     * @param participantId The participant ID of the common API address (last part)
+     * @param serviceName The service name of the common API address (middle part)
+     * @param domain The domain of the common API address (first part)
+     * @return Was the deregistration successful
+     */
     virtual bool unregisterService(const std::string& participantId, const std::string& serviceName, const std::string& domain) = 0;
+
+    /**
+     * \brief Unregister a service stub associated with a specified address
+     *
+     * Unregister a service stub associated with a specified address
+     *
+     * @param serviceAddress The common API address
+     * @return Was the deregistration successful
+     */
     inline bool unregisterService(const std::string& serviceAddress) {
 		std::string domain;
 		std::string serviceName;
@@ -131,9 +228,37 @@ class Factory {
 		return unregisterService(participantId, serviceName, domain);
     }
 
+    /**
+     * \brief Get all instances of a specific service name available. Synchronous call.
+     *
+     * Get all instances of a specific service name available. Synchronous call.
+     *
+     * @param serviceName The service name of the common API address (middle part)
+     * @param serviceDomainName The domain of the common API address (first part)
+     * @return A vector of strings containing the available complete common api addresses.
+     */
     virtual std::vector<std::string> getAvailableServiceInstances(const std::string& serviceName, const std::string& serviceDomainName = "local") = 0;
 
+    /**
+     * \brief Is a particular complete common api address available. Synchronous call.
+     *
+     * Is a particular complete common api address available. Synchronous call.
+     *
+     * @param serviceAddress The common API address
+     * @return Is alive
+     */
     virtual bool isServiceInstanceAlive(const std::string& serviceAddress) = 0;
+
+    /**
+     * \brief Is a particular complete common api address available. Synchronous call.
+     *
+     * Is a particular complete common api address available. Synchronous call.
+     *
+     * @param serviceInstanceID The participant ID of the common API address (last part)
+     * @param serviceName The service name of the common API address (middle part)
+     * @param serviceDomainName The domain of the common API address (first part)
+     * @return Is alive
+     */
     virtual bool isServiceInstanceAlive(const std::string& serviceInstanceID, const std::string& serviceName, const std::string& serviceDomainName = "local") = 0;
 
  protected:
diff --git a/src/CommonAPI/Runtime.h b/src/CommonAPI/Runtime.h
index 92cf736..154cb67 100644
--- a/src/CommonAPI/Runtime.h
+++ b/src/CommonAPI/Runtime.h
@@ -26,14 +26,45 @@ namespace CommonAPI {
 class Factory;
 class Runtime;
 
-
+/**
+ * \brief Represents the CommonAPI runtime bindings available.
+ *
+ * Represents the CommonAPI runtime bindings available.
+ */
 class Runtime {
  public:
+
+    /**
+     * \brief Loads the default runtime
+     *
+     * Loads the default runtime. This is the only one available, or the default as defined in configuration
+     *
+     * @return The runtime object for this binding
+     */
     static std::shared_ptr<Runtime> load();
+    /**
+     * \brief Loads specified runtime
+     *
+     * Loads specified runtime. This is specified by either the well known name defined by the binding, or configured
+     *
+     * @return The runtime object for specified binding
+     */
     static std::shared_ptr<Runtime> load(const std::string& middlewareId);
+    /**
+     * \brief Called by bindings to register their methods. Do not call from applications.
+     *
+     * Called by bindings to register their methods. Do not call from applications.
+     */
     static void registerRuntimeLoader(std::string middlewareName, MiddlewareRuntimeLoadFunction middlewareRuntimeLoadFunction);
 
     virtual ~Runtime() {}
+    /**
+     * \brief Create a factory for the loaded runtime
+     *
+     * Create a factory for the loaded runtime
+     *
+     * @return Factory object for the loaded runtime
+     */
     virtual std::shared_ptr<Factory> createFactory() = 0;
 };
 
diff --git a/src/CommonAPI/SerializableVariant.h b/src/CommonAPI/SerializableVariant.h
index b7524ed..51f8224 100644
--- a/src/CommonAPI/SerializableVariant.h
+++ b/src/CommonAPI/SerializableVariant.h
@@ -25,6 +25,11 @@ class TypeOutputStream;
 template<typename _Type>
 struct TypeWriter;
 
+/**
+ * \brief A variant class which can be serialised by bindings.
+ *
+ * A variant class which can be serialised by bindings.
+ */
 class SerializableVariant {
 public:
     virtual ~SerializableVariant() {
@@ -63,6 +68,11 @@ struct VariantTypeSelector<_SearchType, _SearchType, _RestTypes...> {
     typedef _SearchType type;
 };
 
+/**
+ * \brief A templated generic variant class which provides type safe access and operators
+ *
+ * A templated generic variant class which provides type safe access and operators
+ */
 template<typename ... _Types>
 class Variant: public SerializableVariant {
 private:
@@ -72,10 +82,30 @@ public:
 
     static const unsigned int maxSize = MaxSize<_Types...>::value;
 
+    /**
+     * \brief Construct an empty variant
+     *
+     * Construct an empty variant
+     */
     Variant();
 
+
+    /**
+     * \brief Copy constructor. Must have identical templates.
+     *
+     * Copy constructor. Must have identical templates.
+     *
+     * @param fromVariant Variant to copy
+     */
     Variant(const Variant& fromVariant);
 
+    /**
+     * \brief Copy constructor. Must have identical templates.
+     *
+     * Copy constructor. Must have identical templates.
+     *
+     * @param fromVariant Variant to copy
+     */
     Variant(Variant&& fromVariant);
 
     ~Variant();
@@ -86,27 +116,82 @@ public:
 
     virtual void writeToTypeOutputStream(TypeOutputStream& typeOutputStream) const;
 
+    /**
+      * \brief Assignment of another variant. Must have identical templates.
+      *
+      * Assignment of another variant. Must have identical templates.
+      *
+      * @param rhs Variant to assign
+      */
     Variant& operator=(const Variant& rhs);
-
+    /**
+     * \brief Assignment of another variant. Must have identical templates.
+     *
+     * Assignment of another variant. Must have identical templates.
+     *
+     * @param rhs Variant to assign
+     */
     Variant& operator=(Variant&& rhs);
 
+    /**
+     * \brief Assignment of a contained type. Must be one of the valid templated types.
+     *
+     * Assignment of a contained type. Must be one of the valid templated types.
+     *
+     * @param value Value to assign
+     */
     template<typename _Type>
     typename std::enable_if<!std::is_same<_Type, Variant<_Types...>>::value, Variant<_Types...>&>::type
     operator=(const _Type& value);
 
+    /**
+     * \brief Equality of another variant. Must have identical template list and content.
+     *
+     * Equality of another variant. Must have identical template list and content.
+     *
+     * @param rhs Variant to compare
+     */
     bool operator==(const Variant<_Types...>& rhs) const;
 
+    /**
+      * \brief Not-Equality of another variant. Must have identical template list and content.
+      *
+      * Not-Equality of another variant. Must have identical template list and content.
+      *
+      * @param rhs Variant to compare
+      */
     bool operator!=(const Variant<_Types...>& rhs) const;
 
+    /**
+      * \brief Testif the contained type is the same as the template on this method.
+      *
+      * Testif the contained type is the same as the template on this method.
+      *
+      * @return Is same type
+      */
     template <typename _Type>
     const bool isType() const;
 
+    /**
+     * \brief Construct variant with content type set to value.
+     *
+     * Construct variant with content type set to value.
+     *
+     * @param value Value to place
+     */
     template <typename _Type>
     Variant(const _Type& value,
                     typename std::enable_if<!std::is_const<_Type>::value>::type* = 0,
                     typename std::enable_if<!std::is_reference<_Type>::value>::type* = 0,
                     typename std::enable_if<!std::is_same<_Type, Variant>::value>::type* = 0);
 
+    /**
+     * \brief Construct variant with content type set to value.
+     *
+     * Construct variant with content type set to value.
+     *
+     * @param value Value to place
+     */
     template <typename _Type>
     Variant(_Type && value,
                     typename std::enable_if<!std::is_const<_Type>::value>::type* = 0,
@@ -116,6 +201,13 @@ public:
     template <typename _Type>
     const _Type& get() const;
 
+    /**
+     * \brief Get index in template list of type actually contained
+     *
+     * Get index in template list of type actually contained
+     *
+     * @return Index of contained type
+     */
     inline uint8_t getValueType() const {
     	return valueType_;
     }