improve docs for CAN glue layers

Author: samuelsadok

src/ODriveFlexCAN.hpp

@@ -1,3 +1,6 @@
+// Glue layer for FlexCAN-based CAN stacks.
+// See ODriveHardwareCAN.hpp for documentation.
+
 #pragma once
 
 #include "ODriveCAN.h"

src/ODriveHardwareCAN.hpp

@@ -1,3 +1,5 @@
+// Glue layer for platforms that implement the Arduino's official HardwareCAN API.
+
 #pragma once
 
 #include "ODriveCAN.h"
@@ -6,6 +8,19 @@
 // Must be defined by the application
 void onCanMessage(const CanMsg& msg);
 
+/**
+ * @brief Sends a CAN message over the specified platform-specific interface.
+ * 
+ * @param can_intf A platform-specific reference to the CAN interface to use.
+ * @param id: The CAN message ID to send.
+ *        Bit 31 indicates if the ID is extended (29-bit) or standard (11-bit).
+ *        Bits 30 and 29 are reserved.
+ * @param length: The length of the data in bytes (0-8). For RTR messages, this
+ *        should be 0.
+ * @param data: A pointer to the data to send. If null, a remote transmission
+ *        request (RTR=1) is sent, if supported by the interface.
+ * @return: True if the message was sent successfully, false otherwise.
+ */
 static bool sendMsg(HardwareCAN& can_intf, uint32_t id, uint8_t length, const uint8_t* data) {
     // Note: Arduino_CAN does not support the RTR bit. The ODrive interprets
     // zero-length packets the same as RTR=1, but it creates the possibility of
@@ -18,10 +33,28 @@ static bool sendMsg(HardwareCAN& can_intf, uint32_t id, uint8_t length, const ui
     return can_intf.write(msg) >= 0;
 }
 
+/**
+ * @brief Receives a CAN message from the platform-specific interface and passes
+ * it to the ODriveCAN instance.
+ * 
+ * @param msg: The received CAN message in a platform-specific format.
+ * @param odrive: The ODriveCAN instance to pass the message to.
+ */
 static void onReceive(const CanMsg& msg, ODriveCAN& odrive) {
     odrive.onReceive(msg.id, msg.data_length, msg.data);
 }
 
+/**
+ * @brief Processes the CAN interface's RX buffer and calls onCanMessage for
+ * each pending message.
+ * 
+ * On hardware interfaces where onCanMessage() is already called from the
+ * interrupt handler, this function is a no-op.
+ * 
+ * @param intf: The platform-specific CAN interface to process.
+ * @param max_events: The maximum number of events to process. This prevents
+ *        an infinite loop if messages come at a high rate.
+ */
 static void pumpEvents(HardwareCAN& intf, int max_events = 100) {
     // max_events prevents an infinite loop if messages come at a high rate
     while (intf.available() && max_events--) {

src/ODriveMCPCAN.hpp

@@ -1,3 +1,6 @@
+// Glue layer for MCP2515-based CAN interfaces.
+// See ODriveHardwareCAN.hpp for documentation.
+
 #pragma once
 
 #include "MCP2515.h"
@@ -14,6 +17,8 @@ struct CanMsg {
 // Must be defined by the application if you want to use defaultCanReceiveCallback().
 void onCanMessage(const CanMsg& msg);
 
+// MSB of id means "extended"
+// if data is null, it's a remote request frame
 static bool sendMsg(MCP2515Class& can_intf, uint32_t id, uint8_t length, const uint8_t* data) {
     if (id & 0x80000000) {
         can_intf.beginExtendedPacket(id & 0x1fffffff, length, !data);

src/ODriveSTM32CAN.hpp

@@ -1,3 +1,6 @@
+// CAN glue layer for STM32 platforms.
+// See ODriveHardwareCAN.hpp for documentation.
+
 #pragma once
 
 #include "ODriveCAN.h"