CAN: Add functions to clear queues and fix multiple bugs

This commits adds the functions can_clear_transmit_queue() and
can_clear_receive_queue(). Closes #2906

The following bug are fixed:

- CAN_IO_UNUSED is now explicitly cast to enum type. Closes #2825
- Fix multiple documentation errors. Closes #2898, Closes #2794
- can_reconfigure_alerts() returns incorrect current_alerts. Closes #3028
- Add missing header file. Closes #3065

components/driver/include/driver/can.h

@@ -19,6 +19,7 @@
 extern "C" {
 #endif
 
+#include "freertos/FreeRTOS.h"
 #include "esp_types.h"
 #include "esp_intr.h"
 #include "esp_err.h"
@@ -105,7 +106,7 @@ extern "C" {
 #define CAN_EXTD_ID_MASK                0x1FFFFFFF  /**< Bit mask for 29 bit Extended Frame Format ID */
 #define CAN_STD_ID_MASK                 0x7FF       /**< Bit mask for 11 bit Standard Frame Format ID */
 #define CAN_MAX_DATA_LEN                8           /**< Maximum number of data bytes in a CAN2.0B frame */
-#define CAN_IO_UNUSED                   (-1)        /**< Marks GPIO as unused in CAN configuration */
+#define CAN_IO_UNUSED                   ((gpio_num_t) -1)   /**< Marks GPIO as unused in CAN configuration */
 /** @endcond */
 
 /* ----------------------- Enum and Struct Definitions ---------------------- */
@@ -392,6 +393,34 @@ esp_err_t can_initiate_recovery();
  */
 esp_err_t can_get_status_info(can_status_info_t *status_info);
 
+/**
+ * @brief   Clear the transmit queue
+ *
+ * This function will clear the transmit queue of all messages.
+ *
+ * @note    The transmit queue is automatically cleared when can_stop() or
+ *          can_initiate_recovery() is called.
+ *
+ * @return
+ *      - ESP_OK: Transmit queue cleared
+ *      - ESP_ERR_INVALID_STATE: CAN driver is not installed or TX queue is disabled
+ */
+esp_err_t can_clear_transmit_queue();
+
+/**
+ * @brief   Clear the receive queue
+ *
+ * This function will clear the receive queue of all messages.
+ *
+ * @note    The receive queue is automatically cleared when can_start() is
+ *          called.
+ *
+ * @return
+ *      - ESP_OK: Transmit queue cleared
+ *      - ESP_ERR_INVALID_STATE: CAN driver is not installed
+ */
+esp_err_t can_clear_receive_queue();
+
 #ifdef __cplusplus
 }
 #endif