From c6681ec151cb9cd0303c40f7e04d7e1284d42fc8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20St=C3=BCrz?= Date: Thu, 13 Aug 2015 12:06:29 +0200 Subject: [PATCH] add more core documentation --- guh.pro | 2 +- server/jsonrpc/actionhandler.cpp | 4 ++-- server/jsonrpc/devicehandler.cpp | 14 ++++++++++++ server/jsonrpc/eventhandler.cpp | 13 +++++++++++ server/jsonrpc/jsonhandler.cpp | 25 ++++++++++++++++++++ server/rest/deviceclassesresource.cpp | 27 ++++++++++++++++++++++ server/rest/devicesresource.cpp | 18 +++++++++++++++ server/stateevaluator.cpp | 33 +++++++++++++++++++++++++++ 8 files changed, 133 insertions(+), 3 deletions(-) diff --git a/guh.pro b/guh.pro index 6ffaa8fc..0823fee5 100644 --- a/guh.pro +++ b/guh.pro @@ -25,7 +25,7 @@ tests.depends = libguh doc.depends = libguh server doc.commands = cd $$top_srcdir/doc; qdoc config.qdocconf; cp images/logo.png html/images/; \ - cp -v favicons/* html/; cp -r $$top_srcdir/doc/html $$top_builddir/ + cp favicons/* html/; cp -r $$top_srcdir/doc/html $$top_builddir/ licensecheck.commands = $$top_srcdir/tests/auto/checklicenseheaders.sh $$top_srcdir diff --git a/server/jsonrpc/actionhandler.cpp b/server/jsonrpc/actionhandler.cpp index d1b2e341..652175f0 100644 --- a/server/jsonrpc/actionhandler.cpp +++ b/server/jsonrpc/actionhandler.cpp @@ -21,7 +21,7 @@ /*! \class guhserver::ActionHandler - \brief This subclass of \l{JsonHandler} processes the JSON requests for the \tt Action namespace. + \brief This subclass of \l{JsonHandler} processes the JSON requests for the \tt Actions namespace. \ingroup json \inmodule core @@ -29,7 +29,7 @@ This \l{JsonHandler} will be created in the \l{JsonRPCServer} and used to handle JSON-RPC requests for the \tt {Action} namespace of the API. - \sa JsonHandler, JsonRPCServer + \sa Action, JsonHandler, JsonRPCServer */ #include "actionhandler.h" diff --git a/server/jsonrpc/devicehandler.cpp b/server/jsonrpc/devicehandler.cpp index 6421fbb3..a607889d 100644 --- a/server/jsonrpc/devicehandler.cpp +++ b/server/jsonrpc/devicehandler.cpp @@ -19,6 +19,20 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! + \class guhserver::DeviceHandler + \brief This subclass of \l{JsonHandler} processes the JSON requests for the \tt Devices namespace of the JSON-RPC API. + + \ingroup json + \inmodule core + + This \l{JsonHandler} will be created in the \l{JsonRPCServer} and used to handle JSON-RPC requests + for the \tt {Devices} namespace of the API. + + \sa Device, JsonHandler, JsonRPCServer +*/ + + #include "devicehandler.h" #include "guhcore.h" #include "devicemanager.h" diff --git a/server/jsonrpc/eventhandler.cpp b/server/jsonrpc/eventhandler.cpp index a4edcd61..3fc0d721 100644 --- a/server/jsonrpc/eventhandler.cpp +++ b/server/jsonrpc/eventhandler.cpp @@ -19,6 +19,19 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! + \class guhserver::EventHandler + \brief This subclass of \l{JsonHandler} processes the JSON requests for the \tt Events namespace. + + \ingroup json + \inmodule core + + This \l{JsonHandler} will be created in the \l{JsonRPCServer} and used to handle JSON-RPC requests + for the \tt {Events} namespace of the API. + + \sa Event, JsonHandler, JsonRPCServer +*/ + #include "eventhandler.h" #include "guhcore.h" #include "loggingcategories.h" diff --git a/server/jsonrpc/jsonhandler.cpp b/server/jsonrpc/jsonhandler.cpp index 2031c884..fa9121c9 100644 --- a/server/jsonrpc/jsonhandler.cpp +++ b/server/jsonrpc/jsonhandler.cpp @@ -19,6 +19,16 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! + \class guhserver::JsonHandler + \brief This class represents an interface for developing a handler for the JSON-RPC API. + + \ingroup json + \inmodule core + + \sa JsonRPCServer, JsonReply +*/ + #include "jsonhandler.h" #include "loggingcategories.h" @@ -28,11 +38,13 @@ namespace guhserver { +/*! Constructs a new \l JsonHandler with the given \a parent. */ JsonHandler::JsonHandler(QObject *parent) : QObject(parent) { } +/*! Returns a map with all supported methods, notifications and types for the given meta \a type. */ QVariantMap JsonHandler::introspect(QMetaMethod::MethodType type) { QVariantMap data; @@ -76,6 +88,7 @@ QVariantMap JsonHandler::introspect(QMetaMethod::MethodType type) return data; } +/*! Returns true if this \l JsonHandler has a method with the given \a methodName.*/ bool JsonHandler::hasMethod(const QString &methodName) { return m_descriptions.contains(methodName) && m_params.contains(methodName) && m_returns.contains(methodName); @@ -160,6 +173,18 @@ QVariantMap JsonHandler::statusToReply(Logging::LoggingError status) const return returns; } + +/*! + \class guhserver::JsonReply + \brief This class represents a reply for the JSON-RPC API request. + + \ingroup json + \inmodule core + + \sa JsonHandler, JsonRPCServer +*/ + + JsonReply::JsonReply(Type type, JsonHandler *handler, const QString &method, const QVariantMap &data): m_type(type), m_data(data), diff --git a/server/rest/deviceclassesresource.cpp b/server/rest/deviceclassesresource.cpp index 970497c2..20350239 100644 --- a/server/rest/deviceclassesresource.cpp +++ b/server/rest/deviceclassesresource.cpp @@ -18,6 +18,23 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! + \class guhserver::DeviceClassesResource + \brief This subclass of \l{RestResource} processes the REST requests for the \tt DeviceClasses namespace. + + \ingroup json + \inmodule core + + This \l{RestResource} will be created in the \l{RestServer} and used to handle REST requests + for the \tt {DeviceClasses} namespace of the API. + + \code + http://localhost:3333/api/v1/deviceclasses + \endcode + + \sa DeviceClass, RestResource, RestServer +*/ + #include "deviceclassesresource.h" #include "httprequest.h" #include "guhcore.h" @@ -26,17 +43,27 @@ namespace guhserver { +/*! Constructs a \l DeviceClassesResource with the given \a parent. */ DeviceClassesResource::DeviceClassesResource(QObject *parent) : RestResource(parent) { connect(GuhCore::instance(), &GuhCore::devicesDiscovered, this, &DeviceClassesResource::devicesDiscovered, Qt::QueuedConnection); } +/*! Returns the name of the \l{RestResource}. In this case \b deviceclasses. + + \sa RestResource::name() +*/ QString DeviceClassesResource::name() const { return "deviceclasses"; } +/*! This method will be used to process the given \a request and the given \a urlTokens. The request + has to be in this namespace. Returns the resulting \l HttpReply. + + \sa HttpRequest, HttpReply, RestResource::proccessRequest() +*/ HttpReply *DeviceClassesResource::proccessRequest(const HttpRequest &request, const QStringList &urlTokens) { diff --git a/server/rest/devicesresource.cpp b/server/rest/devicesresource.cpp index 67925569..d4d0cae2 100644 --- a/server/rest/devicesresource.cpp +++ b/server/rest/devicesresource.cpp @@ -18,6 +18,24 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! + \class guhserver::DevicesResource + \brief This subclass of \l{RestResource} processes the REST requests for the \tt Devices namespace. + + \ingroup json + \inmodule core + + This \l{RestResource} will be created in the \l{RestServer} and used to handle REST requests + for the \tt {Devices} namespace of the API. + + \code + http://localhost:3333/api/v1/devices + \endcode + + \sa Device, RestResource, RestServer +*/ + + #include "devicesresource.h" #include "httpreply.h" #include "httprequest.h" diff --git a/server/stateevaluator.cpp b/server/stateevaluator.cpp index da5f5de2..01b1c5d9 100644 --- a/server/stateevaluator.cpp +++ b/server/stateevaluator.cpp @@ -19,6 +19,21 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! + \class guhserver::StateEvaluator + \brief This class helps to evaluate a \l{State} and . + + \ingroup rules + \inmodule core + + The \l StateEvaluator class helps to evaluate a \l StateDescriptor and check if all \l {State}{States} + from the given \l StateDescriptor are valid. A \l StateDescriptor is valid if conditions of the + \l StateDescriptor are true. + + \sa StateDescriptor, State, RuleEngine +*/ + + #include "stateevaluator.h" #include "guhcore.h" #include "devicemanager.h" @@ -27,6 +42,7 @@ namespace guhserver { +/*! Constructs a new StateEvaluator for the given \a stateDescriptor. */ StateEvaluator::StateEvaluator(const StateDescriptor &stateDescriptor): m_stateDescriptor(stateDescriptor), m_operatorType(Types::StateOperatorAnd) @@ -34,6 +50,7 @@ StateEvaluator::StateEvaluator(const StateDescriptor &stateDescriptor): } +/*! Constructs a new StateEvaluator for the given \a childEvaluators and \a stateOperator. */ StateEvaluator::StateEvaluator(QList childEvaluators, Types::StateOperator stateOperator): m_stateDescriptor(), m_childEvaluators(childEvaluators), @@ -41,36 +58,46 @@ StateEvaluator::StateEvaluator(QList childEvaluators, Types::Sta { } +/*! Returns the \l StateDescriptor of this \l StateEvaluator. */ StateDescriptor StateEvaluator::stateDescriptor() const { return m_stateDescriptor; } +/*! Returns the list of child \l {StateEvaluator}{StateEvaluators} of this \l StateEvaluator. */ QList StateEvaluator::childEvaluators() const { return m_childEvaluators; } +/*! Sets the list of child evaluators of this \l StateEvaluator to the given \a stateEvaluators.*/ void StateEvaluator::setChildEvaluators(const QList &stateEvaluators) { m_childEvaluators = stateEvaluators; } +/*! Appends the given \a stateEvaluator to the child evaluators of this \l StateEvaluator. + \sa childEvaluators() +*/ void StateEvaluator::appendEvaluator(const StateEvaluator &stateEvaluator) { m_childEvaluators.append(stateEvaluator); } +/*! Returns the \l {Types::StateOperator}{StateOperator} for this \l StateEvaluator.*/ Types::StateOperator StateEvaluator::operatorType() const { return m_operatorType; } +/*! Sets the \l {Types::StateOperator}{StateOperator} for this \l StateEvaluator to the given. + * \a operatorType. This operator will be used to evaluate the child evaluator list.*/ void StateEvaluator::setOperatorType(Types::StateOperator operatorType) { m_operatorType = operatorType; } +/*! Returns true, if all child evaluator conditions are true depending on the \l {Types::StateOperator}{StateOperator}.*/ bool StateEvaluator::evaluate() const { if (m_stateDescriptor.isValid()) { @@ -106,6 +133,7 @@ bool StateEvaluator::evaluate() const return true; } +/*! Returns true if this \l StateEvaluator has a \l Device in it with the given \a deviceId. */ bool StateEvaluator::containsDevice(const DeviceId &deviceId) const { if (m_stateDescriptor.deviceId() == deviceId) { @@ -119,6 +147,7 @@ bool StateEvaluator::containsDevice(const DeviceId &deviceId) const return false; } +/*! Removes a \l Device with the given \a deviceId from this \l StateEvaluator. */ void StateEvaluator::removeDevice(const DeviceId &deviceId) { if (m_stateDescriptor.deviceId() == deviceId) { @@ -129,6 +158,8 @@ void StateEvaluator::removeDevice(const DeviceId &deviceId) } } +/*! This method will be used to save this \l StateEvaluator to the given \a settings. + The \a groupName will normally be the corresponding \l Rule. */ void StateEvaluator::dumpToSettings(GuhSettings &settings, const QString &groupName) const { settings.beginGroup(groupName); @@ -151,6 +182,8 @@ void StateEvaluator::dumpToSettings(GuhSettings &settings, const QString &groupN settings.endGroup(); } +/*! This method will be used to load a \l StateEvaluator from the given \a settings. + The \a groupName will be the corresponding \l RuleId. Returns the loaded \l StateEvaluator. */ StateEvaluator StateEvaluator::loadFromSettings(GuhSettings &settings, const QString &groupName) { settings.beginGroup(groupName);