add docs for interfaces

.gitignore

@@ -8,3 +8,4 @@ doc/html
 snap/parts/
 snap/prime/
 snap/stage/
+doc/interfacelist.qdoc

doc/interfaces.qdoc

@@ -0,0 +1,37 @@
+/*!
+    \page interfaces.html
+    \brief Interfaces define how a DeviceClass behaves
+
+    \section1 Interfaces for DeviceClasses
+
+    When creating a DeviceClass, the interfaces field can be used to specify a list of interfaces this DeviceClass implements.
+
+    When implementing an interface, the DeviceClass must follow the interface specification for the according interface. This means
+    the DeviceClass needs to have at least all the \l{StateType}{states}, \l{ActionType}{actions} and \l{EventType}{events} the given interface requires. A DeviceClass may
+    add custom states, actions or events, or even implement multiple interfaces.
+
+    The main purpose of interfaces is to provide for a better user experience. Using interfaces, a plugin developer can suggest the
+    ui to be used for this DeviceClass. For example, having a plugin that can control a dimmable light would likely have a state
+    named "powered" of type boolean and one named "brightness" of type int, ranging from 0 to 100%. Having just this information,
+    the ui would create a generic switch component to flip the bool state and a generic slider component to allow adjusting the
+    brightness because it can't know what the actual switch or slider do. For a better user experience though, the plugin developer
+    could just add the interface "dimmedlight" to this deviceclass and this way tell the ui that this actually is a dimmed light.
+    The ui can use this information to paint a pretty brightness slider, and implicitly flip the power switch off when the brightness
+    slider is moved to the lower end.
+
+    Another purpose of interfaces is to help the ui grouping and managing device classes. For example the \l {gateway} interface does
+    not require to implement any properties, however, it tells the ui that this is a gateway and thus not relevant to show to the
+    user in the main control entity. Instead, gateways might be listed in the configuration section of the client application.
+
+    In general it is a good idea to follow as many interfaces as precicely as possible in order to provide for the best user experience.
+
+    A interface can extend another interface. For example, the \l {light} interface only requires one state called powered of type bool.
+    A dimmablelight extends this type and adds a brightness property to it. This means, if a DeviceClass implements \l {dimmablelight}, it
+    also needs to cater for the \l {light} interface's states.
+
+
+    \section1 Currently available interfaces
+    \include interfacelist.qdoc
+
+
+*/

doc/plugin-json.qdoc

@@ -141,6 +141,7 @@
                             "idName": "deviceClassName",
                             "id": "uuid",
                             "o:deviceIcon": "Icon",
+                            "o:interfaces": [ "String" ],
                             "o:basicTags": [
                                 "BasicTag"
                             ],
@@ -174,6 +175,7 @@
         \li - \underline{\e name:} The visible name of the \l{DeviceClass} \unicode{0x2192} \l{DeviceClass::name()}.
         \li - \underline{\e idName:} This parameter will be used to define the DeviceClassId variable named <idName>DeviceClassId in the plugininfo.h, so it can be used in the code.
         \li - \underline{\e id:} The actual uuid (\l{DeviceClassId}) of the \l{DeviceClass} \unicode{0x2192} \l{DeviceClass::id()}.
+        \li - \underline{\e interfaces: } A list of \l{Interfaces for DeviceClasses}{interfaces} this plugin implements.
         \li - \underline{\e basicTags:} A list of \l{DeviceClass::BasicTag}{BasicTags} for this device \unicode{0x2192} \l{DeviceClass::basicTags()}. A \l{DeviceClass} can have multiple \l{DeviceClass::BasicTag}{BasicTags} which describe the basic category of the DeviceClass. A \l{DeviceClass} should be eighter a Service or a Device, never both. See enum \l{DeviceClass::BasicTag} for more information. The expected value for the \e basicTags parameters matches the enum name like this:
 
         \tt {DeviceClass::BasicTagService} \unicode{0x2192} \tt {"basicTags": [ "Service" ]}

guh.pro

@@ -25,7 +25,8 @@ tests.depends = libguh
 
 doc.depends = libguh server
 # Note: some how extraimages in qdocconf did not the trick
-doc.commands = cd $$top_srcdir/doc; qdoc config.qdocconf; cp -r images/* html/images/; \
+doc.commands += cd $$top_srcdir/libguh/interfaces; ./generatedoc.sh;
+doc.commands += cd $$top_srcdir/doc; qdoc config.qdocconf; cp -r images/* html/images/; \
                cp -r favicons/* html/; cp -r $$top_srcdir/doc/html $$top_builddir/
 
 licensecheck.commands = $$top_srcdir/tests/auto/checklicenseheaders.sh $$top_srcdir

libguh/interfaces/gateway.json

@@ -0,0 +1,3 @@
+{
+
+}

libguh/interfaces/generatedoc.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+
+out_file=../../doc/interfacelist.qdoc
+cur_dir=`pwd`
+echo > $out_file
+echo "\\list" >> $out_file
+for i in `ls *.json`; do
+  echo "\\li \l{$i}" | sed s/\.json// >> $out_file
+done
+echo "\\endlist" >> $out_file
+
+for i in `ls *.json`; do
+  echo "\\\target $i" | sed s/\.json// >> $out_file
+  echo "\\section2 $i" | sed s/\.json// >> $out_file
+  echo "\\quotefile $cur_dir/$i" >> $out_file
+done

libguh/interfaces/interfaces.qrc

@@ -5,5 +5,6 @@
         <file>dimmablelight.json</file>
         <file>colorlight.json</file>
         <file>garagegate.json</file>
+        <file>gateway.json</file>
     </qresource>
 </RCC>