include: zephyr: sys: correct sys_test_bit() and friends description

Correct the documentation of sys_test_bit() and its derivative helper
functions (listed below) since these return a bit mask value instead of
an essentially boolean value as previosuly described.

In tree implementation do conform with that: the result of these
functions are always implicitly tested against being 0 or a non-zero
value.

Helper functions which documentation is modified are sys_test_bit(),
sys_test_and_set_bit(), sys_test_and_clear_bit(), sys_bitfield_test_bit(),
sys_bitfield_test_and_set_bit() and sys_bitfield_test_and_clear_bit().

Signed-off-by: Etienne Carriere <[email protected]>

Author: etienne-lms

include/zephyr/sys/sys_io.h

@@ -285,7 +285,8 @@ typedef uintptr_t mem_addr_t;
  * @param addr the memory address from where to look for the bit
  * @param bit the designated bit to test (from 0 to 31)
  *
- * @return 1 if it is set, 0 otherwise
+ * @return the bitwise AND result of @p addr content and (1 << @p bit).
+ * Result is 0 only if the bit is cleared otherwise result is a non-0 value.
  */
 
 /**
@@ -298,7 +299,8 @@ typedef uintptr_t mem_addr_t;
  * @param addr the memory address from where to look for the bit
  * @param bit the designated bit to test and set (from 0 to 31)
  *
- * @return 1 if it was set, 0 otherwise
+ * @return the bitwise AND result of @p addr content and (1 << @p bit) before target bit
+ * is set. Result is 0 only if the bit was cleared otherwise result is a non-0 value.
  */
 
 /**
@@ -311,7 +313,8 @@ typedef uintptr_t mem_addr_t;
  * @param addr the memory address from where to look for the bit
  * @param bit the designated bit to test and clear (from 0 to 31)
  *
- * @return 0 if it was clear, 1 otherwise
+ * @return the bitwise AND result of @p addr content and (1 << @p bit) before target bit
+ * is cleared. Result is 0 only if the bit was cleared otherwise result is a non-0 value.
  */
 
 /**
@@ -344,7 +347,8 @@ typedef uintptr_t mem_addr_t;
  * @param addr the memory address from where to look for the bit
  * @param bit the designated bit to test (arbitrary
  *
- * @return 1 if it is set, 0 otherwise
+ * @return the bitwise AND result of @p addr content and (1 << @p bit). Result is 0
+ * only if the bit is cleared otherwise result is a non-0 value.
  */
 
 /**
@@ -357,7 +361,8 @@ typedef uintptr_t mem_addr_t;
  * @param addr the memory address from where to look for the bit
  * @param bit the designated bit to test and set (arbitrary)
  *
- * @return 1 if it was set, 0 otherwise
+ * @return the bitwise AND result of @p addr content and (1 << @p bit) before target bit
+ * is set. Result is 0 only if the bit was cleared otherwise result is a non-0 value.
  */
 
 /**
@@ -370,7 +375,8 @@ typedef uintptr_t mem_addr_t;
  * @param addr the memory address from where to look for the bit
  * @param bit the designated bit to test and clear (arbitrary)
  *
- * @return 0 if it was clear, 1 otherwise
+ * @return the bitwise AND result of @p addr content and (1 << @p bit) before target bit
+ * is cleared. Result is 0 only if the bit was cleared otherwise result is a non-0 value.
  */