I Just Keep Loving doxygening protocols.

src/ir_Inax.cpp

@@ -1,20 +1,18 @@
 // Copyright 2019 David Conran (crankyoldgit)
-// Support for an IR controlled Robot Toilet
+/// @file
+/// @brief Support for the Inax Robot Toilet IR protocols.
+/// @see https://www.lixil-manual.com/GCW-1365-16050/GCW-1365-16050.pdf
+/// @see https://github.com/crankyoldgit/IRremoteESP8266/issues/706
+
+// Supports:
+//   Brand: Lixil,  Model: Inax DT-BA283 Toilet
 
 #include <algorithm>
 #include "IRrecv.h"
 #include "IRsend.h"
 #include "IRutils.h"
 
-// Supports:
-//   Brand: Lixil,  Model: Inax DT-BA283 Toilet
-
-// Documentation:
-//   https://www.lixil-manual.com/GCW-1365-16050/GCW-1365-16050.pdf
-
 // Constants
-// Ref:
-//   https://github.com/crankyoldgit/IRremoteESP8266/issues/706
 const uint16_t kInaxTick = 500;
 const uint16_t kInaxHdrMark = 9000;
 const uint16_t kInaxHdrSpace = 4500;
@@ -24,16 +22,12 @@ const uint16_t kInaxZeroSpace = kInaxBitMark;
 const uint16_t kInaxMinGap = 40000;
 
 #if SEND_INAX
