Add documentation for CAN API

jboynes · jboynes · commit 6a263a1959c7 · 2023-11-02T13:39:21.000Z
diff --git a/api/HardwareCAN.h b/api/HardwareCAN.h
@@ -44,12 +44,56 @@ class HardwareCAN
   virtual ~HardwareCAN() {}
 
 
+  /**
+   * Initialize the CAN controller.
+   *
+   * @param can_bitrate the bus bit rate
+   * @return true if initialization succeeded and the controller is operational
+   */
   virtual bool begin(CanBitRate const can_bitrate) = 0;
-  virtual void end() = 0;
 
+  /**
+   * Disable the CAN controller.
+   *
+   * Whether any messages that are buffered will be sent is _implementation defined_.
+   */
+  virtual void end() = 0;
 
+  /**
+   * Enqueue a message for transmission to the CAN bus.
+   *
+   * This call returns when the message has been enqueued for transmission.
+   * Due to bus arbitration and error recovery there may be a substantial delay
+   * before the message is actually sent.
+   *
+   * An implementation must ensure that all messages with the same CAN priority
+   * are sent in the order in which they are enqueued.
+   *
+   * It is _implementation defined_ whether multiple messages can be enqueued
+   * for transmission, and if messages with higher CAN priority can preempt the
+   * transmission of previously enqueued messages. The default configuration for
+   * and implementation should not allow multiple messages to be enqueued.
+   *
+   * @param msg the message to send
+   * @return 1 if the message was enqueued, an _implementation defined_ error code < 0 if there was an error
+   * @todo define specific error codes, especially "message already pending"
+   */
   virtual int write(CanMsg const &msg) = 0;
+
+  /**
+   * Determine if any messages have been received and buffered.
+   *
+   * @return the number of unread messages that have been received
+   */
   virtual size_t available() = 0;
+
+  /**
+   * Returns the first message received, or an empty message if none are available.
+   *
+   * Messages must be returned in the order received.
+   *
+   * @return the first message in the receive buffer
+   */
   virtual CanMsg read() = 0;
 };
 
