Fix #1010, resolve discrepancies between common API and unit tests

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

src/os/inc/osapi-common.h

@@ -136,7 +136,7 @@ void OS_Application_Run(void);
  *         means the OSAL can not be initialized.  Typical platform specific response
  *         is to abort since additional OSAL calls will have undefined behavior.
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS
- * @retval #OS_ERROR   @copybrief OS_ERROR
+ * @retval #OS_ERROR   @copybrief OS_ERROR @covtest
  */
 int32 OS_API_Init(void);
 
@@ -228,10 +228,9 @@ void OS_ApplicationExit(int32 Status);
  * application-defined handlers for these events should not block or attempt
  * to access other OSAL resources.
  *
- * @param[in] handler The application-provided event handler
+ * @param[in] handler The application-provided event handler @nonnull
  * @return Execution status, see @ref OSReturnCodes.
  * @retval #OS_SUCCESS @copybrief OS_SUCCESS
- * @retval #OS_ERROR   @copybrief OS_ERROR
  * @retval #OS_INVALID_POINTER if handler is NULL
  */
 int32 OS_RegisterEventHandler(OS_EventHandler_t handler);

src/unit-tests/oscore-test/ut_oscore_misc_test.c

@@ -120,6 +120,26 @@ void UT_os_apiinit_test()
     UT_TEARDOWN(OS_MutSemDelete(semIds[2]));
 }
 
+/*--------------------------------------------------------------------------------*
+** Syntax: int32 OS_RegisterEventHandler(OS_EventHandler_t handler)
+** See header file for list of return values
+**--------------------------------------------------------------------------------*/
+int32 UT_os_eventhandler(OS_Event_t event, osal_id_t object_id, void *data)
+{
+    return OS_SUCCESS;
+}
+
+void UT_os_registereventhandler_test()
+{
+    /*-----------------------------------------------------*/
+    /* #1 Null-pointer-arg */
+    UT_RETVAL(OS_RegisterEventHandler(NULL), OS_INVALID_POINTER);
+
+    /*-----------------------------------------------------*/
+    /* #2 Nominal */
+    UT_NOMINAL(OS_RegisterEventHandler(UT_os_eventhandler));
+}
+
 /*--------------------------------------------------------------------------------*
 ** Syntax: void OS_printf(const char String, ...)
 ** Purpose: Provides a printing utility similar to printf

src/unit-tests/oscore-test/ut_oscore_misc_test.h

@@ -55,6 +55,7 @@
 **--------------------------------------------------------------------------------*/
 
 void UT_os_apiinit_test(void);
+void UT_os_registereventhandler_test(void);
 
 void UT_os_printf_test(void);
 void UT_os_printfenable_test(void);

src/unit-tests/oscore-test/ut_oscore_test.c

@@ -192,6 +192,7 @@ void UtTest_Setup(void)
     UtTest_AddTeardown(OS_API_Teardown, "Cleanup");
 
     UtTest_Add(UT_os_apiinit_test, NULL, NULL, "OS_API_Init");
+    UtTest_Add(UT_os_registereventhandler_test, NULL, NULL, "OS_RegisterEventHandler");
 
     UtTest_Add(UT_os_printf_test, NULL, NULL, "OS_printf");
     UtTest_Add(UT_os_printfenable_test, NULL, NULL, "OS_printf_enable");