From 17166fefafb194dbf12a5fe8d3f4db4b75958f63 Mon Sep 17 00:00:00 2001
From: Szymon Janc <szymon.janc@codecoup.pl>
Date: Fri, 18 May 2018 14:37:51 +0200
Subject: [PATCH] nimble/host: Add doxygen for ble_hs_mbuf.h

---
 nimble/host/include/host/ble_hs_mbuf.h | 43 ++++++++++++++++++++++++++
 nimble/host/src/ble_hs_mbuf.c          | 37 ----------------------
 2 files changed, 43 insertions(+), 37 deletions(-)

diff --git a/nimble/host/include/host/ble_hs_mbuf.h b/nimble/host/include/host/ble_hs_mbuf.h
index 2b98c7111..fb7b12e60 100644
--- a/nimble/host/include/host/ble_hs_mbuf.h
+++ b/nimble/host/include/host/ble_hs_mbuf.h
@@ -20,6 +20,13 @@
 #ifndef H_BLE_HS_MBUF_
 #define H_BLE_HS_MBUF_
 
+/**
+ * @brief Bluetooth Host chained memory buffer (mbuf)
+ * @defgroup bt_host_mbuf Bluetooth Host chained memory buffer (mbuf)
+ * @ingroup bt_host
+ * @{
+ */
+
 #include <inttypes.h>
 #ifdef __cplusplus
 extern "C" {
@@ -27,8 +34,40 @@ extern "C" {
 
 struct os_mbuf;
 
+/**
+ * Allocates an mbuf suitable for an ATT command packet.  The resulting packet
+ * has sufficient leading space for:
+ *  - ACL data header
+ *  - L2CAP B-frame header
+ *  - Largest ATT command base (prepare write request / response).
+ *
+ * @return An empty mbuf on success, NULLl on error.
+ */
 struct os_mbuf *ble_hs_mbuf_att_pkt(void);
+
+/**
+ * Allocates an mbuf and fills it with the contents of the specified flat
+ * buffer.
+ *
+ * @param buf The flat buffer to copy from.
+ * @param len The length of the flat buffer.
+ *
+ * @return A newly-allocated mbuf on success, NULL on error.
+ */
 struct os_mbuf *ble_hs_mbuf_from_flat(const void *buf, uint16_t len);
+
+/**
+ * Copies the contents of an mbuf into the specified flat buffer.  If the flat
+ * buffer is too small to contain the mbuf's contents, it is filled to capacity
+ * and BLE_HS_EMSGSIZE is returned.
+ *
+ * @param om            The mbuf to copy from.
+ * @param flat          The destination flat buffer.
+ * @param max_len       The size of the flat buffer.
+ * @param out_copy_len  The number of bytes actually copied gets written here.
+ *
+ * @return               0 on success or BLE host core return code on error.
+ */
 int ble_hs_mbuf_to_flat(const struct os_mbuf *om, void *flat, uint16_t max_len,
                         uint16_t *out_copy_len);
 
@@ -36,4 +75,8 @@ int ble_hs_mbuf_to_flat(const struct os_mbuf *om, void *flat, uint16_t max_len,
 }
 #endif
 
+/**
+ * @}
+ */
+
 #endif
diff --git a/nimble/host/src/ble_hs_mbuf.c b/nimble/host/src/ble_hs_mbuf.c
index 0af1341f2..d938d3480 100644
--- a/nimble/host/src/ble_hs_mbuf.c
+++ b/nimble/host/src/ble_hs_mbuf.c
@@ -84,16 +84,6 @@ ble_hs_mbuf_l2cap_pkt(void)
     return ble_hs_mbuf_gen_pkt(BLE_HCI_DATA_HDR_SZ + BLE_L2CAP_HDR_SZ);
 }
 
-/**
- * Allocates an mbuf suitable for an ATT command packet.  The resulting packet
- * has sufficient leading space for:
- *     o ACL data header
- *     o L2CAP B-frame header
- *     o Largest ATT command base (prepare write request / response).
- *
- * @return                  An empty mbuf on success; null on memory
- *                              exhaustion.
- */
 struct os_mbuf *
 ble_hs_mbuf_att_pkt(void)
 {
@@ -105,16 +95,6 @@ ble_hs_mbuf_att_pkt(void)
                                 BLE_ATT_PREP_WRITE_CMD_BASE_SZ);
 }
 
-/**
- * Allocates a an mbuf and fills it with the contents of the specified flat
- * buffer.
- *
- * @param buf                   The flat buffer to copy from.
- * @param len                   The length of the flat buffer.
- *
- * @return                      A newly-allocated mbuf on success;
- *                              NULL on memory exhaustion.
- */
 struct os_mbuf *
 ble_hs_mbuf_from_flat(const void *buf, uint16_t len)
 {
@@ -135,23 +115,6 @@ ble_hs_mbuf_from_flat(const void *buf, uint16_t len)
     return om;
 }
 
-/**
- * Copies the contents of an mbuf into the specified flat buffer.  If the flat
- * buffer is too small to contain the mbuf's contents, it is filled to capacity
- * and BLE_HS_EMSGSIZE is returned.
- *
- * @param om                    The mbuf to copy from.
- * @param flat                  The destination flat buffer.
- * @param max_len               The size of the flat buffer.
- * @param out_copy_len          The number of bytes actually copied gets
- *                                  written here.
- *
- * @return                      0 on success;
- *                              BLE_HS_EMSGSIZE if the flat buffer is too small
- *                                  to contain the mbuf's contents;
- *                              A BLE host core return code on unexpected
- *                                  error.
- */
 int
 ble_hs_mbuf_to_flat(const struct os_mbuf *om, void *flat, uint16_t max_len,
                     uint16_t *out_copy_len)