From 754f494746b0eaa22bc409b8325b4bdedceb02f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20St=C3=BCrz?= Date: Sat, 25 Oct 2014 18:44:27 +0200 Subject: [PATCH] added some more documetations --- libguh/types/eventdescriptor.cpp | 2 +- libguh/types/state.cpp | 1 + libguh/types/state.h | 2 +- libguh/types/statedescriptor.cpp | 18 ++++++++ libguh/types/vendor.cpp | 7 +++- server/rule.cpp | 14 ++++--- server/ruleengine.cpp | 72 +++++++++++--------------------- 7 files changed, 59 insertions(+), 57 deletions(-) diff --git a/libguh/types/eventdescriptor.cpp b/libguh/types/eventdescriptor.cpp index 6ba6943c..3adb8811 100644 --- a/libguh/types/eventdescriptor.cpp +++ b/libguh/types/eventdescriptor.cpp @@ -30,7 +30,7 @@ #include "eventdescriptor.h" -/*! Constructs an EventDescriptor describing an Event. +/*! Constructs an EventDescriptor describing an \l{Event}. */ EventDescriptor::EventDescriptor(const EventTypeId &eventTypeId, const DeviceId &deviceId, const QList ¶mDescriptors): m_eventTypeId(eventTypeId), diff --git a/libguh/types/state.cpp b/libguh/types/state.cpp index 806045df..42392584 100644 --- a/libguh/types/state.cpp +++ b/libguh/types/state.cpp @@ -40,6 +40,7 @@ State::State(const StateTypeId &stateTypeId, const DeviceId &deviceId): { } +/*! Returns the id of this State. */ StateId State::id() const { return m_id; diff --git a/libguh/types/state.h b/libguh/types/state.h index 872d1d31..5983709a 100644 --- a/libguh/types/state.h +++ b/libguh/types/state.h @@ -34,7 +34,7 @@ public: StateTypeId stateTypeId() const; DeviceId deviceId() const; - QStringList stateNames() const; + //QStringList stateNames() const; QVariant value() const; void setValue(const QVariant &value); diff --git a/libguh/types/statedescriptor.cpp b/libguh/types/statedescriptor.cpp index 9be78fc4..c1a96689 100644 --- a/libguh/types/statedescriptor.cpp +++ b/libguh/types/statedescriptor.cpp @@ -31,12 +31,16 @@ #include "statedescriptor.h" +/*! Constructs an StateDescriptor describing an \l{State}. + */ StateDescriptor::StateDescriptor(): m_operatorType(Types::ValueOperatorEquals) { } +/*! Constructs an StateDescriptor describing an \l{State} with the given \a stateTypeId, \a deviceId, \a stateValue and \a operatorType. + */ StateDescriptor::StateDescriptor(const StateTypeId &stateTypeId, const DeviceId &deviceId, const QVariant &stateValue, Types::ValueOperator operatorType): m_stateTypeId(stateTypeId), m_deviceId(deviceId), @@ -46,26 +50,36 @@ StateDescriptor::StateDescriptor(const StateTypeId &stateTypeId, const DeviceId } +/*! Returns the StateTypeId of this \l{State}. + */ StateTypeId StateDescriptor::stateTypeId() const { return m_stateTypeId; } +/*! Returns the DeviceId of this \l{State}. + */ DeviceId StateDescriptor::deviceId() const { return m_deviceId; } +/*! Returns the Value of this \l{State}. + */ QVariant StateDescriptor::stateValue() const { return m_stateValue; } +/*! Returns the ValueOperator of this \l{State}. + */ Types::ValueOperator StateDescriptor::operatorType() const { return m_operatorType; } +/*! Overloads the == operator for this \l{State}.Returns true, if the given \a other \l{StateDescriptor} == this StateDescriptor. + */ bool StateDescriptor::operator ==(const StateDescriptor &other) const { return m_stateTypeId == other.stateTypeId() && @@ -74,6 +88,8 @@ bool StateDescriptor::operator ==(const StateDescriptor &other) const m_operatorType == other.operatorType(); } +/*! Overloads the == operator for this \l{State}. Returns true, if the given \a state == an other \l{State}. + */ bool StateDescriptor::operator ==(const State &state) const { if ((m_stateTypeId != state.stateTypeId()) || (m_deviceId != state.deviceId())) { @@ -96,6 +112,8 @@ bool StateDescriptor::operator ==(const State &state) const return false; } +/*! Overloads the != operator for this \l{State}. Returns true, if the given \a state != an other \l{State}. + */ bool StateDescriptor::operator !=(const State &state) const { return !(operator==(state)); diff --git a/libguh/types/vendor.cpp b/libguh/types/vendor.cpp index 811c3a06..5e9fecce 100644 --- a/libguh/types/vendor.cpp +++ b/libguh/types/vendor.cpp @@ -28,27 +28,32 @@ #include "vendor.h" +/*! Constructs an Vendor with the given \a id and the given \a name. + */ Vendor::Vendor(const VendorId &id, const QString &name): m_id(id), m_name(name) { } +/*! Returns the id of this vendor. */ VendorId Vendor::id() const { return m_id; } - +/*! Set the id of this vendor with the given \a id. */ void Vendor::setId(const VendorId &id) { m_id = id; } +/*! Returns the name of this vendor. */ QString Vendor::name() const { return m_name; } +/*! Set the name of this vendor with the given \a name. */ void Vendor::setName(const QString &name) { m_name = name; diff --git a/server/rule.cpp b/server/rule.cpp index cec368eb..25f837af 100644 --- a/server/rule.cpp +++ b/server/rule.cpp @@ -24,14 +24,16 @@ \inmodule server A Rule is always triggered by an \l{EventDescriptor}, has \l{State}{States} - to be compared and \l{Action}{Actions} to be executed. Additionally a - Rule is either of type \l{Rule::RuleTypeAll} or \l{Rule::RuleTypeAny} - which determines if all or any of the \l{State}{States} must be matching - in order for the \l{Action}{Actions} to be executed. + to be compared and \l{Action}{Actions} to be executed. \sa EventDescriptor, State, Action */ +// Additionally a Rule is either of type \l{Rule::RuleTypeAll} or \l{Rule::RuleTypeAny} +// which determines if all or any of the \l{State}{States} must be matching +// in order for the \l{Action}{Actions} to be executed. + + //! \enum Rule::RuleType // Note: There is no RuleTypeNone. If you don't want to compare any @@ -54,7 +56,7 @@ Rule::Rule() } -/*! Constructs a Rule with the given \a id, \a eventDescriptor, \a states and \a actions.*/ +/*! Constructs a Rule with the given \a id, \a eventDescriptorList, \a stateEvaluator and \a actions.*/ Rule::Rule(const RuleId &id, const QList &eventDescriptorList, const StateEvaluator &stateEvaluator, const QList &actions): m_id(id), m_eventDescriptors(eventDescriptorList), @@ -75,7 +77,7 @@ QList Rule::eventDescriptors() const return m_eventDescriptors; } -/*! Returns the \l{StateEvaluator} that needs to evaluate successfully in order for this to Rule apply. */ +/*! Returns the StateEvaluator that needs to evaluate successfully in order for this to Rule apply. */ StateEvaluator Rule::stateEvaluator() const { return m_stateEvaluator; diff --git a/server/ruleengine.cpp b/server/ruleengine.cpp index be911074..f2ff0e94 100644 --- a/server/ruleengine.cpp +++ b/server/ruleengine.cpp @@ -42,14 +42,30 @@ /*! \enum RuleEngine::RuleError \value RuleErrorNoError No error happened. Everything is fine. + \value RuleErrorInvalidRuleId + The given RuleId is not valid. \value RuleErrorRuleNotFound Couldn't find a \l{Rule} with the given id. \value RuleErrorDeviceNotFound Couldn't find a \l{Device} with the given id. \value RuleErrorEventTypeNotFound Couldn't find a \l{EventType} with the given id. + \value RuleErrorActionTypeNotFound + Couldn't find a \l{ActionType} with the given id. + \value RuleErrorInvalidParameter + The given \l{Param} is not valid. + \value RuleErrorMissingParameter + One of the given \l{Param}s is missing. */ +/*! \enum RuleEngine::RemovePolicy + \value RemovePolicyCascade + Remove the whole Rule. + \value RemovePolicyUpdate + Remove a \l{Device} from a rule. +*/ + + #include "ruleengine.h" #include "types/paramdescriptor.h" #include "types/eventdescriptor.h" @@ -170,15 +186,15 @@ QList RuleEngine::evaluateEvent(const Event &event) return actions; } -/*! Add a new \l{Rule} with the given \a EventDescriptorList and \a actions to the engine. +/*! Add a new \l{Rule} with the given \a ruleId , \a eventDescriptorList and \a actions to the engine. For convenience, this creates a Rule without any \l{State} comparison. */ RuleEngine::RuleError RuleEngine::addRule(const RuleId &ruleId, const QList &eventDescriptorList, const QList &actions, bool enabled) { return addRule(ruleId, eventDescriptorList, StateEvaluator(), actions, enabled); } -/*! Add a new \l{Rule} with the given \a event, \a states and \a actions to the engine. */ -RuleEngine::RuleError RuleEngine::addRule(const RuleId &ruleId, const QList &eventDescriptorList, const StateEvaluator &stateEvaluator, const QList &actions, bool enabled) +/*! Add a new \l{Rule} with the given \a ruleId , \a eventDescriptorList, \a stateEvaluator and list of \a actions to the engine.*/ +RuleEngine::RuleError RuleEngine::addRule(const RuleId &ruleId, const QList &eventDescriptorList, const StateEvaluator &stateEvaluator, const QList &actions) { if (ruleId.isNull()) { return RuleErrorInvalidRuleId; @@ -282,13 +298,14 @@ QList RuleEngine::rules() const return m_rules.values(); } +/*! Returns a list of all ruleIds loaded in this Engine. */ QList RuleEngine::ruleIds() const { return m_ruleIds; } /*! Removes the \l{Rule} with the given \a ruleId from the Engine. - Returns \l{RuleEngine::RuleError} which describes whether the operation + Returns \l{RuleError} which describes whether the operation was successful or not. */ RuleEngine::RuleError RuleEngine::removeRule(const RuleId &ruleId) { @@ -310,50 +327,7 @@ RuleEngine::RuleError RuleEngine::removeRule(const RuleId &ruleId) return RuleErrorNoError; } -/*! Enables a rule that has been previously disabled. - \sa disableRule */ -RuleEngine::RuleError RuleEngine::enableRule(const RuleId &ruleId) -{ - if (!m_rules.contains(ruleId)) { - qWarning() << "Rule not found. Can't enable it"; - return RuleErrorRuleNotFound; - } - Rule rule = m_rules.value(ruleId); - rule.setEnabled(true); - m_rules[ruleId] = rule; - QSettings settings(m_settingsFile); - settings.beginGroup(ruleId.toString()); - if (!settings.value("enabled", true).toBool()) { - settings.setValue("enabled", true); - emit ruleChanged(ruleId); - } - settings.endGroup(); - - return RuleErrorNoError; -} - -/*! Disables a rule. Disabled rules won't be triggered. - \sa enableRule */ -RuleEngine::RuleError RuleEngine::disableRule(const RuleId &ruleId) -{ - if (!m_rules.contains(ruleId)) { - qWarning() << "Rule not found. Can't disable it"; - return RuleErrorRuleNotFound; - } - Rule rule = m_rules.value(ruleId); - rule.setEnabled(false); - m_rules[ruleId] = rule; - QSettings settings(m_settingsFile); - settings.beginGroup(ruleId.toString()); - if (settings.value("enabled", true).toBool()) { - settings.setValue("enabled", false); - emit ruleChanged(ruleId); - } - settings.endGroup(); - - return RuleErrorNoError; -} - +/*! Returns the \l{Rule} with the given \a ruleId. If the \l{Rule} does not exist, it will return \l{Rule::Rule()} */ Rule RuleEngine::findRule(const RuleId &ruleId) { foreach (const Rule &rule, m_rules) { @@ -364,6 +338,7 @@ Rule RuleEngine::findRule(const RuleId &ruleId) return Rule(); } +/*! Returns a list of all \l{Rule}{Rules} loaded in this Engine, which contains a \l{Device} with the given \a deviceId. */ QList RuleEngine::findRules(const DeviceId &deviceId) { // Find all offending rules @@ -394,6 +369,7 @@ QList RuleEngine::findRules(const DeviceId &deviceId) return offendingRules; } +/*! Removes a \l{Device} from a \l{Rule} with the given \a id and \a deviceId. */ void RuleEngine::removeDeviceFromRule(const RuleId &id, const DeviceId &deviceId) { if (!m_rules.contains(id)) {