added documentation and fixed some doc errors

doc/config.qdocconf

@@ -12,5 +12,5 @@ headers.fileextensions = "*.h"
 imagedirs = images
 
 sourcedirs = ..
-sources.fileextensions = "*.cpp *.qdoc"
+sources.fileextensions = "*.cpp *.qdoc *.json"
 

libguh/devicemanager.cpp

@@ -42,7 +42,8 @@
     \value HardwareResourceRadio868
         Refers to the 868 MHz radio.
     \value HardwareResourceTimer
-        Refers to the global timer managed by the \l{DeviceManager}. Plugins should not create their own timers, but rather request the global timer using the hardware resources.
+        Refers to the global timer managed by the \l{DeviceManager}. Plugins should not create their own timers,
+        but rather request the global timer using the hardware resources.
 */
 
 /*!
@@ -52,21 +53,58 @@
 
     \value DeviceErrorNoError
         No Error. Everything went fine.
+    \value DeviceErrorPluginNotFound
+        Couldn't find the Plugin for the given id.
     \value DeviceErrorDeviceNotFound
         Couldn't find a \l{Device} for the given id.
     \value DeviceErrorDeviceClassNotFound
         Couldn't find a \l{DeviceClass} for the given id.
     \value DeviceErrorActionTypeNotFound
         Couldn't find the \l{ActionType} for the given id.
+    \value DeviceErrorStateTypeNotFound
+        Couldn't find the \l{StateType} for the given id.
+    \value DeviceErrorEventTypeNotFound
+        Couldn't find the \l{EventType} for the given id.
+    \value DeviceErrorDeviceDescriptorNotFound
+        Couldn't find the \l{DeviceDescriptor} for the given id.
     \value DeviceErrorMissingParameter
         Parameters do not comply to the template.
-    \value DeviceErrorPluginNotFound
+    \value DeviceErrorInvalidParameter
-        Couldn't find the Plugin for the given id.
+        One of the given parameter is not valid.
     \value DeviceErrorSetupFailed
-        Error setting up the \{Device}. It will not be functional.
+        Error setting up the \l{Device}. It will not be functional.
+    \value DeviceErrorDuplicateUuid
+        Error setting up the \l{Device}. The given DeviceId allready exists.
+    \value DeviceErrorCreationMethodNotSupported
+        Error setting up the \l{Device}. This \l{DeviceClass}{CreateMethod} is not supported for this \l{Device}.
+    \value DeviceErrorSetupMethodNotSupported
+        Error setting up the \l{Device}. This \l{DeviceClass}{SetupMethod} is not supported for this \l{Device}.
+    \value DeviceErrorHardwareNotAvailable
+        The Hardware of the \l{Device} is not available.
+    \value DeviceErrorHardwareFailure
+        The Hardware of the \l{Device} has an error.
+    \value DeviceErrorAsync
+        The response of the \l{Device} will be asynchronous.
+    \value DeviceErrorDeviceInUse
+        The \l{Device} is currently bussy.
+    \value DeviceErrorPairingTransactionIdNotFound
+        Couldn't find the PairingTransactionId for the given id.
 */
 
-/*! \fn void DeviceManager::emitEvent(const Event &event)
+/*!
+    \enum DeviceManager::DeviceSetupStatus
+
+    This enum type specifies the setup status of a \l{Device}.
+
+    \value DeviceSetupStatusSuccess
+        No Error. Everything went fine.
+    \value DeviceSetupStatusFailure
+        Something went wrong during the setup.
+    \value DeviceSetupStatusAsync
+        The status of the \l{Device} setup will be emitted asynchronous.
+*/
+
+/*! \fn void DeviceManager::eventTriggered(const Event &event)
     The DeviceManager will emit a \l{Event} described in \a event whenever a Device
     creates one. Normally only \l{GuhCore} should connect to this and execute actions
     after checking back with the \{RulesEngine}. Exceptions might be monitoring interfaces
@@ -119,6 +157,7 @@ DeviceManager::DeviceManager(QObject *parent) :
     // TODO: error handling if no Radio433 detected (GPIO or network), disable radio433 plugins or something...
 }
 
+/*! Destructor of the DeviceManager. Each loaded \l{DevicePlugin} will be deleted.*/
 DeviceManager::~DeviceManager()
 {
     qDebug() << "Shutting down DeviceManager";
@@ -139,6 +178,8 @@ DevicePlugin *DeviceManager::plugin(const PluginId &id) const
     return m_devicePlugins.value(id);
 }
 
