From bcf2f2a2de5d032269fcad007e9274f2570889d3 Mon Sep 17 00:00:00 2001
From: Hauke Petersen <hauke.petersen@fu-berlin.de>
Date: Thu, 15 Aug 2019 17:41:40 +0200
Subject: [PATCH] sys/bluetil/addr: add doc in byte ordering

---
 sys/include/net/bluetil/addr.h | 28 +++++++++++++++++++---------
 1 file changed, 19 insertions(+), 9 deletions(-)

diff --git a/sys/include/net/bluetil/addr.h b/sys/include/net/bluetil/addr.h
index f538471493..205000b056 100644
--- a/sys/include/net/bluetil/addr.h
+++ b/sys/include/net/bluetil/addr.h
@@ -42,25 +42,31 @@ extern "C" {
 /**
  * @brief   Copy address and swap the byte order in the target buffer
  *
- * @param[in] src       buffer with source address, *must* hold BLE_ADDR_LEN
+ * @param[in] src       buffer with source address, *must* hold
+ *                      @ref BLE_ADDR_LEN bytes
+ * @param[out] dst      target buffer, *must* be able to hold @ref BLE_ADDR_LEN
  *                      bytes
- * @param[out] dst      target buffer, *must* be able to hold BLE_ADDR_LEN bytes
  */
 void bluetil_addr_swapped_cp(const uint8_t *src, uint8_t *dst);
 
 /**
  * @brief   Convert the given BLE address to a human readable string
  *
+ * @note    The address is expected to be in network byte order
+ *
  * @param[out] out      '\0' terminated address string, *must* be able to hold
- *                      BLUETIL_ADDR_STRLEN bytes
- * @param[in] addr      address buffer, *must* hold BLE_ADDR_LEN bytes
+ *                      @ref BLUETIL_ADDR_STRLEN bytes
+ * @param[in] addr      address buffer, *must* hold @ref BLE_ADDR_LEN bytes
  */
 void bluetil_addr_sprint(char *out, const uint8_t *addr);
 
 /**
  * @brief   Print the given BLE address to STDOUT
  *
- * @param[in] addr      address to print, is expected to hold BLE_ADDR_LEN bytes
+ * @note    The address is expected to be in network byte order
+ *
+ * @param[in] addr      address to print, is expected to hold @ref BLE_ADDR_LEN
+ *                      bytes
  */
 void bluetil_addr_print(const uint8_t *addr);
 
@@ -68,9 +74,9 @@ void bluetil_addr_print(const uint8_t *addr);
  * @brief   Parse a BLE address from the given string
  *
  * @param[out] addr     buffer to write the BLE address, *must* be able to hold
- *                      BLE_ADDR_LEN bytes
+ *                      @ref BLE_ADDR_LEN bytes
  * @param[in] addr_str  address string, must be at least of length
- *                      (BLUETIL_ADDR_STRLEN - 1)
+ *                      (@ref BLUETIL_ADDR_STRLEN - 1)
  *
  * @return  a pointer to the resulting address on success
  * @return  NULL on parsing error
@@ -81,9 +87,11 @@ uint8_t *bluetil_addr_from_str(uint8_t *addr, const char *addr_str);
  * @brief   Get a string representation of the given BLE addresses IID-based
  *          link local address
  *
+ * @note    The address is expected to be in network byte order
+ *
  * @param[out] out      '\0' terminated string, *must* be able to hold
- *                      BLUETIL_IPV6_IID_STRLEN bytes
- * @param[in]  addr     address to convert, , *must* hold BLE_ADDR_LEN bytes
+ *                      @ref BLUETIL_IPV6_IID_STRLEN bytes
+ * @param[in]  addr     address to convert, , *must* hold @ref BLE_ADDR_LEN bytes
  */
 void bluetil_addr_ipv6_l2ll_sprint(char *out, const uint8_t *addr);
 
@@ -91,6 +99,8 @@ void bluetil_addr_ipv6_l2ll_sprint(char *out, const uint8_t *addr);
  * @brief   Dump the given BLE addresses IPv6 IID-based link local address to
  *          STDIO
  *
+ * @note    The address is expected to be in network byte order
+ *
  * @param[in] addr      generate IID for this address
  */
 void bluetil_addr_ipv6_l2ll_print(const uint8_t *addr);