MMmmmmm, More Making Marvellous Method Manuals (#1189)

* Comment all the methods & Doxify the comments for all protocols starting with `M`.
  - MagiQuest
  - Midea
  - Mitsubishi
  - Mitsubishi Heavy
  - Multibrackets
  - MWM (Made With Magic)
* Fix commenting mistakes in Daikin & HitachiAc424
* Correct `remote_state[]` size in `IRMitsubishiHeavy88Ac` class.
* Add missing `calibrate()` method to  `IRMitsubishiHeavy88Ac` class.

src/IRsend.h

@@ -473,9 +473,9 @@ class IRsend {
                    const uint16_t repeat = kMidea24MinRepeat);
 #endif  // SEND_MIDEA24
 #if SEND_MAGIQUEST
-  void sendMagiQuest(uint64_t data, uint16_t nbits = kMagiquestBits,
-                     uint16_t repeat = kNoRepeat);
-  uint64_t encodeMagiQuest(uint32_t wand_id, uint16_t magnitude);
+  void sendMagiQuest(const uint64_t data, const uint16_t nbits = kMagiquestBits,
+                     const uint16_t repeat = kNoRepeat);
+  uint64_t encodeMagiQuest(const uint32_t wand_id, const uint16_t magnitude);
 #endif
 #if SEND_LASERTAG
   void sendLasertag(uint64_t data, uint16_t nbits = kLasertagBits,

src/ir_Daikin.cpp

@@ -929,9 +929,9 @@ uint8_t IRDaikin2::convertSwingV(const stdAc::swingv_t position) {
   }
 }
 
-/// Convert a stdAc::swingv_t enum into it's native setting.
-/// @param[in] setting The enum to be converted.
-/// @return The native equivilant of the enum.
+/// Convert a native vertical swing postion to it's common equivalent.
+/// @param[in] setting A native position to convert.
+/// @return The common vertical swing position.
 stdAc::swingv_t IRDaikin2::toCommonSwingV(const uint8_t setting) {
   switch (setting) {
     case kDaikin2SwingVHigh: return stdAc::swingv_t::kHighest;
@@ -1245,9 +1245,9 @@ uint8_t IRDaikin2::convertSwingH(const stdAc::swingh_t position) {
   }
 }
 
-/// Convert a stdAc::swingh_t enum into it's native setting.
-/// @param[in] setting The enum to be converted.
-/// @return The native equivilant of the enum.
+/// Convert a native horizontal swing postion to it's common equivalent.
+/// @param[in] setting A native position to convert.
+/// @return The common horizontal swing position.
 stdAc::swingh_t IRDaikin2::toCommonSwingH(const uint8_t setting) {
   switch (setting) {
     case kDaikin2SwingHSwing: return stdAc::swingh_t::kAuto;
@@ -2085,9 +2085,9 @@ uint8_t IRDaikin160::convertSwingV(const stdAc::swingv_t position) {
   }
 }
 
-/// Convert a stdAc::swingv_t enum into it's native setting.
-/// @param[in] setting The enum to be converted.
-/// @return The native equivilant of the enum.
+/// Convert a native vertical swing postion to it's common equivalent.
+/// @param[in] setting A native position to convert.
+/// @return The common vertical swing position.
 stdAc::swingv_t IRDaikin160::toCommonSwingV(const uint8_t setting) {
   switch (setting) {
     case kDaikin160SwingVHighest: return stdAc::swingv_t::kHighest;
@@ -2471,9 +2471,9 @@ uint8_t IRDaikin176::convertSwingH(const stdAc::swingh_t position) {
   }
 }
 
-/// Convert a stdAc::swingh_t enum into it's native setting.
-/// @param[in] setting The enum to be converted.
-/// @return The native equivilant of the enum.
+/// Convert a native horizontal swing postion to it's common equivalent.
+/// @param[in] setting A native position to convert.
+/// @return The common horizontal swing position.
 stdAc::swingh_t IRDaikin176::toCommonSwingH(const uint8_t setting) {
   switch (setting) {
     case kDaikin176SwingHOff: return stdAc::swingh_t::kOff;

src/ir_Hitachi.cpp

@@ -1048,6 +1048,7 @@ void IRHitachiAc424::stateReset(void) {
   setFan(kHitachiAc424FanAuto);
 }
 
+/// Update the internal consistency check for the protocol.
 void IRHitachiAc424::setInvertedStates(void) {
   for (uint8_t i = 3; i < kHitachiAc424StateLength - 1; i += 2)
     remote_state[i + 1] = ~remote_state[i];

src/ir_MWM.cpp

@@ -1,8 +1,8 @@
 // Copyright 2018 Brett T. Warden
-// derived from ir_Lasertag.cpp, Copyright 2017 David Conran
 
 /// @file
 /// @brief Disney Made With Magic (MWM) Support
+/// derived from ir_Lasertag.cpp
 /// @see https://github.com/crankyoldgit/IRremoteESP8266/pull/557
 
 // Supports:
@@ -27,17 +27,13 @@ const int16_t kSpace = 1;
 const int16_t kMark = 0;
 
 #if SEND_MWM
-// Send a MWM packet.
-// This protocol is 2400 bps serial, 1 start bit (mark), 1 stop bit (space), no
-// parity
-//
-// Args:
-//   data:    The message you wish to send.
-//   nbits:   Bit size of the protocol you want to send.
-//   repeat:  Nr. of extra times the data will be sent.
-//
-// Status: Implemented.
-//
+/// Send a MWM packet/message.
+/// Status: Implemented.
+/// @param[in] data The message to be sent.
+/// @param[in] nbytes The number of bytes of message to be sent.
+/// @param[in] repeat The number of times the command is to be repeated.
+/// @note This protocol is 2400 bps serial, 1 start bit (mark),
+///   1 stop bit (space), no parity
 void IRsend::sendMWM(const uint8_t data[], const uint16_t nbytes,
                      const uint16_t repeat) {
   if (nbytes < 3) return;  // Shortest possible message is 3 bytes
@@ -72,21 +68,16 @@ void IRsend::sendMWM(const uint8_t data[], const uint16_t nbytes,
 #endif  // SEND_MWM
 
 #if DECODE_MWM
-// Decode the supplied MWM message.
-// This protocol is 2400 bps serial, 1 start bit (mark), 1 stop bit (space), no
-// parity
-//
-// Args:
-//   results: Ptr to the data to decode and where to store the decode result.
-//   offset:  The starting index to use when attempting to decode the raw data.
-//            Typically/Defaults to kStartOffset.
-//   nbits:   The number of data bits to expect.
-//   strict:  Flag indicating if we should perform strict matching.
-// Returns:
-//   boolean: True if it can decode it, false if it can't.
-//
-// Status: Implemented.
-//
+/// Decode the supplied MWM message.
+/// Status: Implemented.
+/// @param[in,out] results Ptr to the data to decode & where to store the result
+/// @param[in] offset The starting index to use when attempting to decode the
+///   raw data. Typically/Defaults to kStartOffset.
+/// @param[in] nbits The number of data bits to expect.
+/// @param[in] strict Flag indicating if we should perform strict matching.
+/// @return True if it can decode it, false if it can't.
+/// @note This protocol is 2400 bps serial, 1 start bit (mark),
+///   1 stop bit (space), no parity
 bool IRrecv::decodeMWM(decode_results *results, uint16_t offset,
                        const uint16_t nbits, const bool strict) {
   DPRINTLN("DEBUG: decodeMWM");

src/ir_Magiquest.cpp

@@ -2,6 +2,11 @@
 // Copyright 2015 kitlaan
 // Copyright 2017 Jason kendall, David Conran
 
+/// @file
+/// @brief Support for MagiQuest protocols.
+/// @see https://github.com/kitlaan/Arduino-IRremote/blob/master/ir_Magiquest.cpp
+/// @see https://github.com/mpflaga/Arduino-IRremote
+
 #include "ir_Magiquest.h"
 #include <algorithm>
 #include "IRrecv.h"
@@ -11,25 +16,14 @@
 #define IS_ZERO(m, s) (((m)*100 / ((m) + (s))) <= kMagiQuestZeroRatio)
 #define IS_ONE(m, s) (((m)*100 / ((m) + (s))) >= kMagiQuestOneRatio)
 
-// Strips taken from:
-// https://github.com/kitlaan/Arduino-IRremote/blob/master/ir_Magiquest.cpp
-// and
-// https://github.com/mpflaga/Arduino-IRremote
-
-// Source: https://github.com/mpflaga/Arduino-IRremote
-
 #if SEND_MAGIQUEST
-// Send a MagiQuest formatted message.
-//
-// Args:
-//   data:   The contents of the message you want to send.
-//   nbits:  The bit size of the message being sent.
-//           Typically kMagiquestBits.
-//   repeat: The number of times you want the message to be repeated.
-//
-// Status: Alpha / Should be working.
-//
-void IRsend::sendMagiQuest(uint64_t data, uint16_t nbits, uint16_t repeat) {
+/// Send a MagiQuest formatted message.
+/// Status: Beta / Should be working.
+/// @param[in] data The message to be sent.
+/// @param[in] nbits The number of bits of message to be sent.
+/// @param[in] repeat The number of times the command is to be repeated.
+void IRsend::sendMagiQuest(const uint64_t data, const uint16_t nbits,
+                           const uint16_t repeat) {
   sendGeneric(0, 0,  // No Headers - Technically it's included in the data.
                      // i.e. 8 zeros.
               kMagiQuestMarkOne, kMagiQuestSpaceOne, kMagiQuestMarkZero,
@@ -38,11 +32,15 @@ void IRsend::sendMagiQuest(uint64_t data, uint16_t nbits, uint16_t repeat) {
               kMagiQuestGap, data, nbits, 36, true, repeat, 50);
 }
 
-// Encode a MagiQuest wand_id, and a magnitude into a single 64bit value.
-// (Only 48 bits of real data + 8 leading zero bits)
-// This is suitable for calling sendMagiQuest() with.
-// e.g. sendMagiQuest(encodeMagiQuest(wand_id, magnitude));
-uint64_t IRsend::encodeMagiQuest(uint32_t wand_id, uint16_t magnitude) {
+/// Encode a MagiQuest wand_id, and a magnitude into a single 64bit value.
+/// (Only 48 bits of real data + 8 leading zero bits)
+/// This is suitable for calling sendMagiQuest() with.
+/// e.g. sendMagiQuest(encodeMagiQuest(wand_id, magnitude))
+/// @param[in] wand_id The value for the wand ID.
+/// @param[in] magnitude The value for the magnitude
+/// @return A code suitable for calling sendMagiQuest() with.
+uint64_t IRsend::encodeMagiQuest(const uint32_t wand_id,
+                                 const uint16_t magnitude) {
   uint64_t result = 0;
   result = wand_id;
   result <<= 16;
@@ -51,34 +49,23 @@ uint64_t IRsend::encodeMagiQuest(uint32_t wand_id, uint16_t magnitude) {
   result &= 0xFFFFFFFFFFFFULL;
   return result;
 }
-#endif
-
-// Source:
-// https://github.com/kitlaan/Arduino-IRremote/blob/master/ir_Magiquest.cpp
+#endif  // SEND_MAGIQUEST
 
 #if DECODE_MAGIQUEST
-// Decode the supplied MagiQuest message.
-// MagiQuest protocol appears to be a header of 8 'zero' bits, followed
-// by 32 bits of "wand ID" and finally 16 bits of "magnitude".
-// Even though we describe this protocol as 56 bits, it really only has
-// 48 bits of data that matter.
-//
-// In transmission order, 8 zeros + 32 wand_id + 16 magnitude.
-//
-// Args:
-//   results: Ptr to the data to decode and where to store the decode result.
-//   offset:  The starting index to use when attempting to decode the raw data.
-//            Typically/Defaults to kStartOffset.
-//   nbits:   Nr. of bits to expect in the data portion, inc. the 8 bit header.
-//            Typically kMagiquestBits.
-//   strict:  Flag to indicate if we strictly adhere to the specification.
-// Returns:
-//   boolean: True if it can decode it, false if it can't.
-//
-// Status: Alpha / Should work.
-//
-// Ref:
-//   https://github.com/kitlaan/Arduino-IRremote/blob/master/ir_Magiquest.cpp
+/// Decode the supplied MagiQuest message.
+/// Status: Beta / Should work.
+/// @param[in,out] results Ptr to the data to decode & where to store the result
+/// @param[in] offset The starting index to use when attempting to decode the
+///   raw data. Typically/Defaults to kStartOffset.
+/// @param[in] nbits The number of data bits to expect.
+/// @param[in] strict Flag indicating if we should perform strict matching.
+/// @return True if it can decode it, false if it can't.
+/// @note MagiQuest protocol appears to be a header of 8 'zero' bits, followed
+/// by 32 bits of "wand ID" and finally 16 bits of "magnitude".
+/// Even though we describe this protocol as 56 bits, it really only has
+/// 48 bits of data that matter.
+/// In transmission order, 8 zeros + 32 wand_id + 16 magnitude.
+/// @see https://github.com/kitlaan/Arduino-IRremote/blob/master/ir_Magiquest.cpp
 bool IRrecv::decodeMagiQuest(decode_results *results, uint16_t offset,
                              const uint16_t nbits, const bool strict) {
   uint16_t bits = 0;
@@ -164,4 +151,4 @@ bool IRrecv::decodeMagiQuest(decode_results *results, uint16_t offset,
   results->command = data & 0xFFFF;  // Magnitude
   return true;
 }
-#endif
+#endif  // DECODE_MAGIQUEST

src/ir_Magiquest.h

@@ -2,6 +2,11 @@
 // Copyright 2015 kitlaan
 // Copyright 2017 Jason kendall, David Conran
 
+/// @file
+/// @brief Support for MagiQuest protocols.
+/// @see https://github.com/kitlaan/Arduino-IRremote/blob/master/ir_Magiquest.cpp
+/// @see https://github.com/mpflaga/Arduino-IRremote
+
 // Supports:
 //   Brand: MagiQuest,  Model: Wand
 
@@ -13,7 +18,7 @@
 #include "IRremoteESP8266.h"
 #include "IRsend.h"
 
-// MagiQuest packet is both Wand ID and magnitude of swish and flick
+/// MagiQuest packet is both Wand ID and magnitude of swish and flick
 union magiquest {
   uint64_t llword;
   uint8_t byte[8];