Improve documentation of protocol format

lib/lib_rf/rc-switch/src/RCSwitch.cpp

@@ -56,33 +56,58 @@
 
 /* Protocol description format
  *
- * {Pulse length, Preamble, Sync bit, "0" bit, "1" bit, Inverted Signal, Guard time}
+ * {
+ *    Pulse length, 
  * 
- * Pulse length: pulse duration Te in microseconds,
- *               example 350
- * Preamble: Alternating high and low levels
- *           {20, 1} means 20 alternations of 1 Te duration
- *      _   _   _   _   _   _   _   _   _   _
- *     | |_| |_| |_| |_| |_| |_| |_| |_| |_| |_
- * Sync bit: Header and clock
- *           {1, 31} means 1 pulse long Te high and 31 low
+ *    PreambleFactor,
+ *    Preamble {high,low},
+ * 
+ *    HeaderFactor,
+ *    Header {high,low},
+ * 
+ *    "0" bit {high,low},
+ *    "1" bit {high,low},
+ * 
+ *    Inverted Signal,
+ *    Guard time
+ * }
+ * 
+ * Pulse length: pulse duration (Te) in microseconds,
+ *               for example 350
+ * PreambleFactor: Number of high and low states to send
+ *                 (One pulse = 2 states, in orther words, number of pulses is
+ *                 ceil(PreambleFactor/2).)
+ * Preamble: Pulse shape which defines a preamble bit.
+ *           Sent ceil(PreambleFactor/2) times.
+ *           For example, {1, 2} with factor 3 would send
+ *      _    _   
+ *     | |__| |__         (each horizontal bar has a duration of Te,
+ *                         vertical bars are ignored)
+ * HeaderFactor: Number of times to send the header pulse.
+ * Header: Pulse shape which defines a header (or "sync"/"clock") pulse.
+ *           {1, 31} means one pulse of duration 1 Te high and 31 Te low
  *      _
  *     | |_______________________________ (don't count the vertical bars)
+ * 
  * "0" bit: pulse shape defining a data bit, which is a logical "0"
  *          {1, 3} means 1 pulse duration Te high level and 3 low
  *      _
  *     | |___
+ * 
  * "1" bit: pulse shape that defines the data bit, which is a logical "1"
  *          {3, 1} means 3 pulses with a duration of Te high level and 1 low
  *      ___
  *     |   |_
  *
- * (note: to form the state bit Z (Tri-State bit), these two codes are combined)
+ * (note: to form the state bit Z (Tri-State bit), two codes are combined)
+ * 
  * Inverted Signal: Signal inversion - if true the signal is inverted
  *                  replacing high to low in a transmitted / received packet
- * Guard time: Safety time, followed by the next preamble of the next packet
- *             for example 39 pulses of low duration Te
+ * Guard time: Separation time between two retries. It will be followed by the 
+ *             next preamble of the next packet. In number of Te.
+ *             e.g. 39 pulses of duration Te low level
  */
+
 #if defined(ESP8266) || defined(ESP32)
 static const VAR_ISR_ATTR RCSwitch::Protocol proto[] = {
 #else