src: add title to header files

src/ad_parser.h

@@ -35,11 +35,10 @@
  *
  */
 
-// *****************************************************************************
-//
-// Advertising Data Parser 
-//
-// *****************************************************************************
+/**
+ * @title AD Data (Advertisements and EIR) Parser 
+ *
+ */
 
 #ifndef AD_PARSER_H
 #define AD_PARSER_H

src/ble/att_db.h

@@ -35,6 +35,10 @@
  *
  */
 
+/**
+ * @title ATT Database Engine
+ *
+ */
 
 #ifndef ATT_DB_H
 #define ATT_DB_H

src/ble/att_db_util.h

@@ -36,8 +36,10 @@
  */
 
 /**
- * Helper to construct ATT DB at runtime 
- * (BTstack GATT Compiler is not used)
+ * @title Runtine ATT Database Setup
+ * 
+ * Helper to construct ATT DB at runtime (BTstack GATT Compiler is not used).
+ *
  */
 
 #ifndef ATT_DB_UTIL_H

src/ble/att_dispatch.h

@@ -37,7 +37,10 @@
 
 
 /**
- * Dispatcher for independent implementation of ATT client and server
+ * @title ATT Dispatch
+ *
+ * Dispatcher for independent implementation of ATT client and server.
+ *
  */
 
 #ifndef ATT_DISPATCH_H

src/ble/att_server.h

@@ -34,6 +34,12 @@
  * contact@bluekitchen-gmbh.com
  *
  */
+
+/**
+ * @title ATT Server
+ *
+ */
+
 #ifndef ATT_SERVER_H
 #define ATT_SERVER_H
 

src/ble/gatt-service/ancs_client.h

@@ -35,10 +35,14 @@
  *
  */
 
+/**
+ * @title ANCS Client
+ * 
+ */
+
 #ifndef ANCS_CLIENT_H
 #define ANCS_CLIENT_H
 
-
 #include <stdint.h>
 #include "btstack_defines.h"
     

src/ble/gatt-service/battery_service_client.h

@@ -35,6 +35,11 @@
  *
  */
 
+/**
+ * @title Battery Service Client
+ * 
+ */
+
 #ifndef BATTERY_SERVICE_CLIENT_H
 #define BATTERY_SERVICE_CLIENT_H
 

src/ble/gatt-service/battery_service_server.h

@@ -34,6 +34,12 @@
  * contact@bluekitchen-gmbh.com
  *
  */
+
+/**
+ * @title Battery Service Server
+ * 
+ */
+
 #ifndef BATTERY_SERVICE_SERVER_H
 #define BATTERY_SERVICE_SERVER_H
 

src/ble/gatt-service/cycling_power_service_server.h

@@ -34,6 +34,12 @@
  * contact@bluekitchen-gmbh.com
  *
  */
+
+/**
+ * @title Cycling Power Service Server
+ * 
+ */
+
 #ifndef CYCLING_POWER_SERVICE_SERVER_H
 #define CYCLING_POWER_SERVICE_SERVER_H
 

src/ble/gatt-service/cycling_speed_and_cadence_service_server.h

@@ -34,6 +34,12 @@
  * contact@bluekitchen-gmbh.com
  *
  */
+
+/**
+ * @title Cycling Speed and Cadence Service Server
+ * 
+ */
+
 #ifndef CYCLING_SPEED_AND_CADENCE_SERVICE_SERVER_H
 #define CYCLING_SPEED_AND_CADENCE_SERVICE_SERVER_H
 

src/ble/gatt-service/device_information_service_client.h

@@ -35,6 +35,11 @@
  *
  */
 
+/**
+ * @title Device Information Service Client
+ * 
+ */
+
 #ifndef DEVICE_INFORMATION_SERVICE_CLIENT_H
 #define DEVICE_INFORMATION_SERVICE_CLIENT_H
 

src/ble/gatt-service/device_information_service_server.h

@@ -34,6 +34,12 @@
  * contact@bluekitchen-gmbh.com
  *
  */
+
+/**
+ * @title Device Information Service Server
+ * 
+ */
+
 #ifndef DEVICE_INFORMATION_SERVICE_SERVER_H
 #define DEVICE_INFORMATION_SERVICE_SERVER_H
 

src/ble/gatt-service/heart_rate_service_server.h

@@ -34,6 +34,12 @@
  * contact@bluekitchen-gmbh.com
  *
  */
+
+/**
+ * @title Heart Rate Service Server
+ * 
+ */
+
 #ifndef HEART_RATE_SERVICE_SERVER_H
 #define HEART_RATE_SERVICE_SERVER_H
 

src/ble/gatt-service/hids_client.h

@@ -35,6 +35,11 @@
  *
  */
 
+/**
+ * @title HID Service Client
+ * 
+ */
+
 #ifndef HIDS_CLIENT_H
 #define HIDS_CLIENT_H
 

src/ble/gatt-service/hids_device.h

@@ -34,6 +34,12 @@
  * contact@bluekitchen-gmbh.com
  *
  */
+
+/**
+ * @title HID Service Server
+ * 
+ */
+
 #ifndef HIDS_DEVICE_H
 #define HIDS_DEVICE_H
 

src/ble/gatt-service/mesh_provisioning_service_server.h

@@ -34,6 +34,12 @@
  * contact@bluekitchen-gmbh.com
  *
  */
+
+/**
+ * @title Mesh Provisioning Service Server
+ * 
+ */
+
 #ifndef __MESH_PROVISIONING_SERVICE_SERVER_H
 #define __MESH_PROVISIONING_SERVICE_SERVER_H
 

