Fix #1008, resolve discrepancies between binsem API and unit tests

Ensures correlation between the unit-tests and documented return
values for the OSAL binsem API.

src/os/inc/osapi-binsem.h

@@ -57,8 +57,8 @@ typedef struct
  * sem_initial_value and name specified by sem_name. sem_id will be
  * returned to the caller
  *
- * @param[out]  sem_id will be set to the non-zero ID of the newly-created resource
- * @param[in]   sem_name the name of the new resource to create
+ * @param[out]  sem_id will be set to the non-zero ID of the newly-created resource @nonnull
+ * @param[in]   sem_name the name of the new resource to create @nonnull
  * @param[in]   sem_initial_value the initial value of the binary semaphore
  * @param[in]   options Reserved for future use, should be passed as 0.
  *
@@ -68,7 +68,7 @@ typedef struct
  * @retval #OS_ERR_NAME_TOO_LONG name length including null terminator greater than #OS_MAX_API_NAME
  * @retval #OS_ERR_NO_FREE_IDS if all of the semaphore ids are taken
  * @retval #OS_ERR_NAME_TAKEN if this is already the name of a binary semaphore
- * @retval #OS_SEM_FAILURE if the OS call failed
+ * @retval #OS_SEM_FAILURE if the OS call failed @covtest
  */
 int32 OS_BinSemCreate(osal_id_t *sem_id, const char *sem_name, uint32 sem_initial_value, uint32 options);
 
@@ -84,7 +84,7 @@ int32 OS_BinSemCreate(osal_id_t *sem_id, const char *sem_name, uint32 sem_initia
  * @return Execution status, see @ref OSReturnCodes
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS
  * @retval #OS_ERR_INVALID_ID if the id passed in is not a binary semaphore
- * @retval #OS_SEM_FAILURE if an unspecified failure occurs
+ * @retval #OS_SEM_FAILURE if an unspecified failure occurs @covtest
  */
 int32 OS_BinSemFlush(osal_id_t sem_id);
 
@@ -102,9 +102,8 @@ int32 OS_BinSemFlush(osal_id_t sem_id);
  *
  * @return Execution status, see @ref OSReturnCodes
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS
- * @retval #OS_SEM_FAILURE the semaphore was not previously initialized or is not
- * in the array of semaphores defined by the system
  * @retval #OS_ERR_INVALID_ID if the id passed in is not a binary semaphore
+ * @retval #OS_SEM_FAILURE if an unspecified failure occurs @covtest
  */
 int32 OS_BinSemGive(osal_id_t sem_id);
 
@@ -123,7 +122,7 @@ int32 OS_BinSemGive(osal_id_t sem_id);
  * @return Execution status, see @ref OSReturnCodes
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS
  * @retval #OS_ERR_INVALID_ID the Id passed in is not a valid binary semaphore
- * @retval #OS_SEM_FAILURE if the OS call failed
+ * @retval #OS_SEM_FAILURE if an unspecified failure occurs @covtest
  */
 int32 OS_BinSemTake(osal_id_t sem_id);
 
@@ -142,9 +141,8 @@ int32 OS_BinSemTake(osal_id_t sem_id);
  * @return Execution status, see @ref OSReturnCodes
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS
  * @retval #OS_SEM_TIMEOUT if semaphore was not relinquished in time
- * @retval #OS_SEM_FAILURE the semaphore was not previously initialized or is not
- * in the array of semaphores defined by the system
  * @retval #OS_ERR_INVALID_ID if the ID passed in is not a valid semaphore ID
+ * @retval #OS_SEM_FAILURE if an unspecified failure occurs @covtest
  */
 int32 OS_BinSemTimedWait(osal_id_t sem_id, uint32 msecs);
 
@@ -160,7 +158,7 @@ int32 OS_BinSemTimedWait(osal_id_t sem_id, uint32 msecs);
  * @return Execution status, see @ref OSReturnCodes
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS
  * @retval #OS_ERR_INVALID_ID if the id passed in is not a valid binary semaphore
- * @retval #OS_SEM_FAILURE the OS call failed
+ * @retval #OS_SEM_FAILURE if an unspecified failure occurs @covtest
  */
 int32 OS_BinSemDelete(osal_id_t sem_id);
 
@@ -172,7 +170,7 @@ int32 OS_BinSemDelete(osal_id_t sem_id);
  * The id is returned through sem_id
  *
  * @param[out] sem_id will be set to the ID of the existing resource
- * @param[in]   sem_name the name of the existing resource to find
+ * @param[in]  sem_name the name of the existing resource to find @nonnull
  *
  * @return Execution status, see @ref OSReturnCodes
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS
@@ -191,7 +189,7 @@ int32 OS_BinSemGetIdByName(osal_id_t *sem_id, const char *sem_name);
  * semaphore.
  *
  * @param[in] sem_id The object ID to operate on
- * @param[out]  bin_prop The property object buffer to fill
+ * @param[out]  bin_prop The property object buffer to fill @nonnull
  *
  * @return Execution status, see @ref OSReturnCodes
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS