Documentation tag to indicate return vals that are not tested in functional test

[jphickey]

Is your feature request related to a problem? Please describe.
The pattern employed in OSAL (and CFE) is that functions should list all directly-generated return values from an implementation as @retval tags in doxygen markup. These are then cross referenced between the test logs to ensure that all documented return value are tested, and all tested return values are documented.

Coverage test should be able to exercise all values all the time, but functional test may not be able to exercise all of them. In particular the ones which depend on a failure of the underlying system call are not likely to be trigger-able from a functional test environment.

Describe the solution you'd like
These return codes should be marked in the doxygen as being "coverage test only". This will capture the fact that this has been checked/examined and the functional test is not expected to reproduce this value.

Describe alternatives you've considered
The retval statements could be entirely removed if they are not trigger-able in a functional test environment. (Many are pass-through values from the low level impl, but probably not all of them)

Additional context
This info is valuable not only for this test/documentation round but also any future audits of these test cases by projects and/or future releases.

Requester Info
Joseph Hickey, Vantage Systems, Inc.

[jphickey]

Proposal is to add three informational tags:

• @nonnull for pointers which are required to be non null, and will trigger the corresponding error code if null (e.g. OS_INVALID_POINTER, etc).
• @nonzero for sizes or other integer values which are required to be non-zero, and will trigger the corresponding error code if zero (e.g. OS_ERR_INVALID_SIZE, etc.)
• @covtest for return values which are only reliably generated in a coverage (stub) test environment (i.e. anything that depends on the failure of something outside the direct control of the test).