chore(ble): Make epic API headers look a bit nicer

epicardium/epicardium.h

@@ -2354,67 +2354,99 @@ enum epic_ble_event_type {
 	BLE_EVENT_DM_EVENT                                = 7,
 };
 
+/**
+ * MicroPython Bluetooth support data types. Please
+ * do not use them until they are stabilized.
+ */
+typedef uint8_t bdAddr_t[6];
+
 struct epic_wsf_header
 {
-  uint16_t        param;          /*!< \brief General purpose parameter passed to event handler */
-  uint8_t         event;          /*!< \brief General purpose event value passed to event handler */
-  uint8_t         status;         /*!< \brief General purpose status value passed to event handler */
+	/** General purpose parameter passed to event handler */
+	uint16_t param;
+	/** General purpose event value passed to event handler */
+	uint8_t event;
+	/** General purpose status value passed to event handler */
+	uint8_t status;
 };
 
 struct epic_att_event
 {
-  struct epic_wsf_header hdr;          /*!< \brief Header structure */
-  uint8_t               *pValue;      /*!< \brief Value */
-  uint16_t              valueLen;     /*!< \brief Value length */
-  uint16_t              handle;       /*!< \brief Attribute handle */
-  uint8_t                continuing;   /*!< \brief TRUE if more response packets expected */
-  uint16_t              mtu;          /*!< \brief Negotiated MTU value */
+	/** Header structure */
+	struct epic_wsf_header hdr;
+	/** Value */
+	uint8_t *pValue;
+	/** Value length */
+	uint16_t valueLen;
+	/** Attribute handle */
+	uint16_t handle;
+	/** TRUE if more response packets expected */
+	uint8_t continuing;
+	/** Negotiated MTU value */
+	uint16_t mtu;
 };
 
-#define BDA_ADDR_LEN 6
-typedef uint8_t bdAddr_t[BDA_ADDR_LEN];
-
 struct epic_hciLeConnCmpl_event
