From d76aa6cb48104d483d17d07d28d4c50b331efe32 Mon Sep 17 00:00:00 2001
From: Stefano D'Angelo <stefano.dangelo@orastron.com>
Date: Sat, 5 Aug 2023 08:58:45 +0200
Subject: [PATCH] added missing doc

---
 include/bw_common.h     | 39 +++++++++++++++++++++++++++++----------
 include/bw_note_queue.h |  7 ++++++-
 include/bw_one_pole.h   | 14 ++++++++++++--
 3 files changed, 47 insertions(+), 13 deletions(-)

diff --git a/include/bw_common.h b/include/bw_common.h
index 6313a7b..b78bdcc 100644
--- a/include/bw_common.h
+++ b/include/bw_common.h
@@ -112,10 +112,25 @@
 #endif
 /*! ...
  *
- *    #### BW_ASSERT
- *    WRITEME
+ *    #### BW_ASSERT and BW_ASSERT_DEEP
+ *    If `NDEBUG` is defined then "calls" to both `BW_ASSERT` and
+ *    `BW_ASSERT_DEEP` will be stripped away by the preprocessor.
+ *
+ *    Whether `NDEBUG` is defined or not, "calls" to `BW_ASSERT_DEEP` will still
+ *    be stripped anyway if `BW_DEBUG_DEEP` is not defined.
+ *
+ *    In all other cases, `BW_ASSERT` and `BW_ASSERT_DEEP` can either be
+ *    provided by you, otherwise `BW_ASSERT` is defined as `assert` (and
+ *    `assert.h` is `#include`d) and `BW_ASSERT_DEEP` is defined as `BW_ASSERT`.
+ *
+ *    `BW_ASSERT` is meant to perform rapid/basic validity checks (e.g., input
+ *    pointer is not `NULL`, input `float` number is finite), while
+ *    `BW_ASSERT_DEEP` should be used for deeper checks (e.g., validate data
+ *    structures and internal states).
  *  >>> */
 #ifdef NDEBUG
+# undef BW_ASSERT
+# undef BW_ASSERT_DEEP
 # define BW_ASSERT(ignore)	((void)0)
 # define BW_ASSERT_DEEP(ignore)	((void)0)
 #else
@@ -140,44 +155,48 @@
  *  ```>>> */
 static inline char bw_is_inf(float x);
 /*! <<<```
- *    WRITEME
+ *    Returns non-`0` if `x` is positive or negative infinity, `0` otherwise.
  *
  *    #### bw_is_nan()
  *  ```>>> */
 static inline char bw_is_nan(float x);
 /*! <<<```
- *    WRITEME
+ *    Returns non-`0` if `x` is NaN, `0` otherwise.
  *
  *    #### bw_is_finite()
  *  ```>>> */
 static inline char bw_is_finite(float x);
 /*! <<<```
- *    WRITEME
+ *    Returns non-`0` if `x` is finite (neither NaN nor positive or negative
+ *    infinity), `0` otherwise.
  *
  *    #### bw_has_inf()
  *  ```>>> */
 static inline char bw_has_inf(const float *x, BW_SIZE_T n_elems);
 /*! <<<```
- *    WRITEME
+ *    Scans the fist `n_elems` in buffer `x` and returns non-`0` if it contains
+ *    at least one positive or negative inifinity value, `0` otherwise.
  *
  *    #### bw_has_nan()
  *  ```>>> */
 static inline char bw_has_nan(const float *x, BW_SIZE_T n_elems);
 /*! <<<```
- *    WRITEME
+ *    Scans the fist `n_elems` in buffer `x` and returns non-`0` if it contains
+ *    at least one NaN value, `0` otherwise.
  *
  *    #### bw_has_only_finite()
  *  ```>>> */
 static inline char bw_has_only_finite(const float *x, BW_SIZE_T n_elems);
 /*! <<<```
- *    WRITEME
+ *    Scans the fist `n_elems` in buffer `x` and returns non-`0` if it only
+ *    finds finite values (neither NaN nor positive or negative infinity), `0`
+ *    otherwise.
  *
  *    #### bw_hash_sdbm()
  *  ```>>> */
 static inline uint32_t bw_hash_sdbm(const char *string);
 /*! <<<```
- *    WRITEME
- *
+ *    Returns the sdbm hash of the given `string`.
  *  }}} */
 
 /*** Implementation ***/
diff --git a/include/bw_note_queue.h b/include/bw_note_queue.h
index 092165b..219a5f1 100644
--- a/include/bw_note_queue.h
+++ b/include/bw_note_queue.h
@@ -127,7 +127,12 @@ static inline void bw_note_queue_add(bw_note_queue *BW_RESTRICT queue, unsigned
  *  ```>>> */
 static inline char bw_note_queue_is_valid(const bw_note_queue *BW_RESTRICT queue);
 /*! <<<```
- *    WRITEME
+ *    Tries to determine whether `queue` is valid and returns non-`0` if it
+ *    seems to be the case and `0` if it is certainly not. False positives are
+ *    possible, false negatives are not.
+ *
+ *    `queue` must at least point to a readable memory block of size greater
+ *    than or equal to that of `bw_note_queue`.
  *  }}} */
 
 /*** Implementation ***/
diff --git a/include/bw_one_pole.h b/include/bw_one_pole.h
index bd3361e..a99dcce 100644
--- a/include/bw_one_pole.h
+++ b/include/bw_one_pole.h
@@ -299,13 +299,23 @@ static inline float bw_one_pole_get_y_z1(const bw_one_pole_state *BW_RESTRICT st
  *  ```>>> */
 static inline char bw_one_pole_coeffs_is_valid(const bw_one_pole_coeffs *BW_RESTRICT coeffs);
 /*! <<<```
- *    WRITEME
+ *    Tries to determine whether `coeffs` is valid and returns non-`0` if it
+ *    seems to be the case and `0` if it is certainly not. False positives are
+ *    possible, false negatives are not.
+ *
+ *    `coeffs` must at least point to a readable memory block of size greater
+ *    than or equal to that of `bw_one_pole_coeffs`.
  *
  *    #### bw_one_pole_state_is_valid()
  *  ```>>> */
 static inline char bw_one_pole_state_is_valid(const bw_one_pole_state *BW_RESTRICT state);
 /*! <<<```
- *    WRITEME
+ *    Tries to determine whether `state` is valid and returns non-`0` if it
+ *    seems to be the case and `0` if it is certainly not. False positives are
+ *    possible, false negatives are not.
+ *
+ *    `state` must at least point to a readable memory block of size greater
+ *    than or equal to that of `bw_one_pole_state`.
  *  }}} */
 
 /*** Implementation ***/