+/*! Returns a certain \l{DeviceError} and sets the configurations of the plugin with the given \a pluginId
+    and the given \a pluginConfig */
 DeviceManager::DeviceError DeviceManager::setPluginConfig(const PluginId &pluginId, const ParamList &pluginConfig)
 {
     DevicePlugin *plugin = m_devicePlugins.value(pluginId);
@@ -160,6 +201,7 @@ DeviceManager::DeviceError DeviceManager::setPluginConfig(const PluginId &plugin
     return result;
 }
 
+/*! Returns all the \l{Vendor}s loaded in the system. */
 QList<Vendor> DeviceManager::supportedVendors() const
 {
     return m_supportedVendors.values();
@@ -179,7 +221,8 @@ QList<DeviceClass> DeviceManager::supportedDevices(const VendorId &vendorId) con
     }
     return ret;
 }
-
+/*! Returns a certain \l{DeviceError} and starts the discovering process of the \l{Device} with the given \a deviceClassId
+    and the given \a params.*/
 DeviceManager::DeviceError DeviceManager::discoverDevices(const DeviceClassId &deviceClassId, const ParamList &params)
 {
     qDebug() << "DeviceManager discoverdevices" << params;
@@ -209,23 +252,10 @@ DeviceManager::DeviceError DeviceManager::discoverDevices(const DeviceClassId &d
 }
 
 /*! Add a new configured device for the given \l{DeviceClass} and the given parameters.
- \a deviceClassId must refer to an existing \{DeviceClass} and \a params must match the parameter description in the \l{DeviceClass}.
+    \a deviceClassId must refer to an existing \{DeviceClass} and \a params must match the parameter description in the \l{DeviceClass}.
     Optionally you can supply an id yourself if you must keep track of the added device. If you don't supply it, a new one will
     be generated. Only devices with \l{DeviceClass::CreateMethodUser} can be created using this method.
-    Returns \l{DeviceManager::DeviceError} to inform about the result.
+    Returns \l{DeviceError} to inform about the result.
-    \list
-    \li DeviceManager::DeviceErrorNoError: The device has been created, set up and added to the list of configured devices correctly.
-    \li DeviceManager::DeviceErrorAsync: The device has been created, but the setup requires async operations. For instance a network query.
-    In this case, you should wait for the \l{deviceSetupFinished()} signal to get the final results.
-    \li DeviceManager::DeviceErrorCreateMethodNotSupported: The deviceId you've chosen refers to a DeviceClass which can't be created manually.
-    \li DeviceManager::DeviceErrorDeviceClassNotFound: The given deviceClassId can't be found in the list of supported devices.
-    \li DeviceManager::DeviceErrorMissingParameter: The given params do not suffice for the given deviceClassId.
-    \li DeviceManager::DeviceErrorDeviceParameterError: The given params can't be matched to the ParamTypes for the given deviceClassId.
-    \li DeviceManager::DeviceErrorDuplicateUuid: The given uuid already exists.
-    \li DeviceManager::DeviceErrorPluginNotFound: Couldn't find a plugin that handles this deviceClassId.
-    \li DeviceManager::DeviceErrorSetupFailed: The device couldn't be set up. Even though you supplied all the parameters correctly, something
-    went wrong during setup. Reasons may be a hardware/network failure, wrong username/password or similar, depending on what the device plugin
-    needs to do in order to set up the device.
 */
 DeviceManager::DeviceError DeviceManager::addConfiguredDevice(const DeviceClassId &deviceClassId, const ParamList &params, const DeviceId id)
 {
@@ -239,6 +269,11 @@ DeviceManager::DeviceError DeviceManager::addConfiguredDevice(const DeviceClassI
     return DeviceErrorCreationMethodNotSupported;
 }
 
+/*! Add a new configured device for the given \l{DeviceClass} the given DeviceDescriptorId. Only devices with \l{DeviceClass::CreateMethodDiscovery}
+    can be created using this method. The \a deviceClassId must refer to an existing \l{DeviceClass} and the \a deviceDescriptorId must refer to an existing DeviceDescriptorId
+    from the discovery.
+    Returns \l{DeviceError} to inform about the result.
+*/
 DeviceManager::DeviceError DeviceManager::addConfiguredDevice(const DeviceClassId &deviceClassId, const DeviceDescriptorId &deviceDescriptorId, const DeviceId &deviceId)
 {
     DeviceClass deviceClass = findDeviceClass(deviceClassId);
@@ -257,6 +292,10 @@ DeviceManager::DeviceError DeviceManager::addConfiguredDevice(const DeviceClassI
     return addConfiguredDeviceInternal(deviceClassId, descriptor.params(), deviceId);
 }
 
+/*!
+    Returns \l{DeviceManager}{DeviceError} to inform about the result.
+*/
+
 DeviceManager::DeviceError DeviceManager::pairDevice(const PairingTransactionId &pairingTransactionId, const DeviceClassId &deviceClassId, const ParamList &params)
 {
     DeviceClass deviceClass = findDeviceClass(deviceClassId);

libguh/plugin/deviceclass.cpp

@@ -16,8 +16,7 @@
  *                                                                         *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-/*!
+/*! \class DeviceClass
-    \class DeviceClass
     \brief Describes \l{Device}{Devices}.
 
     \ingroup devices
@@ -32,13 +31,38 @@
     \sa Device
 */
 
+/*! \enum DeviceClass::CreateMethod
+
+    This enum type specifies the CreateMethod of this \l{DeviceClass}
+
+    \value CreateMethodUser
+        The user will specify the \l{Param}s.
+    \value CreateMethodAuto
+        The device will be created automaticaly.
+    \value CreateMethodDiscovery
+        The device will be discovered and added by the user by specifying the DeviceDescriptorId.
+*/
+
+/*! \enum DeviceClass::SetupMethod
+
+    This enum type specifies the SetupMethod of this \l{DeviceClass}
+
+    \value SetupMethodJustAdd
+        The \l{Device} will be just added. This is the default value.
+    \value SetupMethodDisplayPin
+        During the setup, a pin will be displayed on the \l{Device}. The pin will be needed in order to pair the device.
+    \value SetupMethodEnterPin
+        During the setup, a pin will be needed in order to pair the \l{Device}.
+    \value SetupMethodPushButton
+        During the setup, a button has to be pushed in order to pair the \l{Device}.
+*/
+
 #include "deviceclass.h"
 
-/*! Constructs a DeviceClass with the give \a pluginId and \a id.
+/*! Constructs a DeviceClass with the give \a pluginId ,\a vendorId and \a id .
     When implementing a plugin, create a DeviceClass for each device you support.
     Generate a new uuid (e.g. uuidgen) and hardode it into the plugin. The id
-    should never change or it will appear as a new DeviceClass in the system.
+    should never change or it will appear as a new DeviceClass in the system.*/
- */
 DeviceClass::DeviceClass(const PluginId &pluginId, const VendorId &vendorId, const DeviceClassId &id):
     m_id(id),
     m_vendorId(vendorId),
@@ -46,34 +70,33 @@ DeviceClass::DeviceClass(const PluginId &pluginId, const VendorId &vendorId, con
     m_createMethods(CreateMethodUser),
     m_setupMethod(SetupMethodJustAdd)
 {
-
 }
 
-/*! Returns the id of this DeviceClass. */
+/*! Returns the id of this \l{DeviceClass}. */
 DeviceClassId DeviceClass::id() const
 {
     return m_id;
 }
 
-/*! Returns the VendorId for this DeviceClass */
+/*! Returns the VendorId for this \l{DeviceClass} */
 VendorId DeviceClass::vendorId() const
 {
     return m_vendorId;
 }
 
-/*! Returns the pluginId this DeviceClass is managed by. */
+/*! Returns the pluginId this \l{DeviceClass} is managed by. */
 PluginId DeviceClass::pluginId() const
 {
     return m_pluginId;
 }
 
-/*! Returns true if this DeviceClass's id, vendorId and pluginId are valid uuids. */
+/*! Returns true if this \l{DeviceClass}'s id, vendorId and pluginId are valid uuids. */
 bool DeviceClass::isValid() const
 {
     return !m_id.isNull() && !m_vendorId.isNull() && !m_pluginId.isNull();
 }
 
-/*! Returns the name of this DeviceClass's. This is visible to the user. */
+/*! Returns the name of this \l{DeviceClass}'s. This is visible to the user. */
 QString DeviceClass::name() const
 {
     return m_name;
@@ -86,14 +109,14 @@ void DeviceClass::setName(const QString &name)
 }
 
 /*! Returns the statesTypes of this DeviceClass. \{Device}{Devices} created
-    from this DeviceClass must have their states matching to this template. */
+    from this \l{DeviceClass} must have their states matching to this template. */
 QList<StateType> DeviceClass::stateTypes() const
 {
     return m_stateTypes;
 }
 
 /*! Set the \a stateTypes of this DeviceClass. \{Device}{Devices} created
-    from this DeviceClass must have their states matching to this template. */
+    from this \l{DeviceClass} must have their states matching to this template. */
 void DeviceClass::setStateTypes(const QList<StateType> &stateTypes)
 {
     m_stateTypes = stateTypes;
@@ -109,14 +132,14 @@ void DeviceClass::setStateTypes(const QList<StateType> &stateTypes)
 }
 
 /*! Returns the eventTypes of this DeviceClass. \{Device}{Devices} created
-    from this DeviceClass must have their events matching to this template. */
+    from this \l{DeviceClass} must have their events matching to this template. */
 QList<EventType> DeviceClass::eventTypes() const
 {
     return m_allEventTypes;
 }
 
 /*! Set the \a eventTypes of this DeviceClass. \{Device}{Devices} created
-    from this DeviceClass must have their events matching to this template. */
+    from this \l{DeviceClass} must have their events matching to this template. */
 void DeviceClass::setEventTypes(const QList<EventType> &eventTypes)
 {
     m_eventTypes = eventTypes;
@@ -132,68 +155,79 @@ void DeviceClass::setEventTypes(const QList<EventType> &eventTypes)
 }
 
 /*! Returns the actionTypes of this DeviceClass. \{Device}{Devices} created
-    from this DeviceClass must have their actions matching to this template. */
+    from this \l{DeviceClass} must have their actions matching to this template. */
 QList<ActionType> DeviceClass::actionTypes() const
 {
     return m_actionTypes;
 }
 
 /*! Set the \a actionTypes of this DeviceClass. \{Device}{Devices} created
-    from this DeviceClass must have their actions matching to this template. */
+    from this \l{DeviceClass} must have their actions matching to this template. */
 void DeviceClass::setActionTypes(const QList<ActionType> &actionTypes)
 {
     m_actionTypes = actionTypes;
 }
 
 /*! Returns the params description of this DeviceClass. \{Device}{Devices} created
-    from this DeviceClass must have their params matching to this template. */
+    from this \l{DeviceClass} must have their params matching to this template. */
 QList<ParamType> DeviceClass::paramTypes() const
 {
     return m_paramTypes;
 }
 
 /*! Set the \a params of this DeviceClass. \{Device}{Devices} created
-    from this DeviceClass must have their actions matching to this template. */
+    from this \l{DeviceClass} must have their actions matching to this template. */
 void DeviceClass::setParamTypes(const QList<ParamType> &params)
 {
     m_paramTypes = params;
 }
 
+/*! Returns the discovery params description of this DeviceClass. \{Device}{Devices} created
+    from this \l{DeviceClass} must have their params matching to this template. */
 QList<ParamType> DeviceClass::discoveryParamTypes() const
 {
     return m_discoveryParamTypes;
 }
-
+/*! Set the \a params of this DeviceClass for the discovery. \{Device}{Devices} created
+    from this \l{DeviceClass} must have their actions matching to this template. */
 void DeviceClass::setDiscoveryParamTypes(const QList<ParamType> &params)
 {
     m_discoveryParamTypes = params;
 }
 
+/*! Returns the \l{DeviceClass::CreateMethod}s of this \l{DeviceClass}.*/
 DeviceClass::CreateMethods DeviceClass::createMethods() const
 {
     return m_createMethods;
 }
 
+/*! Set the \a createMethods of this \l{DeviceClass}.
+    \sa CreateMethod, */
 void DeviceClass::setCreateMethods(DeviceClass::CreateMethods createMethods)
 {
     m_createMethods = createMethods;
 }
 
+/*! Returns the \l{DeviceClass::SetupMethod} of this \l{DeviceClass}.*/
 DeviceClass::SetupMethod DeviceClass::setupMethod() const
 {
     return m_setupMethod;
 }
 
+/*! Set the \a setupMethod of this \l{DeviceClass}.
+    \sa SetupMethod, */
 void DeviceClass::setSetupMethod(DeviceClass::SetupMethod setupMethod)
 {
     m_setupMethod = setupMethod;
 }
 
+/*! Returns the pairing information of this \l{DeviceClass}.*/
 QString DeviceClass::pairingInfo() const
 {
     return m_pairingInfo;
 }
 
+/*! Set the \a pairingInfo of this \l{DeviceClass}. */
 void DeviceClass::setPairingInfo(const QString &pairingInfo)
 {
     m_pairingInfo = pairingInfo;

libguh/plugin/devicedescriptor.cpp

@@ -16,6 +16,17 @@
  *                                                                         *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
+/*!
+    \class DeviceDescriptor
+    \brief Describes \l{Device}{Devices}.
+
+    \ingroup devices
+    \inmodule libguh
+
+    \sa Device
+*/
+
+
 #include "devicedescriptor.h"
 
 DeviceDescriptor::DeviceDescriptor():

libguh/plugin/deviceplugin.cpp

@@ -46,7 +46,7 @@ pure virtual methods: \l{DevicePlugin::pluginName()}, \l{DevicePlugin::pluginId(
  */
 
 /*!
- \fn void DevicePlugin::radioData(QList<int> rawData)
+ \fn void DevicePlugin::radioData(const QList<int> &rawData)
  If the plugin has requested any radio device using \l{DevicePlugin::requiredHardware()}, this slot will
  be called when there is \a rawData available from that device.
  */
@@ -74,7 +74,7 @@ pure virtual methods: \l{DevicePlugin::pluginName()}, \l{DevicePlugin::pluginId(
  DeviceManager::DeviceErrorAsync and continue processing in an async manner. Once
  you have the reply ready, emit actionExecutionFinished() with the appropriate parameters.
 
- \sa DevicePlugin::report() DevicePlugin::actionExecutionFinished()
+ \sa DevicePlugin::report(), DevicePlugin::actionExecutionFinished()
  */
 
 /*!

libguh/types/param.cpp

@@ -16,6 +16,16 @@
  *                                                                         *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
+/*!
+    \class Param
+    \brief Holds the parameters of a Param.
+
+    \ingroup types
+    \inmodule libguh
+
+    \sa Device, ParamType, ParamDescriptor
+*/
+
 #include "param.h"
 
 #include <QDebug>

libguh/types/paramdescriptor.cpp

@@ -16,6 +16,18 @@
  *                                                                         *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
+/*!
+    \class ParamDescriptor
+    \brief Describes a certain \l{Param}.
+
+    \ingroup types
+    \inmodule libguh
+
+    An ParamDescriptor describes a \l{Param} in order to match it with a \l{Rule}.
+
+    \sa State, Rule
+*/
+
 #include "paramdescriptor.h"
 
 ParamDescriptor::ParamDescriptor(const QString &name, const QVariant &value):

libguh/types/paramtype.cpp

@@ -15,6 +15,16 @@
  *  along with guh. If not, see <http://www.gnu.org/licenses/>.            *
  *                                                                         *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+/*!
+    \class ParamType
+    \brief Describes a certain ParamType.
+
+    \ingroup types
+    \inmodule libguh
+
+    \sa Device, Param
+*/
+
 
 #include "paramtype.h"
 

libguh/types/statedescriptor.cpp

@@ -16,6 +16,19 @@
  *                                                                         *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
+/*!
+    \class StateDescriptor
+    \brief Describes a certain \l{State}.
+
+    \ingroup types
+    \inmodule libguh
+
+    An StateDescriptor describes a \l{State} in order to match it with a \l{Rule}.
+
+    \sa State, Rule
+*/
+
+
 #include "statedescriptor.h"
 
 StateDescriptor::StateDescriptor():

libguh/types/vendor.cpp

@@ -16,6 +16,16 @@
  *                                                                         *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
+/*!
+    \class Vendor
+    \brief Holds information about a the vendor of a \l{Device}.
+
+    \ingroup types
+    \inmodule libguh
+
+    \sa Device
+*/
+
 #include "vendor.h"
 
 Vendor::Vendor(const VendorId &id, const QString &name):

plugins/deviceplugins/eq-3/deviceplugineq-3.cpp

@@ -17,7 +17,7 @@
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 /*!
-    \page wemo.html
+    \page eq3.html
     \title eQ-3 Max!
 
     \ingroup plugins

plugins/deviceplugins/openweathermap/devicepluginopenweathermap.cpp

@@ -265,6 +265,7 @@
                 \li 413b3fc6-bd1c-46fb-8c86-03096254f94f
                 \li unsigned int
             \endtable
+
 */
 
 

server/rule.cpp

@@ -32,17 +32,17 @@
     \sa EventDescriptor, State, Action
 */
 
-/*! \enum Rule::RuleType
+//! \enum Rule::RuleType
 
-    Note: There is no RuleTypeNone. If you don't want to compare any
+//    Note: There is no RuleTypeNone. If you don't want to compare any
-    states, construct a rule without states in which case it doesn't
+//    states, construct a rule without states in which case it doesn't
-    matter what the Rule's type is.
+//    matter what the Rule's type is.
+
+//    \value RuleTypeAll
+//    All States must match in order for the Rule to apply.
+//    \value RuleTypeAny
+//    Any State must match in order for the Rule to apply.
 
-    \value RuleTypeAll
-    All States must match in order for the Rule to apply.
-    \value RuleTypeAny
-    Any State must match in order for the Rule to apply.
-*/
 
 #include "rule.h"
 

server/ruleengine.cpp

@@ -30,11 +30,11 @@
     \sa Event, EventDescriptor, Rule, Action
 */
 
-/*! \fn void RuleEngine::ruleAdded(const QUuid &ruleId)
+/*! \fn void RuleEngine::ruleAdded(const RuleId &ruleId)
     Will be emitted whenever a new \l{Rule} is added to this Engine.
     \a ruleId holds the id of the new rule.*/
 
-/*! \fn void RuleEngine::ruleRemoved(const QUuid &ruleId)
+/*! \fn void RuleEngine::ruleRemoved(const RuleId &ruleId)
     Will be emitted whenever a \l{Rule} is removed from this Engine.
     \a ruleId holds the id of the removed rule. You should remove any references
     or copies you hold for this rule.*/
@@ -48,7 +48,7 @@
         Couldn't find a \l{Device} with the given id.
     \value RuleErrorEventTypeNotFound
         Couldn't find a \l{EventType} with the given id.
-    */
+*/
 
 #include "ruleengine.h"
 #include "types/paramdescriptor.h"