From a7bbba1999aba05d90c57c6f4cb8c5b437ba9ea0 Mon Sep 17 00:00:00 2001 From: Michael Zanetti Date: Sun, 26 Jan 2014 03:54:30 +0100 Subject: [PATCH] moar docs --- Hive.pro | 2 +- doc/allclasses.qdoc | 6 + doc/deviceplugins.qdoc | 11 + doc/hive.qdoc | 15 +- doc/html-styles.qdocconf | 12 - doc/html-template.qdocconf | 2 +- doc/rules.qdoc | 7 + doc/style.css | 673 ++++++++++++++++++++++++++++++++++++ libhive/action.cpp | 15 + libhive/actiontype.cpp | 9 + libhive/device.cpp | 13 + libhive/deviceclass.cpp | 16 + libhive/devicemanager.cpp | 14 + libhive/deviceplugin.cpp | 82 +++++ libhive/deviceplugin.h | 6 +- libhive/state.cpp | 11 +- libhive/statetype.cpp | 10 + libhive/trigger.cpp | 15 + libhive/triggertype.cpp | 22 ++ libhive/types.qdoc | 8 +- server/jsonrpc/jsonrpc.qdoc | 10 +- server/rule.cpp | 18 +- server/rule.h | 2 +- server/ruleengine.cpp | 16 +- server/ruleengine.h | 2 +- 25 files changed, 957 insertions(+), 40 deletions(-) create mode 100644 doc/allclasses.qdoc create mode 100644 doc/deviceplugins.qdoc create mode 100644 doc/rules.qdoc create mode 100644 doc/style.css diff --git a/Hive.pro b/Hive.pro index 9eb74578..88709e3f 100644 --- a/Hive.pro +++ b/Hive.pro @@ -6,5 +6,5 @@ server.depends = libhive plugins plugins.depends = libhive docs.depends = libhive server -docs.commands = cd doc; qdoc config.qdocconf +docs.commands = cd ${PWD}; qdoc config.qdocconf QMAKE_EXTRA_TARGETS += docs diff --git a/doc/allclasses.qdoc b/doc/allclasses.qdoc new file mode 100644 index 00000000..23033287 --- /dev/null +++ b/doc/allclasses.qdoc @@ -0,0 +1,6 @@ +/*! + \page classes.html + \title All Hive Classes + + \generatelist classes +*/ diff --git a/doc/deviceplugins.qdoc b/doc/deviceplugins.qdoc new file mode 100644 index 00000000..d8b679fa --- /dev/null +++ b/doc/deviceplugins.qdoc @@ -0,0 +1,11 @@ +/*! + \page deviceplugins.html + \title Device Plugins + + \brief This is the API for implementing Hive device plugins. + + When creating a device plugin, start by subclassing \l{DevicePlugin} and filling + in information for the pure virtual methods. + + \annotatedlist devices +*/ diff --git a/doc/hive.qdoc b/doc/hive.qdoc index 77023c33..84c23f3c 100644 --- a/doc/hive.qdoc +++ b/doc/hive.qdoc @@ -1,22 +1,27 @@ /*! \page index.html - \title Hive + \title Hive Developer Documentation \section1 Summary - The hive backend service consists of three main modules: + The Hive backend service consists of three main modules: \list \li libhive \list - \li \l{Types} used in the hive system - \li Defines plugin API and plugin loading mechanism + \li \l{Types}{Types used in the hive system} + \li \l{Device Plugins}{The Device Plugin API} \endlist \li Hive server \list \li Hive core \li \l{JSONRPC Interface} - \li Rules engine + \li \l{Rules} \endlist \li Device plugins. A collection of officially supported device plugins. \endlist + + \section2 Quicklinks + \list + \li \l{All Hive Classes} + \endlist */ diff --git a/doc/html-styles.qdocconf b/doc/html-styles.qdocconf index 5c16c5df..a839c745 100644 --- a/doc/html-styles.qdocconf +++ b/doc/html-styles.qdocconf @@ -7,18 +7,6 @@ HTML.templatedir = . HTML.stylesheets = style.css HTML.scripts = - -# Files not referenced in any qdoc file (last four needed by qtdemo) -# See also qhp.Qt.extraFiles -extraimages.HTML = qt-logo.png \ - arrow_down.png \ - breadcrumb.png \ - bullet_gt.png \ - bullet_dn.png \ - bullet_sq.png \ - bullet_up.png \ - horBar.png \ - sprites-combined.png # Include the style sheets and scripts used. diff --git a/doc/html-template.qdocconf b/doc/html-template.qdocconf index 44c36680..4e9c791a 100644 --- a/doc/html-template.qdocconf +++ b/doc/html-template.qdocconf @@ -3,7 +3,7 @@ include(html-styles.qdocconf) HTML.postheader = \ "
\n" \ "
\n" \ - " Hive Documentation\n" \ + " Hive Developer Documentation\n" \ "
\n" \ "
\n" \ "
    \n" \ diff --git a/doc/rules.qdoc b/doc/rules.qdoc new file mode 100644 index 00000000..010027e2 --- /dev/null +++ b/doc/rules.qdoc @@ -0,0 +1,7 @@ +/*! + \page rules.html + \title Rules + + \annotatedlist rules +*/ + diff --git a/doc/style.css b/doc/style.css new file mode 100644 index 00000000..8ec0abb4 --- /dev/null +++ b/doc/style.css @@ -0,0 +1,673 @@ +@media screen +{ + +/* basic elements */ + html + { + color: #000000; + background: #ffed5d; + } + table + { + border-collapse: collapse; + border-spacing: 0; + } + fieldset, img + { + border: 0; + max-width:100%; + } + address, caption, cite, code, dfn, em, strong, th, var, optgroup + { + font-style: inherit; + font-weight: inherit; + } + del, ins + { + text-decoration: none; + } + li + { + list-style: none; + } + ol li + { + list-style: decimal; + } + caption, th + { + text-align: left; + } + h1, h2, h3, h4, h5, h6 + { + font-size: 100%; + } + q:before, q:after + { + content: ''; + } + abbr, acronym + { + border: 0; + font-variant: normal; + } + sup, sub + { + vertical-align: baseline; + } + tt, .qmlreadonly span, .qmldefault span + { + word-spacing:0.5em; + } + legend + { + color: #000000; + } + strong + { + font-weight: bold; + } + em + { + font-style: italic; + } + + body + { + margin-left: 0.5em; + margin-right: 0.5em; + } + a + { + color: #00732F; + text-decoration: none; + } + hr + { + background-color: #E6E6E6; + border: 1px solid #E6E6E6; + height: 1px; + width: 100%; + text-align: left; + margin: 1.5em 0 1.5em 0; + } + + pre + { + border: 1px solid #DDDDDD; + -moz-border-radius: 0.7em 0.7em 0.7em 0.7em; + -webkit-border-radius: 0.7em 0.7em 0.7em 0.7em; + border-radius: 0.7em 0.7em 0.7em 0.7em; + margin: 0 1.5em 1em 1em; + padding: 1em 1em 1em 1em; + overflow-x: auto; + } + table, pre + { + -moz-border-radius: 0.7em 0.7em 0.7em 0.7em; + -webkit-border-radius: 0.7em 0.7em 0.7em 0.7em; + border-radius: 0.7em 0.7em 0.7em 0.7em; + background-color: #F6F6F6; + border: 1px solid #E6E6E6; + border-collapse: separate; + margin-bottom: 2.5em; + } + pre { + font-size: 90%; + display: block; + overflow:hidden; + } + thead + { + margin-top: 0.5em; + font-weight: bold + } + th + { + padding: 0.5em 1.5em 0.5em 1.5em; + background-color: #E1E1E1; + border-left: 1px solid #E6E6E6; + } + td + { + padding: 0.25em 1.5em 0.25em 2em; + } + + td.rightAlign + { + padding: 0.25em 0.5em 0.25em 1em; + } + table tr.odd + { + border-left: 1px solid #E6E6E6; + background-color: #F6F6F6; + color: #66666E; + } + table tr.even + { + border-left: 1px solid #E6E6E6; + background-color: #ffffff; + color: #66666E; + } + + div.float-left + { + float: left; margin-right: 2em + } + div.float-right + { + float: right; margin-left: 2em + } + + span.comment + { + color: #008B00; + font-style: italic + } + span.string, span.char + { + color: #000084; + } + span.number + { + color: #a46200; + } + span.operator + { + color: #202020; + } + span.keyword + { + color: #840000; + } + span.name + { + color: black + } + span.type + { + font-weight: bold + } + span.type a:visited + { + color: #0F5300; + } + span.preprocessor + { + color: #404040 + } +/* end basic elements */ + +/* font style elements */ + .heading + { + font-weight: bold; + font-size: 125%; + } + .subtitle + { + font-size: 110% + } + .small-subtitle + { + font-size: 100% + } + .red + { + color:red; + } +/* end font style elements */ + +/* global settings*/ + .header, .footer + { + display: block; + clear: both; + overflow: hidden; + } +/* end global settings*/ + +/* header elements */ + .header .qtref + { + color: #00732F; + font-weight: bold; + font-size: 130%; + } + + .header .content + { + margin-bottom: 0.5em + } + + .naviNextPrevious + { + display: none + } + .header .breadcrumb + { + font-size: 90%; + padding: 0.5em 0 0.5em 1em; + margin: 0; + background-color: #fafafa; + height: 1.35em; + border-bottom: 1px solid #d1d1d1; + } + + .header .breadcrumb ul + { + margin: 0; + padding: 0; + } + + .header .content + { + word-wrap: break-word; + } + + .header .breadcrumb ul li + { + float: left; + background: url(../images/breadcrumb.png) no-repeat 0 3px; + padding-left: 1.5em; + margin-left: 1.5em; + } + + .header .breadcrumb ul li.last + { + font-weight: normal; + } + + .header .breadcrumb ul li a + { + color: #00732F; + } + + .header .breadcrumb ul li.first + { + background-image: none; + padding-left: 0; + margin-left: 0; + } + + .header .content ol li { + background: none; + margin-bottom: 1.0em; + margin-left: 1.2em; + padding-left: 0 + } + + .header .content li + { + background: url(../images/bullet_sq.png) no-repeat 0 5px; + margin-bottom: 1em; + padding-left: 1.2em; + } + +/* end header elements */ + +/* content elements */ + .content h1 + { + font-weight: bold; + font-size: 150% + } + + .content h2 + { + font-weight: bold; + font-size: 135%; + width: 100%; + } + .content h3 + { + font-weight: bold; + font-size: 120%; + width: 100%; + } + .content table p + { + margin: 0 + } + .content ul + { + padding-left: 2.5em; + } + .content li + { + padding-top: 0.25em; + padding-bottom: 0.25em; + } + .content ul img { + vertical-align: middle; + } + + .content a:visited + { + color: #4c0033; + text-decoration: none; + } + + .content a:visited:hover + { + color: #4c0033; + text-decoration: underline; + } + + a:hover + { + color: #4c0033; + text-decoration: underline; + } + descr p a + { + text-decoration: underline; + } + + .descr p a:visited + { + text-decoration: underline; + } + + .alphaChar{ + width:95%; + background-color:#F6F6F6; + border:1px solid #E6E6E6; + -moz-border-radius: 7px 7px 7px 7px; + border-radius: 7px 7px 7px 7px; + -webkit-border-radius: 7px 7px 7px 7px; + font-size:12pt; + padding-left:10px; + margin-top:10px; + margin-bottom:10px; + } + .flowList{ + /*vertical-align:top;*/ + /*margin:20px auto;*/ + + column-count:3; + -webkit-column-count:3; + -moz-column-count:3; +/* + column-width:100%; + -webkit-column-width:200px; + -col-column-width:200px; +*/ + column-gap:41px; + -webkit-column-gap:41px; + -moz-column-gap:41px; + + column-rule: 1px dashed #ccc; + -webkit-column-rule: 1px dashed #ccc; + -moz-column-rule: 1px dashed #ccc; + } + + .flowList dl{ + } + .flowList dd{ + /*display:inline-block;*/ + margin-left:10px; + min-width:250px; + line-height: 1.5; + min-width:100%; + min-height:15px; + } + + .flowList dd a{ + } + + .content .flowList p{ + padding:0px; + } + + .content .alignedsummary + { + margin: 15px; + } + + + .qmltype + { + text-align: center; + font-size: 120%; + } + .qmlreadonly + { + padding-left: 5px; + float: right; + color: #254117; + } + + .qmldefault + { + padding-left: 5px; + float: right; + color: red; + } + + .qmldoc + { + } + + .generic .alphaChar{ + margin-top:5px; + } + + .generic .odd .alphaChar{ + background-color: #F6F6F6; + } + + .generic .even .alphaChar{ + background-color: #FFFFFF; + } + + .memItemRight{ + padding: 0.25em 1.5em 0.25em 0; + } + .highlightedCode + { + margin: 1.0em; + } + .annotated td { + padding: 0.25em 0.5em 0.25em 0.5em; + } + + .header .content .toc ul + { + padding-left: 0px; + } + + .content .toc h3 { + border-bottom: 0px; + margin-top: 0px; + } + + .content .toc h3 a:hover { + color: #00732F; + text-decoration: none; + } + + .content .toc .level2 + { + margin-left: 1.5em; + } + + .content .toc .level3 + { + margin-left: 3.0em; + } + + .content ul li + { + background: url(../images/bullet_sq.png) no-repeat 0 0.7em; + padding-left: 1em + } + + .content .toc li + { + background: url(../images/bullet_dn.png) no-repeat 0 5px; + padding-left: 1em + } + + .relpage + { + -moz-border-radius: 7px 7px 7px 7px; + -webkit-border-radius: 7px 7px 7px 7px; + border-radius: 7px 7px 7px 7px; + border: 1px solid #DDDDDD; + padding: 25px 25px; + clear: both; + } + .relpage ul + { + float: none; + padding: 1.5em; + } + + h3.fn, span.fn + { + -moz-border-radius:7px 7px 7px 7px; + -webkit-border-radius:7px 7px 7px 7px; + border-radius:7px 7px 7px 7px; + background-color: #F6F6F6; + border-width: 1px; + border-style: solid; + border-color: #E6E6E6; + font-weight: bold; + word-spacing:3px; + padding:3px 5px; + } + + .functionIndex { + font-size:12pt; + word-spacing:10px; + margin-bottom:10px; + background-color: #F6F6F6; + border-width: 1px; + border-style: solid; + border-color: #E6E6E6; + -moz-border-radius: 7px 7px 7px 7px; + -webkit-border-radius: 7px 7px 7px 7px; + border-radius: 7px 7px 7px 7px; + width:100%; + } + + .centerAlign + { + text-align:center; + } + + .rightAlign + { + text-align:right; + } + + .leftAlign + { + text-align:left; + } + + .topAlign{ + vertical-align:top + } + + .functionIndex a{ + display:inline-block; + } + +/* end content elements */ +/* footer elements */ + + .footer + { + color: #393735; + font-size: 0.75em; + text-align: center; + padding-top: 1.5em; + padding-bottom: 1em; + background-color: #E6E7E8; + margin: 0; + } + .footer p + { + margin: 0.25em + } + .small + { + font-size: 0.5em; + } +/* end footer elements */ + + .item { + float: left; + position: relative; + width: 100%; + overflow: hidden; + } + + + .item .primary { + margin-right: 220px; + position: relative; + } + + .item hr { + margin-left: -220px; + } + + .item .secondary { + float: right; + width: 200px; + position: relative; + } + + .item .cols { + clear: both; + display: block; + } + + .item .cols .col { + float: left; + margin-left: 1.5%; + } + + .item .cols .col.first { + margin-left: 0; + } + + .item .cols.two .col { + width: 45%; + } + + .item .box { + margin: 0 0 10px 0; + } + + .item .box h3 { + margin: 0 0 10px 0; + } + + .cols.unclear { + clear:none; + } +} + +/* end of screen media */ + +/* start of print media */ + +@media print +{ + input, textarea, .header, .footer, .toolbar, .feedback, .wrapper .hd, .wrapper .bd .sidebar, .wrapper .ft, #feedbackBox, #blurpage, .toc, .breadcrumb, .toolbar, .floatingResult + { + display: none; + background: none; + } + .content + { + background: none; + display: block; + width: 100%; margin: 0; float: none; + } +} +/* end of print media */ diff --git a/libhive/action.cpp b/libhive/action.cpp index 048ed9e2..dc08bd87 100644 --- a/libhive/action.cpp +++ b/libhive/action.cpp @@ -1,3 +1,17 @@ +/*! + \class Action + \brief Holds information required to execute an action described by a \l{ActionType}. + + \ingroup types + \inmodule libhive + + It is bound to a \l{Device} and an \l{ActionType} and holds the parameters + for the execution of the action. + + The params must match the template as described in \l{ActionType}. + + \sa Device, ActionType +*/ #include "action.h" Action::Action(const QUuid &deviceId, const QUuid &actionTypeId) : @@ -6,6 +20,7 @@ Action::Action(const QUuid &deviceId, const QUuid &actionTypeId) : { } +/*! An Action is valid if \l{actionTypeId} and \l{deviceId} are valid uuids. */ bool Action::isValid() const { return !m_actionTypeId.isNull() && !m_deviceId.isNull(); diff --git a/libhive/actiontype.cpp b/libhive/actiontype.cpp index d63ded1a..2ec05fbf 100644 --- a/libhive/actiontype.cpp +++ b/libhive/actiontype.cpp @@ -1,3 +1,12 @@ +/*! + \class ActionType + \brief Describes an \l{Action} for a \l{Device}. + + \ingroup types + + \sa Action +*/ + #include "actiontype.h" ActionType::ActionType(const QUuid &id): diff --git a/libhive/device.cpp b/libhive/device.cpp index 9cfd0718..44563a24 100644 --- a/libhive/device.cpp +++ b/libhive/device.cpp @@ -1,3 +1,16 @@ +/*! + \class Device + \brief A Device represents a installed and configured hardware device. + + \ingroup devices + \inmodule libhive + + This class holds the values for configured devices. It is associated with a \{DeviceClass} which + can be used to get more details about the device. + + \sa DeviceClass +*/ + #include "device.h" #include diff --git a/libhive/deviceclass.cpp b/libhive/deviceclass.cpp index dbcd74ae..122d1a32 100644 --- a/libhive/deviceclass.cpp +++ b/libhive/deviceclass.cpp @@ -1,3 +1,19 @@ +/*! + \class DeviceClass + \brief Describes \l{Device}{Devices}. + + \ingroup devices + \inmodule libhive + + It holds information general information about devices and their vendors and + describes what actions, triggers and states a device supports. As this is + just a description of device and does not represent actual \l{Device}{Devices}, + the actions, triggers and states are described in form of \l{TriggerType}, + \l{StateType} and \l{ActionType} + + \sa Device +*/ + #include "deviceclass.h" DeviceClass::DeviceClass(const QUuid &pluginId, const QUuid &id): diff --git a/libhive/devicemanager.cpp b/libhive/devicemanager.cpp index cd8af0e3..fe9899ed 100644 --- a/libhive/devicemanager.cpp +++ b/libhive/devicemanager.cpp @@ -1,3 +1,17 @@ +/*! + \class DeviceManager + \brief The main entry point when interacting with \l{Device}{Devices} + + \ingroup devices + \inmodule libhive + + The DeviceManager holds all information about supported and configured Devices in the system. + + It is also responsible for loading Plugins and managing common hardware resources between + \l{DevicePlugin}{device plugins}. + +*/ + #include "devicemanager.h" #include "radio433.h" diff --git a/libhive/deviceplugin.cpp b/libhive/deviceplugin.cpp index 2541d64c..6e86da44 100644 --- a/libhive/deviceplugin.cpp +++ b/libhive/deviceplugin.cpp @@ -1,3 +1,15 @@ +/*! + \class DevicePlugin + \brief This is the base class interface for device plugins. + + \ingroup devices + \inmodule libhive + + When implementing a new plugin, start by subclassing this and implementing the following + pure virtual methods: \l{DevicePlugin::pluginName()}, \l{DevicePlugin::pluginId()}, + \l{DevicePlugin::supportedDevices()} and \l{DevicePlugin::requiredHardware()} +*/ + #include "deviceplugin.h" #include "devicemanager.h" @@ -5,6 +17,54 @@ #include +/*! + \fn QString DevicePlugin::pluginName() const + Return the name of the plugin. A String presented to the user. + */ + +/*! + \fn QUuid DevicePlugin::pluginId() const + When implementing a plugin, generate a new uuid and return it here. Always return the + same uuid and don't change it or configurations can't be matched any more. + */ + +/*! + \fn QList DevicePlugin::supportedDevices() const + Return a list of \l{DeviceClass}{DeviceClasses} describing all the devices supported by this plugin. + */ + +/*! + \fn DeviceManager::HardwareResources DevicePlugin::requiredHardware() const + Return flags describing the common hardware resources required by this plugin. + \sa DevicePlugin::transmitData(), DevicePlugin::radioData(), DevicePlugin::hiveTimer() + */ + +/*! + \fn void DevicePlugin::radioData(QList 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. + */ + +/*! + \fn void DevicePlugin::hiveTimer() + If the plugin has requested the timer using \l{DevicePlugin::requiredHardware()}, this slot will be called + on timer events. + */ + +/*! + \fn void DevicePlugin::executeAction(Device *device, const Action &action) + This will be called to actually execute actions on the hardware. The \{Device} and + the \{Action} are contained in the \a device and \a action parameters. + */ + +/*! + \fn void DevicePlugin::emitTrigger(const Trigger &trigger) + Emit this to produce a \l{Trigger} in the system. Usually in response to incoming data, + such as \l{DevicePlugin::radioData()} or \l{DevicePlugin::hiveTimer()}. Find a + configured \l{Device} from the \l{DeviceManager} and get its \l{TriggerTypes}, then + create a \l{Trigger} complying to that \l{TriggerType} and emit it here. + */ + DevicePlugin::DevicePlugin(): m_deviceManager(0) { @@ -22,22 +82,44 @@ void DevicePlugin::initPlugin(DeviceManager *deviceManager) init(); } +/*! + Returns a map containing the plugin configuration. + + When implementing a new plugin, override this and fill in the empty configuration if your plugin requires any. + */ QVariantMap DevicePlugin::configuration() const { return QVariantMap(); } +/*! + Will be called by the DeviceManager to set a plugin's config. + + When implementing a new plugin, override this and react to configuration changes. + + TODO: Still need to define a common format for the config. + */ void DevicePlugin::setConfiguration(const QVariantMap &configuration) { Q_UNUSED(configuration) qWarning() << "Plugin" << pluginName() << pluginId() << "does not support any configuration"; } +/*! + Returns a pointer to the \l{DeviceManager}. + + When implementing a plugin, use this to find the \l{Device}{Devices} you need. + */ + DeviceManager *DevicePlugin::deviceManager() const { return m_deviceManager; } +/*! + Transmits data on the Radio433 or Radio868 devices, depending on the hardware requested by this plugin. + \sa DevicePlugin::requiredHardware() + */ void DevicePlugin::transmitData(QList rawData) { switch (requiredHardware()) { diff --git a/libhive/deviceplugin.h b/libhive/deviceplugin.h index eec5cb59..5f25cfc7 100644 --- a/libhive/deviceplugin.h +++ b/libhive/deviceplugin.h @@ -18,8 +18,6 @@ public: DevicePlugin(); virtual ~DevicePlugin(); - void initPlugin(DeviceManager *deviceManager); - virtual void init() {} virtual QString pluginName() const = 0; @@ -48,7 +46,11 @@ protected: void transmitData(QList rawData); private: + void initPlugin(DeviceManager *deviceManager); + DeviceManager *m_deviceManager; + + friend class DeviceManager; }; Q_DECLARE_INTERFACE(DevicePlugin, "org.hiveyourhome.DevicePlugin") diff --git a/libhive/state.cpp b/libhive/state.cpp index 1c6f9519..d3a5cade 100644 --- a/libhive/state.cpp +++ b/libhive/state.cpp @@ -1,11 +1,14 @@ /*! \class State - \brief The container class for States. - \inmodule Types + \brief Holds the parameters of a State of a \l{Device}. \ingroup types + \inmodule libhive - Lorem ipsum + States hold the state values for devices. A State is associated to a \l{Device} by + the \l{Device::deviceId} {deviceId} and represents the value of a state described in a \l{StateType} + + \sa StateType */ #include "state.h" @@ -16,11 +19,13 @@ State::State(const QUuid &stateTypeId, const QUuid &deviceId): { } +/*! Returns the id of the StateType describing this State. */ QUuid State::stateTypeId() const { return m_stateTypeId; } +/*! Returns the id of the StateType describing this State. */ QUuid State::deviceId() const { return m_deviceId; diff --git a/libhive/statetype.cpp b/libhive/statetype.cpp index 016bd028..004fa4d4 100644 --- a/libhive/statetype.cpp +++ b/libhive/statetype.cpp @@ -1,3 +1,13 @@ +/*! + \class StateType + \brief Describes a \l{State} for a \l{Device}. + + \ingroup types + \inmodule libhive + + \sa State +*/ + #include "statetype.h" StateType::StateType(const QUuid &id): diff --git a/libhive/trigger.cpp b/libhive/trigger.cpp index d157bf34..403ae640 100644 --- a/libhive/trigger.cpp +++ b/libhive/trigger.cpp @@ -1,3 +1,18 @@ +/*! + \class Trigger + \brief Holds information required to emit a trigger described by a \l{TriggerType}. + + \ingroup types + \inmodule libhive + + It is bound to a \l{Device} and a \l{TriggerType} and holds the parameters + for the event that happened. + + The params must match the template as described in \l{TriggerType}. + + \sa Device TriggerType +*/ + #include "trigger.h" Trigger::Trigger(const QUuid &triggerTypeId, const QUuid &deviceId, const QVariantMap ¶ms): diff --git a/libhive/triggertype.cpp b/libhive/triggertype.cpp index 59725174..5f2b8cdb 100644 --- a/libhive/triggertype.cpp +++ b/libhive/triggertype.cpp @@ -1,30 +1,52 @@ +/*! + \class TriggerType + \brief Describes a \l{Trigger} for a \l{Device}. + + \ingroup types + \inmodule libhive + + \sa Trigger +*/ + #include "triggertype.h" +/*! Constructs a TriggerType object with the given id. */ TriggerType::TriggerType(const QUuid &id): m_id(id) { } +/*! Returns the id. */ QUuid TriggerType::id() const { return m_id; } +/*! Returns the name of this TriggerType, e.g. "Temperature changed" */ QString TriggerType::name() const { return m_name; } +/*! Set a name for this TriggerType, e.g. "Temperature changed" */ void TriggerType::setName(const QString &name) { m_name = name; } +/*! + Holds a map describing possible parameters for a \l{Trigger} of this TriggerType. + e.g. QVariantList(QVariantMap(("name", "temperature"), ("type": QVariant::Real))) + */ QVariantList TriggerType::parameters() const { return m_parameters; } +/*! + Set the parameter description for this TriggerType, + e.g. QVariantList(QVariantMap(("name", "temperature"), ("type": QVariant::Real))) + */ void TriggerType::setParameters(const QVariantList ¶meters) { m_parameters = parameters; diff --git a/libhive/types.qdoc b/libhive/types.qdoc index d3ee3463..f1ff8f2d 100644 --- a/libhive/types.qdoc +++ b/libhive/types.qdoc @@ -1,12 +1,6 @@ /*! \page types.html \title Types - \nextpage - libhive types: - \list - \li \c State - \li \c Trigger - \li \c Action - \endlist + \annotatedlist types */ diff --git a/server/jsonrpc/jsonrpc.qdoc b/server/jsonrpc/jsonrpc.qdoc index f7b10766..e7e8e4bf 100644 --- a/server/jsonrpc/jsonrpc.qdoc +++ b/server/jsonrpc/jsonrpc.qdoc @@ -12,20 +12,20 @@ The JSON message protocol communicates by exchanging JSON Objects with the following properties: \list - \li \c "id": \c integer + \li \code "id": integer \endcode The id should be a unique identifier for the message. Any server response will contain the same id allowing to match responses to requests/commands. This parameter is mandatory. - \li "method": string + \li \code "method": string \endcode The method field holds the method to be executed. Methods are grouped into namespaces. The method string consists of two parts, the namespace and the method name, separated by a dot. This parameter is mandatory. - (Example: "JSONRPC.Introspect") - \li "params": Object + (Example: \c"JSONRPC.Introspect") + \li \code "params": object \endcode The params contains any JSON object. This parameter is optional and differs according to the requested method. \endlist - The JSONRPC API is self documenting and can be introspected by calling JSONRPC.Introspect. + The JSONRPC API is self documenting and can be introspected by calling \c"JSONRPC.Introspect". \section1 Communicating with the server The server listens on TCP port 1234 for incoming TCP connections. It will respond to incoming diff --git a/server/rule.cpp b/server/rule.cpp index 8b21ffa9..7bba6b33 100644 --- a/server/rule.cpp +++ b/server/rule.cpp @@ -1,8 +1,24 @@ +/*! + \class Rule + \brief This class represents a rule. + + \ingroup rules + \inmodule server + + A \l{Rule} is always triggered by a \l{Trigger}, 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. + + \sa Trigger, State, Action +*/ + #include "rule.h" #include -Rule::Rule(const QUuid &id, const Trigger &trigger, const QList states, const QList &actions): +Rule::Rule(const QUuid &id, const Trigger &trigger, const QList &states, const QList &actions): m_id(id), m_trigger(trigger), m_states(states), diff --git a/server/rule.h b/server/rule.h index 12c4a37e..38b64628 100644 --- a/server/rule.h +++ b/server/rule.h @@ -15,7 +15,7 @@ public: RuleTypeAny }; - Rule(const QUuid &id, const Trigger &trigger, const QList states, const QList &actions); + Rule(const QUuid &id, const Trigger &trigger, const QList &states, const QList &actions); QUuid id() const; Trigger trigger() const; diff --git a/server/ruleengine.cpp b/server/ruleengine.cpp index 9597733e..b798b0f9 100644 --- a/server/ruleengine.cpp +++ b/server/ruleengine.cpp @@ -1,3 +1,17 @@ +/*! + \class RuleEngine + \brief The Engine that evaluates \l{Rule}{Rules} and finds + \l{Action}{Actions} to be executed. + + \ingroup rules + \inmodule server + + You can add, remove and update rules and query the engine for actions to be executed + for a given \l{Trigger}. + + \sa Trigger, Rule, Action +*/ + #include "ruleengine.h" #include "hivecore.h" @@ -88,7 +102,7 @@ RuleEngine::RuleError RuleEngine::addRule(const Trigger &trigger, const QList(), actions); } -RuleEngine::RuleError RuleEngine::addRule(const Trigger &trigger, const QList states, const QList &actions) +RuleEngine::RuleError RuleEngine::addRule(const Trigger &trigger, const QList &states, const QList &actions) { qDebug() << "adding rule: Trigger:" << trigger.triggerTypeId() << "with" << actions.count() << "actions"; DeviceClass triggerDeviceClass = HiveCore::instance()->deviceManager()->findDeviceClassforTrigger(trigger.triggerTypeId()); diff --git a/server/ruleengine.h b/server/ruleengine.h index 63e0dd1d..ff2fabc3 100644 --- a/server/ruleengine.h +++ b/server/ruleengine.h @@ -24,7 +24,7 @@ public: QList evaluateTrigger(const Trigger &trigger); RuleError addRule(const Trigger &trigger, const QList &actions); - RuleError addRule(const Trigger &trigger, const QList states, const QList &actions); + RuleError addRule(const Trigger &trigger, const QList &states, const QList &actions); QList rules() const; RuleError removeRule(const QUuid &ruleId);