src/ble/gatt-service/mesh_proxy_service_server.h

@@ -34,6 +34,12 @@
  * contact@bluekitchen-gmbh.com
  *
  */
+
+/**
+ * @title Mesh Proxy Service Server
+ * 
+ */
+
 #ifndef __MESH_PROXY_SERVICE_SERVER_H
 #define __MESH_PROXY_SERVICE_SERVER_H
 

src/ble/gatt-service/nordic_spp_service_server.h

@@ -34,6 +34,12 @@
  * contact@bluekitchen-gmbh.com
  *
  */
+
+/**
+ * @title Nordic SPP Service Server
+ * 
+ */
+
 #ifndef NORDIC_SPP_H
 #define NORDIC_SPP_H
 

src/ble/gatt-service/scan_parameters_service_client.h

@@ -35,6 +35,11 @@
  *
  */
 
+/**
+ * @title Scan Parameters Service Client
+ * 
+ */
+
 /** 
  * @text The Scan Parameters Service Client allows to store its 
  * LE scan parameters on a remote device such that the remote device 

src/ble/gatt-service/scan_parameters_service_server.h

@@ -34,6 +34,12 @@
  * contact@bluekitchen-gmbh.com
  *
  */
+
+/**
+ * @title Scan Parameters Service Server
+ * 
+ */
+
 #ifndef SCAN_PARAMETERS_H
 #define SCAN_PARAMETERS_H
 

src/ble/gatt-service/ublox_spp_service_server.h

@@ -34,6 +34,12 @@
  * contact@bluekitchen-gmbh.com
  *
  */
+
+/**
+ * @title u-blox SPP Service Server
+ * 
+ */
+
 #ifndef UBLOX_SPP_H
 #define UBLOX_SPP_H
 

src/ble/gatt_client.h

@@ -35,6 +35,10 @@
  *
  */
 
+/**
+ * @title GATT Client
+ *
+ */
 
 #ifndef btstack_gatt_client_h
 #define btstack_gatt_client_h

src/ble/le_device_db.h

@@ -35,6 +35,11 @@
  *
  */
  
+/**
+ * @title Device Database
+ *
+ */
+
 #ifndef LE_DEVICE_DB_H
 #define LE_DEVICE_DB_H
 

src/ble/le_device_db_tlv.h

@@ -34,7 +34,12 @@
  * contact@bluekitchen-gmbh.com
  *
  */
- 
+
+/**
+ * @title Device Database TLV
+ * 
+ */
+
 #ifndef LE_DEVICE_DB_TLV_H
 #define LE_DEVICE_DB_TLV_H
 

src/ble/sm.h

@@ -35,10 +35,15 @@
  *
  */
 
+/**
+ * @title Security Manager
+ * 
+ */
+
 #ifndef SM_H
 #define SM_H
 