-{
-  struct epic_wsf_header hdr;        /*!< \brief Event header */
-  uint8_t             status;        /*!< \brief Status. */
-  uint16_t            handle;        /*!< \brief Connection handle. */
-  uint8_t             role;          /*!< \brief Local connection role. */
-  uint8_t             addrType;      /*!< \brief Peer address type. */
-  bdAddr_t            peerAddr;      /*!< \brief Peer address. */
-  uint16_t            connInterval;  /*!< \brief Connection interval */
-  uint16_t            connLatency;   /*!< \brief Connection latency. */
-  uint16_t            supTimeout;    /*!< \brief Supervision timeout. */
-  uint8_t             clockAccuracy; /*!< \brief Clock accuracy. */
-
-  /* \brief enhanced fields */
-  bdAddr_t            localRpa;      /*!< \brief Local RPA. */
-  bdAddr_t            peerRpa;       /*!< \brief Peer RPA. */
+{        /** Event header */
+	struct epic_wsf_header hdr;
+	/** Status. */
+	uint8_t status;
+	/** Connection handle. */
+	uint16_t handle;
+	/** Local connection role. */
+	uint8_t role;
+	/** Peer address type. */
+	uint8_t addrType;
+	/** Peer address. */
+	bdAddr_t peerAddr;
+	/** Connection interval */
+	uint16_t connInterval;
+	/** Connection latency. */
+	uint16_t connLatency;
+	/** Supervision timeout. */
+	uint16_t supTimeout;
+	/** Clock accuracy. */
+	uint8_t clockAccuracy;
+
+	/** enhanced fields */
+	/** Local RPA. */
+	bdAddr_t localRpa;
+	/** Peer RPA. */
+	bdAddr_t peerRpa;
 };
 
 /*! \brief Disconnect complete event */
 struct epic_hciDisconnectCmpl_event
 {
-  struct epic_wsf_header hdr;        /*!< \brief Event header */
-  uint8_t             status;        /*!< \brief Disconnect complete status. */
-  uint16_t            handle;        /*!< \brief Connect handle. */
-  uint8_t             reason;        /*!< \brief Reason. */
+	/** Event header */
+	struct epic_wsf_header hdr;
+	/** Disconnect complete status. */
+	uint8_t status;
+	/** Connect handle. */
+	uint16_t handle;
+	/** Reason. */
+	uint8_t reason;
 };
 
-
 struct epic_dm_event
 {
 	union {
-		struct epic_hciLeConnCmpl_event     leConnCmpl;                  /*!< \brief LE connection complete. */
-		struct epic_hciDisconnectCmpl_event disconnectCmpl;              /*!< \brief Disconnect complete. */
+		/** LE connection complete. */
+		struct epic_hciLeConnCmpl_event leConnCmpl;
+		/** Disconnect complete. */
+		struct epic_hciDisconnectCmpl_event disconnectCmpl;
 	};
 };
 
 struct epic_att_write
 {
-  struct epic_wsf_header hdr;          /*!< \brief Header structure */
-  uint16_t              valueLen;     /*!< \brief Value length */
-  uint16_t              handle;       /*!< \brief Attribute handle */
+	/** Header structure */
+	struct epic_wsf_header hdr;
+	/** Value length */
+	uint16_t valueLen;
+	/** Attribute handle */
+	uint16_t handle;
+
 	uint8_t operation;
 	uint16_t offset;
 	void *buffer;
@@ -2431,21 +2463,29 @@ struct epic_ble_event {
 };
 
 /**
- * Scan report data. Bases on ``hciLeAdvReportEvt_t`` from BLE stack.
+ * Scan report data. Based on ``hciLeAdvReportEvt_t`` from BLE stack.
  *
  * TODO: 64 bytes for data is an arbitrary number ATM */
 struct epic_scan_report
 {
-  uint8_t             data[64];       /*!< \brief advertising or scan response data. */
-  uint8_t             len;            /*!< \brief length of advertising or scan response data. */
-  int8_t              rssi;           /*!< \brief RSSI. */
-  uint8_t             eventType;      /*!< \brief Advertising event type. */
-  uint8_t             addrType;       /*!< \brief Address type. */
-  uint8_t             addr[6];        /*!< \brief Device address. */
-
-  /* \brief direct fields */
-  uint8_t             directAddrType; /*!< \brief Direct advertising address type. */
-  uint8_t             directAddr[6];  /*!< \brief Direct advertising address. */
+	/** advertising or scan response data. */
+	uint8_t data[64];
+	/** length of advertising or scan response data. */
+	uint8_t len;
+	/** RSSI. */
+	int8_t rssi;
+	/** Advertising event type. */
+	uint8_t eventType;
+	/** Address type. */
+	uint8_t addrType;
+	/** Device address. */
+	uint8_t addr[6];
+
+	/** direct fields */
+	/** Direct advertising address type. */
+	uint8_t directAddrType;
+	/** Direct advertising address. */
+	uint8_t directAddr[6];
 };
 
 /**
@@ -2591,6 +2631,15 @@ API(API_BLE_GET_SCAN_REPORT, int epic_ble_get_scan_report(struct epic_scan_repor
  */
 API(API_BLE_HID_SEND_REPORT, int epic_ble_hid_send_report(uint8_t report_id, uint8_t *data, uint8_t len));
 
+
+/**
+ * MicroPython BLE support API
+ *
+ * Please do not use this API outside the MicroPython Bluetooth module. The API designed to work
+ * specifically with that module.
+ *
+ * The MicroPython Bluetooth module is still in flux so this API will continue to change as well.
+ */
 API(API_BLE_ATTS_DYN_CREATE_GROUP, int epic_atts_dyn_create_service(const uint8_t *uuid, uint8_t uuid_len, uint16_t group_size, void **pSvcHandle, uint16_t *start_handle));
 //API(API_BLE_ATTS_DYN_DELETE_GROUP, void AttsDynDeleteGroup(void *pSvcHandle));
 API(API_BLE_ATTS_DYN_DELETE_GROUPS, int epic_ble_atts_dyn_delete_groups(void));