improve code comments

src/BootKeyboard/BootKeyboard.cpp

@@ -264,6 +264,16 @@ uint8_t BootKeyboard_::getBootOnly() {
   return bootkb_only;
 }
 
+/*
+ * Set whether to send only Boot Protocol regardless of whether Boot
+ * Protocol has been requested. Used by USBQuirks to toggle protocol
+ * modes.
+ *
+ * This is only really safe to call after detaching from USB, because
+ * otherwise, the report format might get out of sync with what the host
+ * expects, and the host probably won't see the new Report Descriptor
+ * until after a re-attach.
+ */
 void BootKeyboard_::setBootOnly(uint8_t bootonly) {
   bootkb_only = bootonly;
 }
@@ -305,7 +315,7 @@ int BootKeyboard_::sendReportUnchecked() {
   size_t reportlen;
   // Send only boot report if host requested boot protocol, or if configured as boot-only
   if (protocol == HID_BOOT_PROTOCOL || bootkb_only) {
-    reportlen = 8;
+    reportlen = BOOT_REPORT_LEN;
   } else {
     reportlen = sizeof(out_report);
   }

src/BootKeyboard/BootKeyboard.h

@@ -31,12 +31,19 @@ THE SOFTWARE.
 #include "HIDTables.h"
 #include "HIDAliases.h"
 
+// Declare the hybrid boot keyboard feature so Kaleidoscope can depend on it
 #define BOOTKB_HYBRID 1
 
 #define BOOT_KEY_BYTES 6
+#define BOOT_REPORT_LEN 8
+
 #define NKRO_KEY_BITS (4 + HID_LAST_KEY - HID_KEYBOARD_A_AND_A + 1)
 #define NKRO_KEY_BYTES ((NKRO_KEY_BITS + 7) / 8)
 
+/*
+ * Keep the current key states in a NKRO bitmap. We'll convert it to Boot
+ * Protocol as needed.
+ */
 typedef union {
   // Modifiers + keymap
   struct {
@@ -46,6 +53,15 @@ typedef union {
   uint8_t allkeys[1 + NKRO_KEY_BYTES];
 } HID_NKRO_KeyboardReport_Data_t;
 
+/*
+ * Hybrid boot report that contains the Boot Protocol report as a prefix to
+ * a bitmap NKRO report. The keycodes array of the Boot Report is marked as
+ * padding in the Report Descriptor, so HID-aware hosts will ignore it, but
+ * hosts that require Boot Protocol without requesting it have a chance of
+ * working, assuming they can deal with the extended report.
+ *
+ * We do send only the Boot Report if the host has requested Boot Protocol.
+ */
 typedef union {
   // Hybrid report: boot keyboard report + NKRO report
   struct {
@@ -57,12 +73,16 @@ typedef union {
     // NKRO keyboard non-modifiers keys bitmap
     uint8_t nkro_keys[NKRO_KEY_BYTES];
   };
-  uint8_t bytes[8 + NKRO_KEY_BYTES];
+  uint8_t bytes[BOOT_REPORT_LEN + NKRO_KEY_BYTES];
 } HID_BootKeyboardReport_Data_t;
 
 
 class BootKeyboard_ : public PluggableUSBModule {
  public:
+  /*
+   * Change to `bootkb_only_ = 1` if you need to default to only sending
+   * Boot Protocol, even if in Report Protocol.
+   */
   BootKeyboard_(uint8_t bootkb_only_ = 0);
   size_t press(uint8_t k);
   void begin();