Refactor the Doxygen structure (#880)

2017-07-31 18:42:26 +02:00
parent 1cd2c6df05
commit f3ab329ad3
42 changed files with 3834 additions and 13340 deletions
@@ -22,6 +22,7 @@
 *
 * @brief API and type declarations for MySensors messages
 * @defgroup MyMessagegrp MyMessage
+ * @ingroup publics
 * @{
 *
 * @brief Here you can find all message types used by the MySensors protocol as well as macros for
@@ -55,7 +56,7 @@ typedef enum {
 	S_MOTION				= 1,	//!< Motion sensor, V_TRIPPED, V_ARMED
 	S_SMOKE					= 2,	//!< Smoke sensor, V_TRIPPED, V_ARMED
 	S_BINARY				= 3,	//!< Binary light or relay, V_STATUS, V_WATT
-	S_LIGHT					= 3,	//!< \deprecated Same as S_BINARY, **** DEPRECATED, DO NOT USE ****
+	S_LIGHT					= 3,	//!< \deprecated Same as S_BINARY
 	S_DIMMER				= 4,	//!< Dimmable light or fan device, V_STATUS (on/off), V_PERCENTAGE (dimmer level 0-100), V_WATT
 	S_COVER					= 5,	//!< Blinds or window cover, V_UP, V_DOWN, V_STOP, V_PERCENTAGE (open/close to a percentage)
 	S_TEMP					= 6,	//!< Temperature sensor, V_TEMP
@@ -99,9 +100,9 @@ typedef enum {
 	V_TEMP					= 0,	//!< S_TEMP. Temperature S_TEMP, S_HEATER, S_HVAC
 	V_HUM					= 1,	//!< S_HUM. Humidity
 	V_STATUS				= 2,	//!< S_BINARY, S_DIMMER, S_SPRINKLER, S_HVAC, S_HEATER. Used for setting/reporting binary (on/off) status. 1=on, 0=off
-	V_LIGHT					= 2,	//!< \deprecated Same as V_STATUS, **** DEPRECATED, DO NOT USE ****
+	V_LIGHT					= 2,	//!< \deprecated Same as V_STATUS
 	V_PERCENTAGE			= 3,	//!< S_DIMMER. Used for sending a percentage value 0-100 (%).
-	V_DIMMER				= 3,	//!< \deprecated Same as V_PERCENTAGE, **** DEPRECATED, DO NOT USE ****
+	V_DIMMER				= 3,	//!< \deprecated Same as V_PERCENTAGE
 	V_PRESSURE				= 4,	//!< S_BARO. Atmospheric Pressure
 	V_FORECAST				= 5,	//!< S_BARO. Whether forecast. string of "stable", "sunny", "cloudy", "unstable", "thunderstorm" or "unknown"
 	V_RAIN					= 6,	//!< S_RAIN. Amount of rain
@@ -120,7 +121,7 @@ typedef enum {
 	V_SCENE_ON				= 19,	//!< S_SCENE_CONTROLLER. Turn on a scene
 	V_SCENE_OFF				= 20,	//!< S_SCENE_CONTROLLER. Turn of a scene
 	V_HVAC_FLOW_STATE		= 21,	//!< S_HEATER, S_HVAC. HVAC flow state ("Off", "HeatOn", "CoolOn", or "AutoChangeOver")
-	V_HEATER				= 21,	//!< \deprecated Same as V_HVAC_FLOW_STATE, **** DEPRECATED, DO NOT USE ****
+	V_HEATER				= 21,	//!< \deprecated Same as V_HVAC_FLOW_STATE
 	V_HVAC_SPEED			= 22,	//!< S_HVAC, S_HEATER. HVAC/Heater fan speed ("Min", "Normal", "Max", "Auto")
 	V_LIGHT_LEVEL			= 23,	//!< S_LIGHT_LEVEL. Uncalibrated light level. 0-100%. Use V_LEVEL for light level in lux
 	V_VAR1					= 24,	//!< VAR1
@@ -350,8 +350,15 @@ int8_t _sleep(const uint32_t sleepingMS, const bool smartSleep = false,
              const uint8_t interrupt2 = INTERRUPT_NOT_DEFINED, const uint8_t mode2 = MODE_NOT_DEFINED);


+// **** private functions ********
+
+/**
+ * @defgroup MyLockgrp MyNodeLock
+ * @ingroup internals
+ * @brief API declaration for MyNodeLock
+ * @{
+ */
 /**
- * @ingroup MyLockgrp
 * @brief Lock a node and transmit provided message with 30m intervals
 *
 * This function is called if suspicious activity has exceeded the threshold (see
@@ -366,8 +373,7 @@ void _nodeLock(const char* str);
 * @brief Check node lock status and prevent node execution if locked.
 */
 void _checkNodeLock(void);
-
-// **** private functions ********
+/** @}*/ // Node lock group

 /**
 * @brief Node initialisation
@@ -17,14 +17,14 @@
 * version 2 as published by the Free Software Foundation.
 */
 /**
- * @defgroup MySigninggrp MySigning
- * @ingroup internals
+ * @defgroup MySigninggrpPub Message signing
+ * @ingroup publics
 * @{
 *
- * @brief The signing driver provides a generic API for various signing backends to offer
- * signing of MySensors messages.
+ * @brief The message signing infrastructure provides message authenticity to users by signing
+ * MySensors messages.
 *
- * Signing support created by Patrick "Anticimex" Fallberg (<patrick@fallberg.net>)
+ * Signing support created by Patrick "Anticimex" Fallberg.
 *
 * @section MySigninggrptoc Table of contents
 *
@@ -48,6 +48,12 @@
 * variant (@ref MY_SIGNING_SIMPLE_PASSWD) of the software backend which only require one setting
 * to activate.
 *
+ * If you use hardware backed signing, then connect the device as follows:
+ * @image html MySigning/wiring.png
+ * @note The pull-up resistor is optional but recommended.
+ * @note If you change the default pin (A3) make sure you use a pin that supports input/output
+ *       (ex. A6 & A7 on a Pro Mini are input only pins).
+ *
 * To use signng, you need to perform three major steps which are described below.
 *
 * <b>Firstly</b>, you need to make sure to pick a backend to use.
@@ -139,22 +145,22 @@
 *
 * To personalize a ATSHA204A do the following procedure:
 * 1. Enable @ref GENERATE_KEYS_ATSHA204A<br>
- *    This will lock the ATSHA204A and generate random keys for HMAC (signing) and AES (encryption).
+ *    This will lock the ATSHA204A and generate random keys for HMAC (signing) and %AES (encryption).
 *    Copy the keys generated and replace the corresponding definitions under
 *    "User defined key data", specifically @ref MY_HMAC_KEY and @ref MY_AES_KEY.
 * 2. Disable @ref GENERATE_KEYS_ATSHA204A and enable @ref PERSONALIZE_ATSHA204A<br>
- *    This will store the HMAC key to the ATSHA204A and the AES key to EEPROM. It will also write
+ *    This will store the HMAC key to the ATSHA204A and the %AES key to EEPROM. It will also write
 *    a checksum of the personalization data in EEPROM to be able to detect if the data is
 *    altered.<br>
 *    Personalization is now complete.
 *
 * To personalize for software signing do the following procedure:
 * 1. Enable @ref GENERATE_KEYS_SOFT<br>
- *    This will generate random keys for HMAC (signing) and AES (encryption).
+ *    This will generate random keys for HMAC (signing) and %AES (encryption).
 *    Copy the keys generated and replace the corresponding definitions under
 *    "User defined key data", specifically @ref MY_HMAC_KEY and @ref MY_AES_KEY.
 * 2. Disable @ref GENERATE_KEYS_SOFT and enable @ref PERSONALIZE_SOFT<br>
- *    This will store the HMAC key and the AES key to EEPROM. It will also write
+ *    This will store the HMAC key and the %AES key to EEPROM. It will also write
 *    a checksum of the personalization data in EEPROM to be able to detect if the data is
 *    altered.<br>
 *    Personalization is now complete.
@@ -382,7 +388,6 @@
 * The following sequence diagram illustrate how messages are passed in a MySensors network with
 * respect to signing:
 * @image html MySigning/signingsequence.png
- * @image latex MySigning/signingsequence.eps "Signing sequence diagram" width=9cm
 *
 * None of this activity is “visible” to you (as the sensor sketch implementor). All you need to do
 * is to set your preferences in your sketch and personalize accordingly.
@@ -395,7 +400,6 @@
 * The following illustration shows what part of the message is signed, and where the signature is
 * stored:
 * @image html MySigning/signingillustrated1.png
- * @image latex MySigning/signingillustrated1.eps "Message structure" width=11cm
 *
 * The first byte of the header is not covered by the signature, because in the network, this byte
 * is used to track hops in the network and therefore might change if the message is passing a relay
@@ -413,7 +417,6 @@
 *
 * The signatures are calculates in the following way:
 * @image html MySigning/signingillustrated2.png
- * @image latex MySigning/signingillustrated2.eps "HMAC processing" width=10cm
 *
 * Exactly how this is done can be reviewed in the source for the software backend
 * (MySigningAtsha204Soft.cpp) and the ATSHA204A
@@ -447,7 +450,6 @@
 * chooses, instead of Alice. Such an attack is known as a <b>replay attack</b>.<br>
 * <i>Authenticity</i> permits Bob to determine if Alice is the true sender of a message.
 * @image html MySigning/alicenfriends.png
- * @image latex MySigning/alicenfriends.eps "Alice with Eve and Bob" width=6cm
 *
 * It can also be interesting for Bob to know that the message Alice sent has not been tampered with
 * in any way. This is the <i>integrity</i> of the message. We now introduce Mallory, who could be
@@ -461,7 +463,6 @@
 * This is achieved by adding a <i>signature</i> to the message, which Bob can inspect to validate
 * that Alice is the author.
 * @image html MySigning/alicenfriends2.png
- * @image latex MySigning/alicenfriends2.eps "Alice with Mallory and Bob" width=9cm
 *
 * The signing scheme used, needs to address both these attack scenarios. Neither Eve nor Mallory
 * must be permitted to interfere with the message exchange between Alice and Bob.
@@ -501,7 +502,6 @@
 *
 * The flow can be described like this:
 * @image html MySigning/alicenbob.png
- * @image latex MySigning/alicenbob.eps "Alice and Bob" width=8cm
 * The benefits for MySensors to support this are obvious. Nobody wants others to be able to control
 * or manipulate any actuators in their home.
 *
@@ -557,7 +557,7 @@
 * keeping the current message routing mechanisms intact and therefore leave the matter of
 * <i>secrecy</i> to be implemented in the “physical” transport layer. With the <i>integrity</i> and
 * <i>authenticity</i> handled in the protocol it ought to be enough for a simple encryption
- * (nonce-less AES with a PSK for instance) on the message as it is sent to the RF backend. Atmel
+ * (nonce-less %AES with a PSK for instance) on the message as it is sent to the RF backend. Atmel
 * does provide such circuits as well but I have not investigated the matter further as it given the
 * current size of the ethernet gateway sketch is close to the size limit on an Arduino Nano, so it
 * will be difficult to fit this into some existing gateway designs.<br>
@@ -571,7 +571,17 @@
 * This might change in the future as more powerful platforms emerge which permit more complex
 * security schemes and better hardware acceleration.
 */
+/** @}*/

+/**
+ * @defgroup MySigninggrp MySigning
+ * @ingroup internals
+ * @{
+ *
+ * @brief API declaration for MySigning signing backend
+ *
+ * @see MySigninggrpPub
+ */
 /**
 * @file MySigning.h
 *
@@ -738,9 +748,11 @@ int signerMemcmp(const void* a, const void* b, size_t sz);

 /**
 * @defgroup MySigningDebugMessages Signing related debug messages
- * @ingroup MySigninggrp
+ * @ingroup MySigninggrpPub
 * @{
 *
+ * @brief Explanation of the abstract signing related debug messages
+ *
 * MySigning-related log messages, format: [!]SYSTEM:SUB SYSTEM:MESSAGE
 * - [!] Exclamation mark is prepended in case of error or warning
 * - SYSTEM:
@@ -825,9 +837,11 @@ int signerMemcmp(const void* a, const void* b, size_t sz);

 /**
 * @defgroup MySigningTroubleshootinggrp Signing troubleshooting
- * @ingroup MySigninggrp
+ * @ingroup MySigninggrpPub
 * @{
 *
+ * @brief Typical signing related failure cases and how to solve them
+ *
 * @section MySigningTroubleshootingSymptoms Symptoms and solutions
 *
 * The first thing to do if you suspect signing is causing problems, is to enable the verbose debug