- #if defined __cplusplus
+#if defined __cplusplus
 extern "C" {
 #endif
 

src/btstack_audio.h

@@ -35,6 +35,12 @@
  *
  */
 
+/** 
+ * @title Audio Interface
+ *
+ * Abstraction layer for 16-bit audio playback and recording within BTstack.
+ */
+
 #ifndef BTSTACK_AUDIO_H
 #define BTSTACK_AUDIO_H
 
@@ -44,11 +50,7 @@
 extern "C" {
 #endif
 
-/*
- *  btstack_audio.h
- *
- *  Abstraction layer for 16-bit audio playback and recording within BTstack
- */
+/* API_START */
 
 typedef struct {
 
@@ -158,6 +160,8 @@ const btstack_audio_sink_t *   btstack_audio_embedded_sink_get_instance(void);
 const btstack_audio_source_t * btstack_audio_embedded_source_get_instance(void);
 
 const btstack_audio_sink_t *   btstack_audio_esp32_sink_get_instance(void);
+/* API_END */
+
 // const btstack_audio_source_t *   btstack_audio_esp32_source_get_instance(void);
 
 #if defined __cplusplus

src/btstack_base64_decoder.h

@@ -35,8 +35,9 @@
  *
  */
 
-/*
- *  btstack_base64_decoder.h
+/**
+ * @title base64 Decoder
+ *
  */
 
 #ifndef BTSTACK_BASE_64_DECODER_H
@@ -44,11 +45,17 @@
 
 #include <stdint.h>
 
+#if defined __cplusplus
+extern "C" {
+#endif
+
 typedef struct {
     uint8_t pos;
     uint8_t value;
 } btstack_base64_decoder_t;
 
+/* API_START */
+
 #define BTSTACK_BASE64_DECODER_MORE     -1
 #define BTSTACK_BASE64_DECODER_COMPLETE -2
 #define BTSTACK_BASE64_DECODER_INVALID  -3
@@ -77,4 +84,10 @@ int  btstack_base64_decoder_process_byte(btstack_base64_decoder_t * context, uin
  */
 int btstack_base64_decoder_process_block(const uint8_t * input_data, uint32_t input_size, uint8_t * output_buffer, uint32_t output_max_size);
 
+/* API_END */
+
+#if defined __cplusplus
+}
 #endif
+
+#endif // BTSTACK_BASE_64_DECODER_H

src/btstack_chipset.h

@@ -35,11 +35,12 @@
  *
  */
 
-/*
- *  btstack_chipset.h
+/**
+ * @title Chipset Driver 
+ * 
+ * The API implements custom chipset initialization and support of proprietary extensions
+ * to set UART baud rate, Bluetooth Address, and similar.
  *
- *  Chipset Driver - implements custom chipset initializtion and support proprietary extensions
- *  to set UART baud rate, Bluetooth Address, and similar.
  */
 
 #ifndef BTSTACK_CHIPSET_H

src/btstack_control.h

@@ -35,10 +35,10 @@
  *
  */
 
-/*
- *  btstack_control.h
+/**
+ * @title BTstack Bluetooth Hardware Control
  *
- *  BTstack Bluetooth Hardware Control API -- allows HCI to manage Bluetooth chipsets via direct hardware controls
+ * The API allows HCI to manage Bluetooth chipsets via direct hardware controls.
  *
  */
 

src/btstack_crypto.h

@@ -35,8 +35,8 @@
  *
  */
 
-/*
- * btstack_crypto.h
+/**
+ * Crypto-related functions
  *
  * Central place for all crypto-related functions with completion callbacks to allow
  * using of MCU crypto peripherals or the Bluetooth controller

src/btstack_debug.h

@@ -35,10 +35,11 @@
  *
  */
 
-/*
- *  btstack_debug.h
+/**
+ * @title Debug Messages
+ *
+ * Allow to funnel debug and error messages. 
  *
- *  allow to funnel debug & error messages 
  */
 
 #ifndef DEBUG_H
@@ -112,8 +113,11 @@ void btstack_assert_failed(const char * file, uint16_t line_nr);
 #define log_error(...) (void)(0)
 #endif
 
+/* API_START */
+
 /** 
  * @brief Log Security Manager key via log_info
+ * @param name
  * @param key to log
  */
 void log_info_key(const char * name, sm_key_t key);
@@ -126,9 +130,12 @@ void log_info_key(const char * name, sm_key_t key);
 void log_info_hexdump(const void *data, int size);
 
 /**
- * @brief Hexdump via log_debug * @param data
+ * @brief Hexdump via log_debug 
+ * @param data
  * @param size
  */
 void log_debug_hexdump(const void *data, int size);
 
+/* API_END */
+
 #endif // DEBUG_H

src/btstack_defines.h

@@ -35,10 +35,11 @@
  *
  */
 
-/*
- * btstack-defines.h
+/**
  *
- * BTstack definitions, events, and error codes */
+ * BTstack definitions, events, and error codes 
+ *
+ */
 
 #ifndef BTSTACK_DEFINES_H
 #define BTSTACK_DEFINES_H

src/btstack_em9304_spi.h

@@ -35,12 +35,13 @@
  *
  */
 
-/*
- *  btstack_em9304_spi.h
+/**
+ * @title EM9304 SPI
+ *
+ * BTstack's Hardware Abstraction Layer for EM9304 connected via SPI with additional RDY Interrupt line.
  *
- *  BTstack's Hardware Abstraction Layer for EM9304 connected via SPI with additional RDY Interrupt line
-
  */
+
 #ifndef BTSTACK_EM9304_SPI_H
 #define BTSTACK_EM9304_SPI_H
 
@@ -55,8 +56,6 @@ extern "C" {
 #include <stdint.h>
 typedef struct {
 
-    /* API_START */
-
     /**
      * @brief Open SPI
      */
@@ -121,10 +120,12 @@ typedef struct {
 } btstack_em9304_spi_t;
 
 /**
- *
+ * @brief Get EM9304 SPI instance
  */
 const btstack_em9304_spi_t * btstack_em9304_spi_embedded_instance(void);
 
+/* API_END */
+
 #if defined __cplusplus
 }
 #endif

src/btstack_event.h

@@ -35,12 +35,10 @@
  *
  */
 
-
-/*
- *  btstack_event.h
- *
- *  @brief BTstack event getter/setter
- *  @note  Don't edit - generated by tool/btstack_event_generator.py
+/**
+ * @title HCI Event Getter
+ *  
+ * Note: Don't edit this file. It is generated by tool/btstack_event_generator.py
  *
  */
 

src/btstack_hid.h

@@ -35,6 +35,11 @@
  *
  */
 
+/**
+ * @title Human Interface Device (HID)
+ *
+ */
+
 #ifndef HID_H
 #define HID_H
 

src/btstack_hid_parser.h

@@ -35,10 +35,11 @@
  *
  */
 
-/*
- *  btstack_hid_parser.h
+/**
+ * @title HID Parser
+ *
+ * Single-pass HID Report Parser: HID Report is directly parsed without preprocessing HID Descriptor to minimize memory.
  *
- *  Single-pass HID Report Parser: HID Report is directly parsed without preprocessing HID Descriptor to minimize memory
  */
 
 #ifndef BTSTACK_HID_PARSER_H

src/btstack_linked_list.h

@@ -35,8 +35,9 @@
  *
  */
 
-/*
- *  btstack_linked_list.h
+/**
+ * @title Linked List
+ *
  */
 
 #ifndef BTSTACK_LINKED_LIST_H

src/btstack_linked_queue.h

@@ -35,8 +35,9 @@
  *
  */
 
-/*
- *  btstack_linked_queue.h
+/**
+ * @title Linked Queue
+ *
  */
 
 #ifndef BTSTACK_LINKED_QUEUE_H

src/btstack_memory.h

@@ -35,12 +35,10 @@
  *
  */
 
-
-
-/*
- *  btstack_memory.h
+/**
+ * @title BTstack Memory Management
  *
- *  @brief BTstack memory management via configurable memory pools
+ * BTstack memory management is performed via configurable memory pools.
  *
  */
 

src/btstack_network.h

@@ -34,9 +34,9 @@
  *
  */
 
-/*
- *  btstack_network.h
- *  Network interface abstraction
+/**
+ * @title Network Interface
+ *
  */
 
 #ifndef BTSTACK_NETWORK_H
@@ -49,6 +49,8 @@
 extern "C" {
 #endif
 
+/* API_START */
+
 /**
  * @brief Initialize network interface
  * @param send_packet_callback
@@ -88,6 +90,8 @@ void btstack_network_packet_sent(void);
  */
 const char * btstack_network_get_name(void);
 
+/* API_END */
+
 #if defined __cplusplus
 }
 #endif

src/btstack_resample.h

@@ -35,6 +35,13 @@
  *
  */
 
+/**
+ * @title Lienar Resampling
+ *
+ * Linear resampling for 16-bit audio code samples using 16 bit/16 bit fixed point math.
+ *
+ */
+
 #ifndef BTSTACK_RESAMPLE_H
 #define BTSTACK_RESAMPLE_H
 
@@ -44,12 +51,6 @@
 extern "C" {
 #endif
 
-/*
- *  btstack_resample.h
- *
- *  Linear resampling for 16-bit audio code samples using 16 bit/16 bit fixed point math
- */
-
 #define BTSTACK_RESAMPLE_MAX_CHANNELS 2
 
 typedef struct {
@@ -59,6 +60,8 @@ typedef struct {
     int      num_channels;
 } btstack_resample_t;
 
+/* API_START */
+
 /**
  * @brief Init resample context
  * @param num_channels
@@ -82,6 +85,8 @@ void btstack_resample_set_factor(btstack_resample_t * context, uint32_t factor);
  */
 uint16_t btstack_resample_block(btstack_resample_t * context, const int16_t * input_buffer, uint32_t num_frames, int16_t * output_buffer);
 
+/* API_END */
+
 #if defined __cplusplus
 }
 #endif

src/btstack_ring_buffer.h

@@ -35,8 +35,9 @@
  *
  */
 
-/*
- *  btstack_ring_buffer.h
+/**
+ * @title Ring Buffer
+ *
  */
 
 #ifndef BTSTACK_RING_BUFFER_H
@@ -56,6 +57,8 @@ typedef struct btstack_ring_buffer {
     uint8_t  full;
 } btstack_ring_buffer_t;
 
+/* API_START */
+
 /**
  * Init ring buffer
  * @param ring_buffer object
@@ -109,6 +112,8 @@ int btstack_ring_buffer_write(btstack_ring_buffer_t * ring_buffer, uint8_t * dat
  */
 void btstack_ring_buffer_read(btstack_ring_buffer_t * ring_buffer, uint8_t * buffer, uint32_t length, uint32_t * number_of_bytes_read); 
 
+/* API_END */
+
 #if defined __cplusplus
 }
 #endif

src/btstack_run_loop.h

@@ -35,10 +35,9 @@
  *
  */
 
-/*
- *  run_loop.h
+/**
+ * @title Run Loop
  *
- *  Created by Matthias Ringwald on 6/6/09.
  */
 
 #ifndef btstack_run_loop_H
@@ -55,7 +54,6 @@
 extern "C" {
 #endif
 	
-
 /**
  * Callback types for run loop data sources
  */

src/btstack_sco_transport.h

@@ -35,9 +35,11 @@
  *
  */
 
-/*
- * btstack_sco_transport.h
- * Hardware abstraction for PCM/I2S Inteface used for HSP/HFP profiles
+/**
+ * @title SCO Transport
+ *
+ * Hardware abstraction for PCM/I2S Inteface used for HSP/HFP profiles.
+ *
  */
 
 #ifndef BTSTACK_SCO_TRANSPORT_H
@@ -59,6 +61,8 @@ typedef enum {
     SCO_FORMAT_16_BIT,
 } sco_format_t;
 
+/* API_START */
+
 typedef struct {
 
     /**
@@ -86,6 +90,8 @@ typedef struct {
 
 } btstack_sco_transport_t;
 
+/* API_END */
+
 #if defined __cplusplus
 }
 #endif

src/btstack_slip.h

@@ -35,9 +35,9 @@
  *
  */
 
-/*
- *  btstack_slip.h
- *  SLIP encoder/decoder
+/**
+ * @title SLIP encoder/decoder
+ *
  */
 
 #ifndef BTSTACK_SLIP_H
@@ -51,6 +51,8 @@ extern "C" {
 
 #define BTSTACK_SLIP_SOF 0xc0
 
+/* API_START */
+
 // ENCODER
 
 /**
@@ -95,6 +97,8 @@ void btstack_slip_decoder_process(uint8_t input);
 
 uint16_t btstack_slip_decoder_frame_size(void);
 
+/* API_END */
+
 #if defined __cplusplus
 }
 #endif

src/btstack_tlv.h

@@ -29,11 +29,12 @@
  *
  */
 
-/*
- *  btstack_tlv_.h
+/**
+ * @title Tag-Value-Length Persistent Storage (TLV)
+ *
+ * Inteface for BTstack's Tag Value Length Persistent Storage implementations
+ * used to store pairing/bonding data.
  *
- *  Inteface for BTstack's Tag Value Length Persistent Storage implementations
- *  used to store pairing/bonding data
  */
 
 #ifndef BTSTACK_TLV_H
@@ -45,6 +46,8 @@
 extern "C" {
 #endif
 
+/* API_START */
+
 typedef struct {
 
 	/**
@@ -92,6 +95,8 @@ void btstack_tlv_set_instance(const btstack_tlv_t * tlv_impl, void * tlv_context
  */
 void btstack_tlv_get_instance(const btstack_tlv_t ** tlv_impl, void ** tlv_context);
 
+/* API_END */
+
 #if defined __cplusplus
 }
 #endif

src/btstack_tlv_none.h

@@ -29,11 +29,11 @@
  *
  */
 
-/*
- *  btstack_tlv_none.h
+/**
+ * @title Empty TLV Instance
  *
- *  Empty implementation for BTstack's Tag Value Length Persistent Storage implementations
- *  No keys are stored. Can be used as placeholder during porting to new platform. 
+ * Empty implementation for BTstack's Tag Value Length Persistent Storage implementations
+ * No keys are stored. Can be used as placeholder during porting to new platform. 
  */
 
 #ifndef BTSTACK_TLV_NONE_H
@@ -46,6 +46,8 @@
 extern "C" {
 #endif
 
+/* API_START */
+
 /**
  * Init Tag Length Value Store
  * @param context btstack_tlv_none_t 
@@ -54,6 +56,8 @@ extern "C" {
  */
 const btstack_tlv_t * btstack_tlv_none_init_instance(void);
 
+/* API_END */
+
 #if defined __cplusplus
 }
 #endif

src/btstack_uart.h

@@ -35,10 +35,10 @@
  *
  */
 
-/*
- *  btstack_uart.h
+/**
+ * @title UART
  *
- *  Common types for UART transports
+ * Common types for UART transports
  *
  */
 
@@ -76,6 +76,8 @@ typedef struct {
     int                   parity;
 } btstack_uart_config_t;
 
+/* API_START */
+
 typedef struct {
     /**
      * init transport
@@ -177,6 +179,8 @@ typedef struct {
 
 } btstack_uart_t;
 
+/* API_END */
+
 // common implementations
 const btstack_uart_t * btstack_uart_posix_instance(void);
 

src/btstack_uart_block.h

@@ -35,10 +35,11 @@
  *
  */
 
-/*
- *  btstack_uart_block.h
+/**
+ * @title UART Block
+ *
+ * Compatibility layer for ports that use btstack_uart_block_t 
  *
- *  Compatibility layer for ports that use btstack_uart_block_t 
  */
 
 #ifndef BTSTACK_UART_BLOCK_H
@@ -51,6 +52,8 @@
 extern "C" {
 #endif
 
+/* API_START */
+
 typedef btstack_uart_t btstack_uart_block_t;
 
 // existing block-only implementations
@@ -62,6 +65,7 @@ const btstack_uart_t * btstack_uart_block_freertos_instance(void);
 static inline const btstack_uart_block_t * btstack_uart_block_posix_instance(void){
     return (const btstack_uart_block_t *) btstack_uart_posix_instance();
 }
+/* API_STOP */
 
 #if defined __cplusplus
 }

src/btstack_uart_slip_wrapper.h

@@ -35,13 +35,14 @@
  *
  */
 
-/*
- *  btstack_uart_slip_wrapper.h
+/**
+ * @title UART SLIP Wrapper
  *
- *  Compatibility layer to use new H5 implementation with btstack_uart.h implementations without SLIP support
- *  Using this compatibility layer caused increased processing as it uses single byte UART reads
+ * Compatibility layer to use new H5 implementation with btstack_uart.h implementations without SLIP support.
+ * Using this compatibility layer caused increased processing as it uses single byte UART reads.
+ *
+ * If you're using H5, please consider implement the H5/SLIP functions in your btstack_uart.h or hal_uart_dma.h implementation.
  *
- *  If you're using H5, please consider implement the H5/SLIP functions in your btstack_uart.h or hal_uart_dma.h implementation
  */
 
 #ifndef BTSTACK_UART_SLIP_WRAPPER_H
@@ -50,6 +51,8 @@
 #include <stdint.h>
 #include "btstack_uart.h"
 
+/* API_START */
+
 /**
  * @brief Initialize SLIP wrapper for existing btstack_uart_block_t instance without SLIP support
  * @param uart_block_without_slip
@@ -57,4 +60,6 @@
  */
 const btstack_uart_t * btstack_uart_slip_wrapper_instance(const btstack_uart_t * uart_without_slip);
 
+/* API_END */
+
 #endif

src/btstack_util.h

@@ -35,14 +35,11 @@
  *
  */
 
-/*
- *  btstack_util.h
+/**
+ * @title General Utility Functions
  *
- *  General utility functions
- *
- *  Created by Matthias Ringwald on 7/23/09.
  */
-
+ 
 #ifndef BTSTACK_UTIL_H
 #define BTSTACK_UTIL_H
 

src/classic/a2dp_sink.h

@@ -35,12 +35,11 @@
  *
  */
 
-/*
- * a2dp_sink.h
- * 
- * Advanced Audio Distribution Transport Profile (A2DP) Sink
+/**
+ * @title A2DP Sink
+ *
+ * Audio/Video Distribution Transport Protocol A2DP Sink is a device that accepts streamed media data.  
  *
- * A2DP Sink is a device that accepts streamed media data.  
  */
 
 #ifndef A2DP_SINK_H

src/classic/a2dp_source.h

@@ -35,12 +35,11 @@
  *
  */
 
-/*
- * a2dp_source.h
- * 
- * Advanced Audio Distribution Transport Profile (A2DP) Source
+/**
+ * @title A2DP Source
+ *
+ *  Audio/Video Distribution Transport Protocol A2DP Source is a device that streames media data.
  *
- * A2DP Source is a device that streames media data.
  */
 
 #ifndef A2DP_SOURCE_H

src/classic/avdtp.h

@@ -35,10 +35,8 @@
  *
  */
 
-/*
- * avdtp.h
- * 
- * Audio/Video Distribution Transport Protocol
+/**
+ * Audio/Video Distribution Transport Protocol (AVDTP)
  *
  * This protocol defines A/V stream negotiation, establishment, and transmission 
  * procedures. Also specified are the message formats that are exchanged between 

src/classic/avdtp_acceptor.h

@@ -35,9 +35,7 @@
  *
  */
 
-/*
- * avdtp_acp.h
- * 
+/**
  * Audio/Video Distribution Transport Protocol - Acceptor Role
  *
  */

src/classic/avdtp_initiator.h

@@ -35,9 +35,7 @@
  *
  */
 
-/*
- * avdtp_int.h
- * 
+/**
  * Audio/Video Distribution Transport Protocol - Initiator Role
  *
  */

src/classic/avdtp_sink.h

@@ -35,12 +35,11 @@
  *
  */
 
-/*
- * avdtp_sink.h
- * 
- * Audio/Video Distribution Transport Protocol (AVDTP) Sink
+/**
+ * @title AVDTP Sink
+ *
+ * Audio/Video Distribution Transport Protocol (AVDTP) Sink is a device that accepts streamed media data.  
  *
- * AVDTP Sink is a device that accepts streamed media data.  
  */
 
 #ifndef AVDTP_SINK_H

src/classic/avdtp_source.h

@@ -35,12 +35,11 @@
  *
  */
 
-/*
- * avdtp_source.h
- * 
- * Audio/Video Distribution Transport Protocol Source
+/**
+ * @title AVDTP Source
+ *
+ * Audio/Video Distribution Transport Protocol (AVDTP) Source is a device that streames media data.
  *
- * AVDTP Source is a device that streames media data.
  */
 
 #ifndef AVDTP_SOURCE_H

src/classic/avdtp_util.h

@@ -35,9 +35,7 @@
  *
  */
 
-/*
- * avdtp_util.h
- * 
+/**
  * Audio/Video Distribution Transport Protocol - Utils
  *
  */

src/classic/avrcp.h

@@ -35,10 +35,8 @@
  *
  */
 
-/*
- * avrcp.h
- * 
- * Audio/Video Remote Control Profile
+/**
+ * Audio/Video Remote Control Profile (AVRCP)
  *
  */
 

src/classic/avrcp_browsing.h

@@ -35,10 +35,8 @@
  *
  */
 
-/*
- * avrcp_browsing.h
- * 
- * Audio/Video Remote Control Profile (Browsing)
+/**
+ * @title AVRCP Browsing
  *
  */
 

src/classic/avrcp_browsing_controller.h

@@ -35,10 +35,8 @@
  *
  */
 
-/*
- * avrcp_browsing_controller.h
- * 
- * Audio/Video Remote Control Profile Browsing
+/**
+ * @title AVRCP Browsing Controller
  *
  */
 

src/classic/avrcp_browsing_target.h

@@ -35,10 +35,8 @@
  *
  */
 
-/*
- * avrcp_browsing_target.h
- * 
- * Audio/Video Remote Control Profile Browsing
+/**
+ * @title AVRCP Browsing Target
  *
  */
 

src/classic/avrcp_controller.h

@@ -35,10 +35,8 @@
  *
  */
 
-/*
- * avrcp.h
- * 
- * Audio/Video Remote Control Profile
+/**
+ * @title AVRCP Controller
  *
  */
 

src/classic/avrcp_media_item_iterator.h

@@ -35,11 +35,10 @@
  *
  */
 
-// *****************************************************************************
-//
-// AVRCP Media Item Iterator 
-//
-// *****************************************************************************
+/**
+ * @title AVRCP Media Item Iterator 
+ *
+ */
 
 #ifndef AVRCP_MEDIA_ITEM_ITERATOR_H
 #define AVRCP_MEDIA_ITEM_ITERATOR_H

src/classic/avrcp_target.h

@@ -36,9 +36,7 @@
  */
 
 /*
- * avrcp_target.h
- * 
- * Audio/Video Remote Control Profile
+ * @title AVRCP Target
  *
  */
 

src/classic/bnep.h

@@ -35,12 +35,15 @@
  *
  */
 
-/*
- * bnep.h
- * Author: Ole Reinhardt <ole.reinhardt@kernelconcepts.de>
+/**
+ * @title BNEP
  *
  */
 
+/**
+ * @author: Ole Reinhardt <ole.reinhardt@kernelconcepts.de>
+ */
+
 #ifndef BNEP_H
 #define BNEP_H
  

src/classic/btstack_cvsd_plc.h

@@ -35,8 +35,8 @@
  *
  */
 
-/*
- * btstack_cvsd_plc.h
+/**
+ * CVSD Packet Loss Concealment 
  *
  */
 

src/classic/btstack_link_key_db.h

@@ -36,7 +36,10 @@
  */
 
 /**
- * interface to provide link key storage
+ * @title Link Key DB
+ * 
+ * Interface to provide link key storage.
+ *
  */
 
 #ifndef BTSTACK_LINK_KEY_DB_H

src/classic/btstack_link_key_db_memory.h

@@ -36,7 +36,8 @@
  */
 
 /**
- * interface to provide link key storage
+ * @title In-Memory Link Key Storage
+ *
  */
 
 #ifndef BTSTACK_LINK_KEY_DB_MEMORY_H
@@ -49,6 +50,8 @@
 extern "C" {
 #endif
 
+/* API_START */
+
 /*
  * @brief
  */

src/classic/btstack_link_key_db_static.h

@@ -36,9 +36,12 @@
  */
 
 /**
- *  Static Link Key implementation to use during development/porting:
+ * @title Static Link Key Storage
+ *  
+ * Static Link Key Storage implementation to use during development/porting:
  *  - Link keys have to be manually added to this file to make them usable
  *  + Link keys are preserved on reflash in constrast to the program flash based link key store
+ *
  */
 
 #ifndef BTSTACK_LINK_KEY_DB_STATIC_H
@@ -50,6 +53,8 @@
 extern "C" {
 #endif
 
+/* API_START */
+
 /*
  * @brief
  */

src/classic/btstack_link_key_db_tlv.h

@@ -36,7 +36,10 @@
  */
 
 /**
- * interface to provide link key storage via BTstack's TLV storage
+ * @title Link Key TLV Storage
+ *
+ * Interface to provide link key storage via BTstack's TLV storage.
+ *
  */
 
 #ifndef BTSTACK_LINK_KEY_DB_TLV_H

src/classic/btstack_sbc.h

@@ -35,8 +35,8 @@
  *
  */
 
-/*
- * btstack_sbc.h
+/**
+ * SBC
  *
  */
 

src/classic/btstack_sbc_plc.h

@@ -35,8 +35,8 @@
  *
  */
 
-/*
- * btstack_sbc_plc.h
+/**
+ * SBC Packet Loss Concealment
  *
  */
 

src/classic/device_id_server.h

@@ -35,10 +35,11 @@
  *
  */
 
-/*
- * device_id_server.h
+/**
+ * @title Device ID Server
  * 
- * Create Device ID SDP Records
+ * Create Device ID SDP Records.
+ *
  */
 
 #ifndef DEVICE_ID_SERVER_H

src/classic/gatt_sdp.h

@@ -35,8 +35,9 @@
  *
  */
 
-/*
- *  gatt_sdp.h
+/**
+ * @title GATT SDP
+ *
  */
 
 #ifndef GATT_SDP_H

src/classic/goep_client.h

@@ -35,6 +35,13 @@
  *
  */
 
+/**
+ * @title GOEP Client 
+ *
+ * Communicate with remote OBEX server - General Object Exchange
+ *
+ */
+
 #ifndef GOEP_CLIENT_H
 #define GOEP_CLIENT_H
 
@@ -47,12 +54,6 @@ extern "C" {
 
 #include "btstack_defines.h"
 
-//------------------------------------------------------------------------------------------------------------
-// goep_client.h
-//
-// Communicate with remote OBEX server - General Object Exchange
-//
-
 /* API_START */
 
 // remote does not expose PBAP features in SDP record

src/classic/hfp.h

@@ -35,12 +35,10 @@
  *
  */
 
-// *****************************************************************************
-//
-//  HFP Hands-Free (HF) unit and Audio Gateway Commons
-//
-// *****************************************************************************
-
+/**
+ * HFP Hands-Free (HF) unit and Audio Gateway Commons
+ *
+ */
 
 #ifndef BTSTACK_HFP_H
 #define BTSTACK_HFP_H

src/classic/hfp_ag.h

@@ -35,12 +35,10 @@
  *
  */
 
-// *****************************************************************************
-//
-// HFP Audio Gateway (AG) unit
-//
-// *****************************************************************************
-
+/**
+ * @title HFP Audio Gateway (AG)
+ *
+ */
 
 #ifndef btstack_hfp_ag_h
 #define btstack_hfp_ag_h

src/classic/hfp_gsm_model.h

@@ -35,12 +35,10 @@
  *
  */
 
-// *****************************************************************************
-//
-//  GSM model 
-//
-// *****************************************************************************
-
+/**
+ * @title HFP GSM Model
+ *
+ */
 
 #ifndef BTSTACK_HFP_GSM_MODEL_H
 #define BTSTACK_HFP_GSM_MODEL_H

src/classic/hfp_hf.h

@@ -35,12 +35,10 @@
  *
  */
 
-// *****************************************************************************
-//
-//  HFP Hands-Free (HF) unit
-//
-// *****************************************************************************
-
+/**
+ * @title HFP Hands-Free (HF)
+ *
+ */
 
 #ifndef BTSTACK_HFP_HF_H
 #define BTSTACK_HFP_HF_H

src/classic/hfp_msbc.h

@@ -35,11 +35,10 @@
  *
  */
  
-// *****************************************************************************
-//
-// HFP mSBC encoder wrapper
-//
-// *****************************************************************************
+/**
+ * @title HFP mSBC Encoder 
+ *
+ */
 
 #ifndef HFP_MSBC_H
 #define HFP_MSBC_H

src/classic/hid_device.h

@@ -35,6 +35,11 @@
  *
  */
 
+/**
+ * @title HID Device
+ *
+ */
+
 #ifndef HID_DEVICE_H
 #define HID_DEVICE_H
 

src/classic/hid_host.h

@@ -35,6 +35,11 @@
  *
  */
 
+/**
+ * @title HID Host
+ *
+ */
+
 #ifndef HID_HOST_H
 #define HID_HOST_H
 

src/classic/hsp_ag.h

@@ -35,12 +35,10 @@
  *
  */
 
-// *****************************************************************************
-//
-// HSP Audio Gateway
-//
-// *****************************************************************************
-
+/**
+ * @title HSP Audio Gateway
+ *
+ */
 
 #ifndef btstack_hsp_ag_h
 #define btstack_hsp_ag_h

src/classic/hsp_hs.h

@@ -35,12 +35,11 @@
  *
  */
 
-// *****************************************************************************
-//
-// HSP Headset
-//
-// *****************************************************************************
 
+/**
+ * @title HSP Headset
+ *
+ */
 
 #ifndef btstack_hsp_hs_h
 #define btstack_hsp_hs_h

src/classic/obex_iterator.h

@@ -34,7 +34,12 @@
  * contact@bluekitchen-gmbh.com
  *
  */
- 
+
+/**
+ * OBEX Iterator
+ *
+ */
+
 #ifndef OBEX_ITERATOR_H
 #define OBEX_ITERATOR_H
 
@@ -45,7 +50,8 @@ extern "C" {
 #include <stdint.h>
 #include "btstack_bool.h"
 
-    /* API_START */
+
+/* API_START */
 
 typedef struct obex_iterator {
     const uint8_t * data;

src/classic/obex_message_builder.h

@@ -35,6 +35,11 @@
  *
  */
 
+/**
+ * OBEX Message Builder
+ *
+ */
+
 #ifndef OBEX_MESSAGE_BUILDER_H
 #define OBEX_MESSAGE_BUILDER_H
 

src/classic/pan.h

@@ -35,10 +35,10 @@
  *
  */
 
-/*
- *  pan.h
+
+/**
+ * @title Personal Area Network (PAN) 
  *
- *  Created by Milanka Ringwald on 10/16/14.
  */
 
 #ifndef PAN_H

src/classic/pbap_client.h

@@ -35,6 +35,11 @@
  *
  */
 
+/**
+ * @title PBAP Client
+ *
+ */
+
 #ifndef PBAP_CLIENT_H
 #define PBAP_CLIENT_H
 

src/classic/rfcomm.h

@@ -35,8 +35,9 @@
  *
  */
 
-/*
- *  RFCOMM.h
+/**
+ * @title RFCOMM
+ *
  */
 
 #ifndef RFCOMM_H

src/classic/sdp_client.h

@@ -35,8 +35,9 @@
  *
  */
 
-/*
- *  sdp_client.h
+/**
+ * @title SDP Client
+ *
  */
 
 #ifndef SDP_CLIENT_H

src/classic/sdp_client_rfcomm.h

@@ -35,8 +35,9 @@
  *
  */
 
-/*
- *  sdp_rfcomm_query.h
+/**
+ * @title SDP Client RFCOMM
+ *
  */
 
 #ifndef SDP_QUERY_RFCOMM_H

src/classic/sdp_server.h

@@ -34,6 +34,12 @@
  * contact@bluekitchen-gmbh.com
  *
  */
+
+/**
+ * @title SDP Server
+ *
+ */
+
 #ifndef SDP_H
 #define SDP_H
 

src/classic/sdp_util.h

@@ -35,8 +35,9 @@
  *
  */
 
-/*
- *  sdp_util.h
+/**
+ * @title SDP Utils
+ *
  */
 
 #ifndef SDP_UTIL_H

src/classic/spp_server.h

@@ -35,10 +35,11 @@
  *
  */
 
-/*
- * spp_server.h
- * 
- * Create SPP SDP Records
+/**
+ * @title SPP Server
+ *
+ * Create SPP SDP Records.
+ *
  */
 
 #ifndef SPP_SERVER_H

src/gap.h

@@ -35,6 +35,11 @@
  *
  */
 
+/**
+ * @title Genral Access Profile (GAP)
+ *
+ */
+
 #ifndef GAP_H
 #define GAP_H
 

src/hci.h

@@ -35,10 +35,8 @@
  *
  */
 
-/*
- *  hci.h
- *
- *  Created by Matthias Ringwald on 4/29/09.
+/**
+ * @title Host Controler Interface (HCI)
  *
  */
 

src/hci_cmd.h

@@ -35,10 +35,9 @@
  *
  */
 
-/*
- *  hci_cmd.h
+/**
+ *  HCI Command Builder and official commands
  *
- *  Created by Matthias Ringwald on 7/23/09.
  */
 
 #ifndef HCI_CMDS_H
@@ -419,8 +418,8 @@ extern const hci_cmd_t hci_ti_write_hardware_register;
  *   A: 31 bytes advertising data
  *   S: Service Record (Data Element Sequence)
  */
- uint16_t hci_cmd_create_from_template(uint8_t *hci_cmd_buffer, const hci_cmd_t *cmd, va_list argptr);
 
+uint16_t hci_cmd_create_from_template(uint8_t *hci_cmd_buffer, const hci_cmd_t *cmd, va_list argptr);
     
 #if defined __cplusplus
 }

src/hci_dump.h

@@ -35,12 +35,11 @@
  *
  */
 
-/*
- *  hci_dump.h
+/**
+ * @title HCI Logging
+ *
+ * Dump HCI trace as BlueZ's hcidump format, Apple's PacketLogger, or stdout.
  *
- *  Dump HCI trace as BlueZ's hcidump format, Apple's PacketLogger, or stdout
- * 
- *  Created by Matthias Ringwald on 5/26/09.
  */
 
 #ifndef HCI_DUMP_H