AE-577: Addressed code review findings.

Author: bogdanarduino

examples/Keyboard/Keyboard.ino

@@ -1,5 +1,8 @@
 /*
- * This simple example shows how to read keyboard data by both listening for events and polling for available character data in the internal buffers of the USB HID Host
+ * This simple example shows how to read keyboard data by both listening for events and polling for available character data in the internal buffers of the USB HID Host.
+ * There are two general ways user input can be detected, either by constantly checking for the state of a buffer (or pin, for example), which we refer to as the "polling" method, or
+ * by having some event fire as soon as the user input (key press in this case) is detected, which, in turn, calls a function we registered previously with the lower layers.
+ * The below example demonstrates both these methods of capturing user input.
  * 
  * Instructions:
  * 1. Connect your Arduino Portenta C33 to a mid-carrier board;
@@ -18,8 +21,9 @@ void onKeyboardConnected() {
   Serial.println("Keyboard connected (callback).");
 }
 
+// This function will now be called every time a key is pressed by the user, as a single event
 void onKeyboardEvent(uint8_t key) {
-  Serial.print("Keyboard event (callback): ");
+  Serial.print("Key pressed (event callback): ");
   Serial.println((char) key);
 }
 
@@ -33,11 +37,12 @@ void setup() {
 }
 
 void loop() {
-  kb.poll();
+  kb.poll(); // This function will continuosly check if a key has been pressed, this is generally refered to as "polling"
 
-  // Second way of reading back the keystrokes is via polling for available characters
+  // If keystrokes were registered, we enter a second loop and print out the entire buffer
   while (kb.available() > 0) {
     char c = kb.read();
+    Serial.print("Key pressed (polling detection): ");
     Serial.println(c);
   }
 }

examples/KeyboardAndMouse/KeyboardAndMouse.ino

@@ -42,9 +42,12 @@ void onMouseConnected() {
 }
 
 // Mouse movement/button event callback
+// Note here the use of the "eventReceived" global variable. Since this function is called in an interrupt context,
+// we cannot do the processing and printin of data using Serial.print inside the interrupt, because it takes too much time.
+// Therefore, we set a global flag to "true", which is then checked in the "loop", outside of the ISR (interrupt service routine), then set back to "false".
+// An even better and more robut, but also more complex, way of handling this is by using a buffer queue for the mouse data and a state machine to process it.
 void onMouseEvent(const HIDMouseEvent &event) {
   eventReceived = true;
-  mouseEvent = event;
 }
 
 void setup() {

examples/Mouse/Mouse.ino

@@ -5,9 +5,9 @@
  * 1. Connect your Arduino Portenta C33 to a mid-carrier board;
  * 2. Upload this sketch to the board;
 
- * 3. Open the Serial Monitor and chose the same baud rate as used in the sketch;
+ * 3. Open the Serial Monitor and chose the same baud rate (115200 in this case) as used in the sketch;
  * 4. Connect your mouse to the USB-A connector and any movement or keypress should be printed as data to the console.
- * Please not that scroll wheel data works inconsistently and might not function correctly with your mouse.
+ * Please note that the scroll wheel data works inconsistently and might not function correctly with your mouse.
  */
 
 #include <Arduino.h>