-// Send a Inax Toilet formatted message.
-//
-// Args:
-//   data:   The message to be sent.
-//   nbits:  The bit size of the message being sent. typically kInaxBits.
-//   repeat: The number of times the message is to be repeated.
-//
-// Status: STABLE / Working.
-//
-// Ref: https://github.com/crankyoldgit/IRremoteESP8266/issues/706
+/// Send a Inax Toilet formatted message.
+/// Status: STABLE / 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.
+/// @see https://github.com/crankyoldgit/IRremoteESP8266/issues/706
 void IRsend::sendInax(const uint64_t data, const uint16_t nbits,
                       const uint16_t repeat) {
   sendGeneric(kInaxHdrMark, kInaxHdrSpace,
@@ -42,23 +36,18 @@ void IRsend::sendInax(const uint64_t data, const uint16_t nbits,
               kInaxBitMark, kInaxMinGap,
               data, nbits, 38, true, repeat, kDutyDefault);
 }
-#endif
+#endif  // SEND_INAX
 
 #if DECODE_INAX
-// Decode the supplied Inax Toilet message.
-//
-// 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.
-//            Typically kInaxBits.
-//   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: Stable / Known working.
-//
+/// Decode the supplied Inax Toilet message.
+/// Status: Stable / Known working.
+/// @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.
+/// @see https://github.com/crankyoldgit/IRremoteESP8266/issues/706
 bool IRrecv::decodeInax(decode_results *results, uint16_t offset,
                         const uint16_t nbits, const bool strict) {
   if (strict && nbits != kInaxBits)
@@ -76,9 +65,9 @@ bool IRrecv::decodeInax(decode_results *results, uint16_t offset,
   // Success
   results->bits = nbits;
   results->value = data;
-  results->decode_type = INAX;
+  results->decode_type = decode_type_t::INAX;
   results->command = 0;
   results->address = 0;
   return true;
 }
-#endif
+#endif  // DECODE_INAX

src/ir_JVC.cpp

@@ -2,15 +2,14 @@
 // Copyright 2017 David Conran
 
 /// @file
-/// @brief JVC
+/// @brief Support for JVC protocols.
+/// Originally added by Kristian Lauszus
+/// Thanks to zenwheel and other people at the original blog post.
 /// @see http://www.sbprojects.com/knowledge/ir/jvc.php
 
 // Supports:
 //   Brand: JVC,  Model: PTU94023B remote
 
-// originally added by Kristian Lauszus
-// (Thanks to zenwheel and other people at the original blog post)
-
 #include <algorithm>
 #include "IRrecv.h"
 #include "IRsend.h"
@@ -38,17 +37,12 @@ const uint16_t kJvcMinGapTicks =
 const uint16_t kJvcMinGap = kJvcMinGapTicks * kJvcTick;
 
 #if SEND_JVC
-// Send a JVC message.
-//
-// Args:
-//   data:   The contents of the command you want to send.
-//   nbits:  The bit size of the command being sent. (kJvcBits)
-//   repeat: The number of times you want the command to be repeated.
-//
-// Status: STABLE.
-//
-// Ref:
-//   http://www.sbprojects.com/knowledge/ir/jvc.php
+/// Send a JVC formatted message.
+/// Status: STABLE / 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.
+/// @see http://www.sbprojects.com/knowledge/ir/jvc.php
 void IRsend::sendJVC(uint64_t data, uint16_t nbits, uint16_t repeat) {
   // Set 38kHz IR carrier frequency & a 1/3 (33%) duty cycle.
   enableIROut(38, 33);
@@ -75,41 +69,28 @@ void IRsend::sendJVC(uint64_t data, uint16_t nbits, uint16_t repeat) {
   }
 }
 
-// Calculate the raw JVC data based on address and command.
-//
-// Args:
-//   address: An 8-bit address value.
-//   command: An 8-bit command value.
-// Returns:
-//   A raw JVC message.
-//
-// Status: STABLE / Works fine.
-//
-// Ref:
-//   http://www.sbprojects.com/knowledge/ir/jvc.php
+/// Calculate the raw JVC data based on address and command.
+/// Status: STABLE / Works fine.
+/// @param[in] address An 8-bit address value.
+/// @param[in] command An 8-bit command value.
+/// @return A raw JVC message code, suitable for sendJVC()..
+/// @see http://www.sbprojects.com/knowledge/ir/jvc.php
 uint16_t IRsend::encodeJVC(uint8_t address, uint8_t command) {
   return reverseBits((command << 8) | address, 16);
 }
-#endif
+#endif  // SEND_JVC
 
 #if DECODE_JVC
-// Decode the supplied JVC message.
-//
-// 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 of data to expect. Typically kJvcBits.
-//   strict:  Flag indicating if we should perform strict matching.
-// Returns:
-//   boolean: True if it can decode it, false if it can't.
-//
-// Status: STABLE
-//
-// Note:
-//   JVC repeat codes don't have a header.
-// Ref:
-//   http://www.sbprojects.com/knowledge/ir/jvc.php
+/// Decode the supplied JVC message.
+/// Status: Stable / Known working.
+/// @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 JVC repeat codes don't have a header.
+/// @see http://www.sbprojects.com/knowledge/ir/jvc.php
 bool IRrecv::decodeJVC(decode_results *results, uint16_t offset,
                        const uint16_t nbits, const bool strict) {
   if (strict && nbits != kJvcBits)
@@ -147,4 +128,4 @@ bool IRrecv::decodeJVC(decode_results *results, uint16_t offset,
   results->repeat = isRepeat;
   return true;
 }
-#endif
+#endif  // DECODE_JVC

src/ir_Kelvinator.cpp

@@ -1,5 +1,6 @@
 // Copyright 2016 David Conran
-//
+/// @file
+/// @brief Support for Kelvinator A/C protocols.
 /// Code to emulate IR Kelvinator YALIF remote control unit, which should
 /// control at least the following Kelvinator A/C units:
 /// KSV26CRC, KSV26HRC, KSV35CRC, KSV35HRC, KSV53HRC, KSV62HRC, KSV70CRC,
@@ -26,7 +27,6 @@
 #include "IRutils.h"
 
 // Constants
-
 const uint16_t kKelvinatorTick = 85;
 const uint16_t kKelvinatorHdrMarkTicks = 106;
 const uint16_t kKelvinatorHdrMark = kKelvinatorHdrMarkTicks * kKelvinatorTick;
@@ -71,11 +71,10 @@ using irutils::setBits;
 
 #if SEND_KELVINATOR
 /// Send a Kelvinator A/C message.
-///
 /// Status: STABLE / Known working.
-/// @param[in] data An array of bytes containing the IR command.
-/// @param[in] nbytes Nr. of bytes of data in the array.
-/// @param[in] repeat Nr. of times the message is to be repeated.
+/// @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.
 void IRsend::sendKelvinator(const unsigned char data[], const uint16_t nbytes,
                             const uint16_t repeat) {
   if (nbytes < kKelvinatorStateLength)
@@ -118,7 +117,7 @@ void IRsend::sendKelvinator(const unsigned char data[], const uint16_t nbytes,
 }
 #endif  // SEND_KELVINATOR
 
-/// Class for handling detailed Kelvinator A/C messages.
+/// Class constructor
 /// @param[in] pin GPIO to be used when sending.
 /// @param[in] inverted Is the output signal to be inverted?
 /// @param[in] use_modulation Is frequency modulation to be used?
@@ -168,6 +167,11 @@ void IRKelvinatorAC::setRaw(const uint8_t new_code[]) {
   memcpy(remote_state, new_code, kKelvinatorStateLength);
 }
 
+/// Calculate the checksum for a given block of state.
+/// @param[in] block A pointer to a block to calc the checksum of.
+/// @param[in] length Length of the block array to checksum.
+/// @return The calculated checksum value.
+/// @note Many Bothans died to bring us this information.
 uint8_t IRKelvinatorAC::calcBlockChecksum(const uint8_t *block,
                                           const uint16_t length) {
   uint8_t sum = kKelvinatorChecksumStart;
@@ -182,7 +186,6 @@ uint8_t IRKelvinatorAC::calcBlockChecksum(const uint8_t *block,
 
 /// Calculate the checksum for the internal state.
 /// @param[in] length Length of the internal state to checksum.
-/// @note Many Bothans died to bring us this information.
 void IRKelvinatorAC::checksum(const uint16_t length) {
   // For each command + options block.
   for (uint16_t offset = 0; offset + 7 < length; offset += 8) {
@@ -476,7 +479,6 @@ String IRKelvinatorAC::toString(void) {
 
 #if DECODE_KELVINATOR
 /// Decode the supplied Kelvinator message.
-///
 /// Status: STABLE / Known working.
 /// @param[in,out] results Ptr to the data to decode & where to store the decode
 ///   result.

src/ir_Kelvinator.h

@@ -1,6 +1,6 @@
-// Kelvinator A/C
-//
 // Copyright 2016 David Conran
+/// @file
+/// @brief Support for Kelvinator A/C protocols.
 
 // Supports:
 //   Brand: Kelvinator,  Model: YALIF Remote
@@ -138,7 +138,6 @@ class IRKelvinatorAC {
  public:
   explicit IRKelvinatorAC(const uint16_t pin, const bool inverted = false,
                           const bool use_modulation = true);
-
   void stateReset(void);
 #if SEND_KELVINATOR
   void send(const uint16_t repeat = kKelvinatorDefaultRepeat);
@@ -186,12 +185,13 @@ class IRKelvinatorAC {
 #ifndef UNIT_TEST
 
  private:
-  IRsend _irsend;
-#else
-  IRsendTest _irsend;
-#endif
-  // The state of the IR remote in IR code form.
-  uint8_t remote_state[kKelvinatorStateLength];
+  IRsend _irsend;  ///< Instance of the IR send class
+#else  // UNIT_TEST
+  /// @cond IGNORE
+  IRsendTest _irsend;  ///< Instance of the testing IR send class
+  /// @endcond
+#endif  // UNIT_TEST
+  uint8_t remote_state[kKelvinatorStateLength];  ///< The state in IR code form.
   void checksum(const uint16_t length = kKelvinatorStateLength);
   void fixup(void);
 };