From 4c022b6a7e2a83a9a618a17bec322558e36da5b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20St=C3=BCrz?= Date: Thu, 7 May 2015 23:04:31 +0200 Subject: [PATCH] add documentation --- libguh/devicemanager.cpp | 39 +++++++++++++++++++++++++++++++++- libguh/devicemanager.h | 2 +- libguh/plugin/deviceplugin.cpp | 9 ++++++++ server/ruleengine.cpp | 6 ++++-- 4 files changed, 52 insertions(+), 4 deletions(-) diff --git a/libguh/devicemanager.cpp b/libguh/devicemanager.cpp index d7ddf46e..2ba54a11 100644 --- a/libguh/devicemanager.cpp +++ b/libguh/devicemanager.cpp @@ -93,6 +93,10 @@ The \l{Device} is currently bussy. \value DeviceErrorPairingTransactionIdNotFound Couldn't find the PairingTransactionId for the given id. + \value DeviceErrorAuthentificationFailure + The device could not authentificate with something. + \value DeviceErrorParameterNotEditable + One of the given device params is not editable. */ /*! \enum DeviceManager::DeviceSetupStatus @@ -121,6 +125,26 @@ \l{StateType} and the \a value parameter holds the new value. */ +/*! \fn void DeviceManager::deviceRemoved(const DeviceId &deviceId); + This signal is emitted when the \l{Device} with the given \a deviceId was removed from the system. This signal will + create the Devices.DeviceRemoved notification. +*/ + +/*! \fn void DeviceManager::deviceAdded(Device *device); + This signal is emitted when a \a \device was added to the system. This signal will + create the Devices.DeviceAdded notification. +*/ + +/*! \fn void DeviceManager::deviceParamsChanged(Device *device); + This signal is emitted when a \a \device was changed in the system (by edit or rediscover). This signal will + create the Devices.DeviceParamsChanged notification. +*/ + +/*! \fn void DeviceManager::deviceEditFinished(Device *device, DeviceError status); + This signal is emitted when the edit process of a \a device is finished. The \a status parameter describes the + \l{DeviceManager::DeviceError}{DeviceError} that occurred. +*/ + /*! \fn void DeviceManager::devicesDiscovered(const DeviceClassId &deviceClassId, const QList &devices); This signal is emitted when the discovery of a \a deviceClassId is finished. The \a devices parameter describes the list of \l{DeviceDescriptor}{DeviceDescriptors} of all discovered \l{Device}{Devices}. @@ -325,7 +349,13 @@ DeviceManager::DeviceError DeviceManager::addConfiguredDevice(const DeviceClassI return addConfiguredDeviceInternal(deviceClassId, descriptor.params(), deviceId); } -DeviceManager::DeviceError DeviceManager::editDevice(const DeviceId &deviceId, const ParamList ¶ms, const bool fromDiscovery) + +/*! Edit the \l{ParamList}{Params} of a configured device with the given \a deviceId to the new given \a params. + * The given parameter \a fromDiscovery specifies if the new \a params came + * from a discovery or if the user set them. If it came from discovery not editable will be changed too. + * + * Returns \l{DeviceError} to inform about the result. */ +DeviceManager::DeviceError DeviceManager::editDevice(const DeviceId &deviceId, const ParamList ¶ms, const bool &fromDiscovery) { Device *device = findConfiguredDevice(deviceId); if (!device) { @@ -389,6 +419,13 @@ DeviceManager::DeviceError DeviceManager::editDevice(const DeviceId &deviceId, c return DeviceErrorNoError; } +/*! Edit the \l{Param}{Params} of a configured device to the \l{Param}{Params} of the DeviceDescriptor with the + * given \a deviceId to the given DeviceDescriptorId. + * Only devices with \l{DeviceClass}{CreateMethodDiscovery} can be changed using this method. + * The \a deviceDescriptorId must refer to an existing DeviceDescriptorId from the discovery. + * This method allows to rediscover a device and update it's \l{Param}{Params}. + * + * Returns \l{DeviceError} to inform about the result. */ DeviceManager::DeviceError DeviceManager::editDevice(const DeviceId &deviceId, const DeviceDescriptorId &deviceDescriptorId) { Device *device = findConfiguredDevice(deviceId); diff --git a/libguh/devicemanager.h b/libguh/devicemanager.h index b53da077..a1ece7f9 100644 --- a/libguh/devicemanager.h +++ b/libguh/devicemanager.h @@ -99,7 +99,7 @@ public: DeviceError addConfiguredDevice(const DeviceClassId &deviceClassId, const ParamList ¶ms, const DeviceId id = DeviceId::createDeviceId()); DeviceError addConfiguredDevice(const DeviceClassId &deviceClassId, const DeviceDescriptorId &deviceDescriptorId, const DeviceId &id = DeviceId::createDeviceId()); - DeviceError editDevice(const DeviceId &deviceId, const ParamList ¶ms, const bool fromDiscovery = false); + DeviceError editDevice(const DeviceId &deviceId, const ParamList ¶ms, const bool &fromDiscovery = false); DeviceError editDevice(const DeviceId &deviceId, const DeviceDescriptorId &deviceDescriptorId); DeviceError pairDevice(const PairingTransactionId &pairingTransactionId, const DeviceClassId &deviceClassId, const ParamList ¶ms); diff --git a/libguh/plugin/deviceplugin.cpp b/libguh/plugin/deviceplugin.cpp index c21d5777..bcbf8bbc 100644 --- a/libguh/plugin/deviceplugin.cpp +++ b/libguh/plugin/deviceplugin.cpp @@ -333,6 +333,15 @@ DeviceManager::DeviceSetupStatus DevicePlugin::setupDevice(Device *device) return DeviceManager::DeviceSetupStatusSuccess; } +/*! This will be called when the \l{ParamList}{Params} of the given \a device was changed. + * Here you have the chance to set up the device with the new \l{ParamList}{Params} without creating a new one. + * + * Return \l{DeviceManager}{DeviceSetupStatusFailure} if something bad happened during the setup in which case the \a device + * will be disabled. Return \l{DeviceManager}{DeviceSetupStatusSuccess} if everything went well. If you can't tell yet and + * need more time to set up the \a device (note: you should never block in this method) you can + * return \l{DeviceManager}{DeviceSetupStatusAsync}. In that case the \l{DeviceManager} will wait for you to emit + * \l{DevicePlugin}{deviceSetupFinished} to report the status. + */ DeviceManager::DeviceSetupStatus DevicePlugin::editDevice(Device *device) { Q_UNUSED(device) diff --git a/server/ruleengine.cpp b/server/ruleengine.cpp index a2c455de..005bcda4 100644 --- a/server/ruleengine.cpp +++ b/server/ruleengine.cpp @@ -33,9 +33,9 @@ \sa Event, EventDescriptor, Rule, RuleAction */ -/*! \fn void RuleEngine::ruleAdded(const RuleId &ruleId) +/*! \fn void RuleEngine::ruleAdded(const Rule &rule) Will be emitted whenever a new \l{Rule} is added to this Engine. - \a ruleId holds the id of the new rule.*/ + The \a rule parameter holds the entire new rule.*/ /*! \fn void RuleEngine::ruleRemoved(const RuleId &ruleId) Will be emitted whenever a \l{Rule} is removed from this Engine. @@ -63,6 +63,8 @@ One of the given \l{Param}{Params} is missing. \value RuleErrorInvalidRuleActionParameter One of the given \l{RuleActionParam}{RuleActionParams} is not valid. + \value RuleErrorTypesNotMatching + One of the RuleActionParams type does not match with the corresponding EventParam type. */ /*! \enum RuleEngine::RemovePolicy