From 052ad37bed1b2b74a56bd8d38ab23903d68dcad5 Mon Sep 17 00:00:00 2001 From: Joseph Hickey Date: Tue, 10 Aug 2021 14:53:21 -0400 Subject: [PATCH] Partial #1724, update in/out status and nonnull/nonzero tags First pass at API doxygen scrub, this updates the in/out markings on parameters where they were not correct, and adds nonnull and nonzero tags where appropriate. --- modules/core_api/fsw/inc/cfe_es.h | 153 +++++++++++++--------- modules/core_api/fsw/inc/cfe_evs.h | 11 +- modules/core_api/fsw/inc/cfe_fs.h | 56 +++++--- modules/core_api/fsw/inc/cfe_msg.h | 100 +++++++------- modules/core_api/fsw/inc/cfe_resourceid.h | 6 +- modules/core_api/fsw/inc/cfe_sb.h | 42 +++--- modules/core_api/fsw/inc/cfe_tbl.h | 44 +++++-- modules/core_api/fsw/inc/cfe_time.h | 8 +- 8 files changed, 252 insertions(+), 168 deletions(-) diff --git a/modules/core_api/fsw/inc/cfe_es.h b/modules/core_api/fsw/inc/cfe_es.h index 2fcb96603..85a4ca48f 100644 --- a/modules/core_api/fsw/inc/cfe_es.h +++ b/modules/core_api/fsw/inc/cfe_es.h @@ -88,7 +88,7 @@ * for future use. * * @param[in] AppID Application ID to convert - * @param[out] Idx Buffer where the calculated index will be stored + * @param[out] Idx Buffer where the calculated index will be stored @nonnull * * @return Execution status, see @ref CFEReturnCodes * @retval #CFE_SUCCESS @copybrief CFE_SUCCESS @@ -113,7 +113,7 @@ CFE_Status_t CFE_ES_AppID_ToIndex(CFE_ES_AppId_t AppID, uint32 *Idx); * for future use. * * @param[in] LibId Library ID to convert - * @param[out] Idx Buffer where the calculated index will be stored + * @param[out] Idx Buffer where the calculated index will be stored @nonnull * * @return Execution status, see @ref CFEReturnCodes * @retval #CFE_SUCCESS @copybrief CFE_SUCCESS @@ -138,11 +138,12 @@ int32 CFE_ES_LibID_ToIndex(CFE_ES_LibId_t LibId, uint32 *Idx); * for future use. * * @param[in] TaskID Task ID to convert - * @param[out] Idx Buffer where the calculated index will be stored + * @param[out] Idx Buffer where the calculated index will be stored @nonnull * * @return Execution status, see @ref CFEReturnCodes * @retval #CFE_SUCCESS @copybrief CFE_SUCCESS * @retval #CFE_ES_ERR_RESOURCEID_NOT_VALID @copybrief CFE_ES_ERR_RESOURCEID_NOT_VALID +** @retval #CFE_ES_BAD_ARGUMENT @copybrief CFE_ES_BAD_ARGUMENT */ CFE_Status_t CFE_ES_TaskID_ToIndex(CFE_ES_TaskId_t TaskID, uint32 *Idx); @@ -262,6 +263,9 @@ CFE_Status_t CFE_ES_ResetCFE(uint32 ResetType); ** \param[in] AppID Identifies the application to be reset. ** ** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_ES_ERR_RESOURCEID_NOT_VALID \copybrief CFE_ES_ERR_RESOURCEID_NOT_VALID +** \retval #CFE_ES_FILE_IO_ERR \copybrief CFE_ES_FILE_IO_ERR +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS ** ** \sa #CFE_ES_ReloadApp, #CFE_ES_DeleteApp ** @@ -292,9 +296,12 @@ CFE_Status_t CFE_ES_RestartApp(CFE_ES_AppId_t AppID); ** ** \param[in] AppID Identifies the application to be reset. ** -** \param[in] AppFileName Identifies the new file to start. +** \param[in] AppFileName Identifies the new file to start @nonnull ** ** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_ES_ERR_RESOURCEID_NOT_VALID \copybrief CFE_ES_ERR_RESOURCEID_NOT_VALID +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_FILE_IO_ERR \copybrief CFE_ES_FILE_IO_ERR ** ** \sa #CFE_ES_RestartApp, #CFE_ES_DeleteApp, #CFE_ES_START_APP_CC ** @@ -314,6 +321,8 @@ CFE_Status_t CFE_ES_ReloadApp(CFE_ES_AppId_t AppID, const char *AppFileName); ** \param[in] AppID Identifies the application to be reset. ** ** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_ES_ERR_RESOURCEID_NOT_VALID \copybrief CFE_ES_ERR_RESOURCEID_NOT_VALID +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS ** ** \sa #CFE_ES_RestartApp, #CFE_ES_ReloadApp ** @@ -499,7 +508,7 @@ int32 CFE_ES_GetResetType(uint32 *ResetSubtypePtr); ** \par Assumptions, External Events, and Notes: ** NOTE: \b All tasks associated with the Application would return the same Application ID. ** -** \param[out] AppIdPtr Pointer to variable that is to receive the Application's ID. +** \param[out] AppIdPtr Pointer to variable that is to receive the Application's ID @nonnull. ** *AppIdPtr will be set to the application ID of the calling Application. ** ** \return Execution status, see \ref CFEReturnCodes @@ -524,7 +533,7 @@ CFE_Status_t CFE_ES_GetAppID(CFE_ES_AppId_t *AppIdPtr); ** CFE_ES_TaskGetInfo() should use this API rather than getting the ID ** from OSAL directly via OS_TaskGetId(). ** -** \param[out] TaskIdPtr Pointer to variable that is to receive the ID. +** \param[out] TaskIdPtr Pointer to variable that is to receive the ID @nonnull. ** Will be set to the ID of the calling task. ** ** \return Execution status, see \ref CFEReturnCodes @@ -546,8 +555,8 @@ CFE_Status_t CFE_ES_GetTaskID(CFE_ES_TaskId_t *TaskIdPtr); ** \par Assumptions, External Events, and Notes: ** None ** -** \param[out] AppIdPtr Pointer to variable that is to receive the Application's ID. -** \param[in] AppName Pointer to null terminated character string containing an Application name. +** \param[out] AppIdPtr Pointer to variable that is to receive the Application's ID @nonnull. +** \param[in] AppName Pointer to null terminated character string containing an Application name @nonnull. ** ** \return Execution status, see \ref CFEReturnCodes ** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -570,8 +579,8 @@ CFE_Status_t CFE_ES_GetAppIDByName(CFE_ES_AppId_t *AppIdPtr, const char *AppName ** \par Assumptions, External Events, and Notes: ** None ** -** \param[out] LibIdPtr Pointer to variable that is to receive the Library's ID. -** \param[in] LibName Pointer to null terminated character string containing a Library name. +** \param[out] LibIdPtr Pointer to variable that is to receive the Library's ID @nonnull. +** \param[in] LibName Pointer to null terminated character string containing a Library name @nonnull. ** ** \return Execution status, see \ref CFEReturnCodes ** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -594,7 +603,7 @@ CFE_Status_t CFE_ES_GetLibIDByName(CFE_ES_LibId_t *LibIdPtr, const char *LibName ** \par Assumptions, External Events, and Notes: ** In the case of a failure (#CFE_ES_ERR_RESOURCEID_NOT_VALID), an empty string is returned. ** -** \param[out] AppName Pointer to a character array of at least \c BufferLength in size that will +** \param[out] AppName Pointer to a character array @nonnull of at least \c BufferLength in size that will ** be filled with the appropriate Application name. ** ** \param[in] AppId Application ID of Application whose name is being requested. @@ -624,7 +633,7 @@ CFE_Status_t CFE_ES_GetAppName(char *AppName, CFE_ES_AppId_t AppId, size_t Buffe ** \par Assumptions, External Events, and Notes: ** In the case of a failure (#CFE_ES_ERR_RESOURCEID_NOT_VALID), an empty string is returned. ** -** \param[out] LibName Pointer to a character array of at least \c BufferLength in size that will +** \param[out] LibName Pointer to a character array @nonnull of at least \c BufferLength in size that will ** be filled with the Library name. ** ** \param[in] LibId Library ID of Library whose name is being requested. @@ -655,7 +664,7 @@ CFE_Status_t CFE_ES_GetLibName(char *LibName, CFE_ES_LibId_t LibId, size_t Buffe ** \par Assumptions, External Events, and Notes: ** None ** -** \param[out] AppInfo Pointer to a structure that will be filled with +** \param[out] AppInfo Pointer to a structure @nonnull that will be filled with ** resource name and memory addresses information. ** \param[in] AppId ID of application to obtain information about ** @@ -681,7 +690,7 @@ CFE_Status_t CFE_ES_GetAppInfo(CFE_ES_AppInfo_t *AppInfo, CFE_ES_AppId_t AppId); ** \par Assumptions, External Events, and Notes: ** None ** -** \param[out] TaskInfo Pointer to a \c CFE_ES_TaskInfo_t structure that holds the specific +** \param[out] TaskInfo Pointer to a \c CFE_ES_TaskInfo_t structure @nonnull that holds the specific ** task information. *TaskInfo is the filled out \c CFE_ES_TaskInfo_t structure containing ** the Task Name, Parent App Name, Parent App ID among other fields. ** @@ -715,7 +724,7 @@ CFE_Status_t CFE_ES_GetTaskInfo(CFE_ES_TaskInfo_t *TaskInfo, CFE_ES_TaskId_t Tas ** \par Assumptions, External Events, and Notes: ** None ** -** \param[out] LibInfo Pointer to a structure that will be filled with +** \param[out] LibInfo Pointer to a structure @nonnull that will be filled with ** resource name and memory addresses information. ** \param[in] LibId ID of application to obtain information about ** @@ -747,7 +756,7 @@ int32 CFE_ES_GetLibInfo(CFE_ES_AppInfo_t *LibInfo, CFE_ES_LibId_t LibId); ** \par Assumptions, External Events, and Notes: ** None ** -** \param[out] ModuleInfo Pointer to a structure that will be filled with +** \param[out] ModuleInfo Pointer to a structure @nonnull that will be filled with ** resource name and memory addresses information. ** \param[in] ResourceId ID of application or library to obtain information about ** @@ -777,22 +786,21 @@ int32 CFE_ES_GetModuleInfo(CFE_ES_AppInfo_t *ModuleInfo, CFE_ResourceId_t Resour ** \par Assumptions, External Events, and Notes: ** None ** -** \param[in, out] TaskIdPtr A pointer to a variable that will be filled in with the new task's ID. *TaskIdPtr is +** \param[out] TaskIdPtr A pointer to a variable that will be filled in with the new task's ID @nonnull. +**TaskIdPtr is ** the Task ID of the newly created child task. ** -** \param[in] TaskName A pointer to a string containing the desired name of the new task. +** \param[in] TaskName A pointer to a string containing the desired name of the new task @nonnull. ** This can be up to #OS_MAX_API_NAME characters, including the trailing null. ** -** \param[in] FunctionPtr A pointer to the function that will be spawned as a new task. This function -** must have the following signature: uint32 function(void). Input parameters -** for the new task are not supported. +** \param[in] FunctionPtr A pointer to the function that will be spawned as a new task @nonnull. ** ** \param[in] StackPtr A pointer to the location where the child task's stack pointer should start. ** NOTE: Not all underlying operating systems support this parameter. ** The CFE_ES_TASK_STACK_ALLOCATE constant may be passed to indicate that the ** stack should be dynamically allocated. ** -** \param[in] StackSize The number of bytes to allocate for the new task's stack. +** \param[in] StackSize The number of bytes to allocate for the new task's stack @nonzero. ** ** \param[in] Priority The priority for the new task. Lower numbers are higher priority, with 0 being ** the highest priority. @@ -800,9 +808,10 @@ int32 CFE_ES_GetModuleInfo(CFE_ES_AppInfo_t *ModuleInfo, CFE_ResourceId_t Resour ** \param[in] Flags Reserved for future expansion. ** ** \return Execution status, see \ref CFEReturnCodes -** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS -** \retval #CFE_ES_ERR_CHILD_TASK_CREATE \copybrief CFE_ES_ERR_CHILD_TASK_CREATE -** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_ERR_CHILD_TASK_CREATE \copybrief CFE_ES_ERR_CHILD_TASK_CREATE +** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT +** \retval #CFE_ES_ERR_RESOURCEID_NOT_VALID \copybrief CFE_ES_ERR_RESOURCEID_NOT_VALID ** ** \sa #CFE_ES_DeleteChildTask, #CFE_ES_ExitChildTask ** @@ -822,8 +831,8 @@ CFE_Status_t CFE_ES_CreateChildTask(CFE_ES_TaskId_t *TaskIdPtr, const char *Task ** \par Assumptions, External Events, and Notes: ** None ** -** \param[out] TaskIdPtr Pointer to variable that is to receive the Task's ID. -** \param[in] TaskName Pointer to null terminated character string containing an Task name. +** \param[out] TaskIdPtr Pointer to variable that is to receive the Task's ID @nonnull. +** \param[in] TaskName Pointer to null terminated character string containing an Task name @nonnull. ** ** \return Execution status, see \ref CFEReturnCodes ** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -846,7 +855,7 @@ CFE_Status_t CFE_ES_GetTaskIDByName(CFE_ES_TaskId_t *TaskIdPtr, const char *Task ** \par Assumptions, External Events, and Notes: ** In the case of a failure (#CFE_ES_ERR_RESOURCEID_NOT_VALID), an empty string is returned. ** -** \param[out] TaskName Pointer to a character array of at least \c BufferLength in size that will +** \param[out] TaskName Pointer to a character array @nonnull of at least \c BufferLength in size that will ** be filled with the Task name. ** ** \param[in] TaskId Task ID of Task whose name is being requested. @@ -880,8 +889,11 @@ CFE_Status_t CFE_ES_GetTaskName(char *TaskName, CFE_ES_TaskId_t TaskId, size_t B *#CFE_ES_CreateChildTask API. ** ** \return Execution status, see \ref CFEReturnCodes -** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS -** \retval #CFE_ES_NOT_IMPLEMENTED \copybrief CFE_ES_NOT_IMPLEMENTED +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_NOT_IMPLEMENTED \copybrief CFE_ES_NOT_IMPLEMENTED +** \retval #CFE_ES_ERR_CHILD_TASK_DELETE \copybrief CFE_ES_ERR_CHILD_TASK_DELETE +** \retval #CFE_ES_ERR_CHILD_TASK_DELETE_MAIN_TASK \copybrief CFE_ES_ERR_CHILD_TASK_DELETE_MAIN_TASK +** \retval #CFE_ES_ERR_RESOURCEID_NOT_VALID \copybrief CFE_ES_ERR_RESOURCEID_NOT_VALID ** ** \sa #CFE_ES_CreateChildTask, #CFE_ES_ExitChildTask ** @@ -945,7 +957,7 @@ void CFE_ES_BackgroundWakeup(void); ** \par Assumptions, External Events, and Notes: ** None ** -** \param[in] SpecStringPtr The format string for the log message. +** \param[in] SpecStringPtr The format string for the log message @nonnull. ** This is similar to the format string for a printf() call. ** ** \return Execution status, see \ref CFEReturnCodes @@ -1031,13 +1043,13 @@ void CFE_ES_ProcessAsyncEvent(void); ** This is indicated by a #CFE_SUCCESS return code, and in this case the calling application should ** ensure that it also calls CFE_ES_CopyToCDS() to fill the block with valid data. ** -** \param[in, out] CDSHandlePtr Pointer Application's variable that will contain the CDS Memory Block Handle. +** \param[out] CDSHandlePtr Pointer Application's variable that will contain the CDS Memory Block Handle @nonnull. ** HandlePtr is the handle of the CDS block that can be used in ** #CFE_ES_CopyToCDS and #CFE_ES_RestoreFromCDS. ** -** \param[in] BlockSize The number of bytes needed in the CDS. +** \param[in] BlockSize The number of bytes needed in the CDS @nonzero. ** -** \param[in] Name A pointer to a character string containing an application +** \param[in] Name A pointer to a character string @nonnull containing an application ** unique name of #CFE_MISSION_ES_CDS_MAX_NAME_LENGTH characters or less. ** ** \return Execution status, see \ref CFEReturnCodes @@ -1047,6 +1059,7 @@ void CFE_ES_ProcessAsyncEvent(void); ** \retval #CFE_ES_CDS_INVALID_SIZE \copybrief CFE_ES_CDS_INVALID_SIZE ** \retval #CFE_ES_CDS_INVALID_NAME \copybrief CFE_ES_CDS_INVALID_NAME ** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT +** \retval #CFE_ES_CDS_INVALID \copybrief CFE_ES_CDS_INVALID ** ** \sa #CFE_ES_CopyToCDS, #CFE_ES_RestoreFromCDS ** @@ -1064,13 +1077,14 @@ CFE_Status_t CFE_ES_RegisterCDS(CFE_ES_CDSHandle_t *CDSHandlePtr, size_t BlockSi ** \par Assumptions, External Events, and Notes: ** None ** -** \param[out] BlockIdPtr Pointer to variable that is to receive the CDS Block ID. -** \param[in] BlockName Pointer to null terminated character string containing a CDS Block name. +** \param[out] BlockIdPtr Pointer to variable that is to receive the CDS Block ID @nonnull. +** \param[in] BlockName Pointer to null terminated character string containing a CDS Block name @nonnull. ** ** \return Execution status, see \ref CFEReturnCodes ** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS ** \retval #CFE_ES_ERR_NAME_NOT_FOUND \copybrief CFE_ES_ERR_NAME_NOT_FOUND ** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT +** \retval #CFE_ES_NOT_IMPLEMENTED The processor does not support a Critical Data Store. ** ** \sa #CFE_ES_GetCDSBlockName ** @@ -1088,7 +1102,7 @@ CFE_Status_t CFE_ES_GetCDSBlockIDByName(CFE_ES_CDSHandle_t *BlockIdPtr, const ch ** \par Assumptions, External Events, and Notes: ** In the case of a failure (#CFE_ES_ERR_RESOURCEID_NOT_VALID), an empty string is returned. ** -** \param[out] BlockName Pointer to a character array of at least \c BufferLength in size that will +** \param[out] BlockName Pointer to a character array @nonnull of at least \c BufferLength in size that will ** be filled with the CDS Block name. ** ** \param[in] BlockId Block ID/Handle of CDS registry entry whose name is being requested. @@ -1101,6 +1115,7 @@ CFE_Status_t CFE_ES_GetCDSBlockIDByName(CFE_ES_CDSHandle_t *BlockIdPtr, const ch ** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS ** \retval #CFE_ES_ERR_RESOURCEID_NOT_VALID \copybrief CFE_ES_ERR_RESOURCEID_NOT_VALID ** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT +** \retval #CFE_ES_NOT_IMPLEMENTED The processor does not support a Critical Data Store. ** ** \sa #CFE_ES_GetCDSBlockIDByName ** @@ -1121,7 +1136,7 @@ CFE_Status_t CFE_ES_GetCDSBlockName(char *BlockName, CFE_ES_CDSHandle_t BlockId, ** ** \param[in] Handle The handle of the CDS block that was previously obtained from #CFE_ES_RegisterCDS. ** -** \param[in] DataToCopy A Pointer to the block of memory to be copied into the CDS. +** \param[in] DataToCopy A Pointer to the block of memory to be copied into the CDS @nonnull. ** ** \return Execution status, see \ref CFEReturnCodes ** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -1150,7 +1165,8 @@ CFE_Status_t CFE_ES_CopyToCDS(CFE_ES_CDSHandle_t Handle, void *DataToCopy); ** ** \param[in] Handle The handle of the CDS block that was previously obtained from #CFE_ES_RegisterCDS. ** -** \param[in, out] RestoreToMemory A Pointer to the block of memory that is to be restored with the contents of +** \param[out] RestoreToMemory A Pointer to the block of memory @nonnull that is to be restored with the contents +*of ** the CDS. *RestoreToMemory is the contents of the specified CDS. ** ** \return Execution status, see \ref CFEReturnCodes @@ -1182,14 +1198,17 @@ CFE_Status_t CFE_ES_RestoreFromCDS(void *RestoreToMemory, CFE_ES_CDSHandle_t Han ** -# The start address of the pool must be 32-bit aligned ** -# 168 bytes are used for internal bookkeeping, therefore, they will not be available for allocation. ** -** \param[in, out] PoolID A pointer to the variable the caller wishes to have the memory pool handle kept in. +** \param[out] PoolID A pointer to the variable the caller wishes to have the memory pool handle kept in +*@nonnull. ** PoolID is the memory pool handle. ** -** \param[in] MemPtr A Pointer to the pool of memory created by the calling application. This address must +** \param[in] MemPtr A Pointer to the pool of memory created by the calling application @nonnull. This address +*must ** be aligned suitably for the processor architecture. The #CFE_ES_STATIC_POOL_TYPE ** macro may be used to assist in creating properly aligned memory pools. ** -** \param[in] Size The size of the pool of memory. Note that this must be an integral multiple of the +** \param[in] Size The size of the pool of memory @nonzero. Note that this must be an integral multiple of +*the ** memory alignment of the processor architecture. ** ** \return Execution status, see \ref CFEReturnCodes @@ -1214,14 +1233,17 @@ CFE_Status_t CFE_ES_PoolCreateNoSem(CFE_ES_MemHandle_t *PoolID, void *MemPtr, si ** -# The start address of the pool must be 32-bit aligned ** -# 168 bytes are used for internal bookkeeping, therefore, they will not be available for allocation. ** -** \param[in, out] PoolID A pointer to the variable the caller wishes to have the memory pool handle kept in. +** \param[out] PoolID A pointer to the variable the caller wishes to have the memory pool handle kept in +*@nonnull. ** PoolID is the memory pool handle. ** -** \param[in] MemPtr A Pointer to the pool of memory created by the calling application. This address must +** \param[in] MemPtr A Pointer to the pool of memory created by the calling application @nonnull. This address +*must ** be aligned suitably for the processor architecture. The #CFE_ES_STATIC_POOL_TYPE ** macro may be used to assist in creating properly aligned memory pools. ** -** \param[in] Size The size of the pool of memory. Note that this must be an integral multiple of the +** \param[in] Size The size of the pool of memory @nonzero. Note that this must be an integral multiple of +*the ** memory alignment of the processor architecture. ** ** \return Execution status, see \ref CFEReturnCodes @@ -1245,14 +1267,17 @@ CFE_Status_t CFE_ES_PoolCreate(CFE_ES_MemHandle_t *PoolID, void *MemPtr, size_t ** -# The start address of the pool must be 32-bit aligned ** -# 168 bytes are used for internal bookkeeping, therefore, they will not be available for allocation. ** -** \param[in, out] PoolID A pointer to the variable the caller wishes to have the memory pool handle kept in. +** \param[out] PoolID A pointer to the variable the caller wishes to have the memory pool handle kept in +*@nonnull. ** PoolID is the memory pool handle. ** -** \param[in] MemPtr A Pointer to the pool of memory created by the calling application. This address must +** \param[in] MemPtr A Pointer to the pool of memory created by the calling application @nonnull. This address +*must ** be aligned suitably for the processor architecture. The #CFE_ES_STATIC_POOL_TYPE ** macro may be used to assist in creating properly aligned memory pools. ** -** \param[in] Size The size of the pool of memory. Note that this must be an integral multiple of the +** \param[in] Size The size of the pool of memory @nonzero. Note that this must be an integral multiple of +*the ** memory alignment of the processor architecture. ** ** \param[in] NumBlockSizes The number of different block sizes specified in the \c BlockSizes array. If set @@ -1268,8 +1293,11 @@ CFE_Status_t CFE_ES_PoolCreate(CFE_ES_MemHandle_t *PoolID, void *MemPtr, size_t ** not. Valid parameter values are #CFE_ES_USE_MUTEX and #CFE_ES_NO_MUTEX ** ** \return Execution status, see \ref CFEReturnCodes -** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS -** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT +** \retval #CFE_ES_NO_RESOURCE_IDS_AVAILABLE \copybrief CFE_ES_NO_RESOURCE_IDS_AVAILABLE +** \retval #CFE_ES_POOL_BOUNDS_ERROR \copybrief CFE_ES_POOL_BOUNDS_ERROR +** \retval #CFE_STATUS_EXTERNAL_RESOURCE_FAIL \copybrief CFE_STATUS_EXTERNAL_RESOURCE_FAIL ** ** \sa #CFE_ES_PoolCreate, #CFE_ES_PoolCreateNoSem, #CFE_ES_GetPoolBuf, #CFE_ES_PutPoolBuf, #CFE_ES_GetMemPoolStats ** @@ -1311,12 +1339,12 @@ int32 CFE_ES_PoolDelete(CFE_ES_MemHandle_t PoolID); ** \par Assumptions, External Events, and Notes: ** -# The size allocated from the memory pool is, at a minimum, 12 bytes more than requested. ** -** \param[in, out] BufPtr A pointer to the Application's pointer in which will be stored the address of the -** allocated memory buffer. *BufPtr is the address of the requested buffer. +** \param[out] BufPtr A pointer to the Application's pointer @nonnull in which will be stored the address of the +** allocated memory buffer. *BufPtr is the address of the requested buffer. ** ** \param[in] Handle The handle to the memory pool as returned by #CFE_ES_PoolCreate or #CFE_ES_PoolCreateNoSem. ** -** \param[in] Size The size of the buffer requested. NOTE: The size allocated may be larger. +** \param[in] Size The size of the buffer requested @nonzero. NOTE: The size allocated may be larger. ** ** \return Bytes Allocated, or error code \ref CFEReturnCodes ** \retval #CFE_ES_ERR_RESOURCEID_NOT_VALID \copybrief CFE_ES_ERR_RESOURCEID_NOT_VALID @@ -1341,7 +1369,7 @@ int32 CFE_ES_GetPoolBuf(CFE_ES_MemPoolBuf_t *BufPtr, CFE_ES_MemHandle_t Handle, ** ** \param[in] Handle The handle to the memory pool as returned by #CFE_ES_PoolCreate or #CFE_ES_PoolCreateNoSem. ** -** \param[in] BufPtr A pointer to the memory buffer to provide status for. +** \param[in] BufPtr A pointer to the memory buffer to provide status for @nonnull. ** ** \return Size of the buffer if successful, or status code if not successful, see \ref CFEReturnCodes ** \retval #CFE_ES_ERR_RESOURCEID_NOT_VALID \copybrief CFE_ES_ERR_RESOURCEID_NOT_VALID @@ -1366,11 +1394,13 @@ CFE_Status_t CFE_ES_GetPoolBufInfo(CFE_ES_MemHandle_t Handle, CFE_ES_MemPoolBuf_ ** ** \param[in] Handle The handle to the memory pool as returned by #CFE_ES_PoolCreate or #CFE_ES_PoolCreateNoSem. ** -** \param[in] BufPtr A pointer to the memory buffer to be released. +** \param[in] BufPtr A pointer to the memory buffer to be released @nonnull. ** ** \return Bytes released, or error code \ref CFEReturnCodes ** \retval #CFE_ES_ERR_RESOURCEID_NOT_VALID \copybrief CFE_ES_ERR_RESOURCEID_NOT_VALID ** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT +** \retval #CFE_ES_BUFFER_NOT_IN_POOL \copybrief CFE_ES_BUFFER_NOT_IN_POOL +** \retval #CFE_ES_POOL_BLOCK_INVALID \copybrief CFE_ES_POOL_BLOCK_INVALID ** ** \sa #CFE_ES_PoolCreate, #CFE_ES_PoolCreateNoSem, #CFE_ES_PoolCreateEx, #CFE_ES_GetPoolBuf, #CFE_ES_GetMemPoolStats, *#CFE_ES_GetPoolBufInfo @@ -1390,9 +1420,9 @@ int32 CFE_ES_PutPoolBuf(CFE_ES_MemHandle_t Handle, CFE_ES_MemPoolBuf_t BufPtr); ** \par Assumptions, External Events, and Notes: ** None ** -** \param[in, out] BufPtr Pointer to #CFE_ES_MemPoolStats_t data structure to be -** filled with memory statistics. *BufPtr is the Memory Pool Statistics stored in given -** data structure. +** \param[out] BufPtr Pointer to #CFE_ES_MemPoolStats_t data structure @nonnull to be +** filled with memory statistics. *BufPtr is the Memory Pool Statistics stored in given +** data structure. ** ** \param[in] Handle The handle to the memory pool whose statistics are desired. ** @@ -1501,9 +1531,10 @@ void CFE_ES_PerfLogAdd(uint32 Marker, uint32 EntryExit); ** ** ** \return Execution status, see \ref CFEReturnCodes -** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS -** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT -** \retval #CFE_ES_ERR_DUPLICATE_NAME \copybrief CFE_ES_ERR_DUPLICATE_NAME +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT +** \retval #CFE_ES_ERR_DUPLICATE_NAME \copybrief CFE_ES_ERR_DUPLICATE_NAME +** \retval #CFE_ES_NO_RESOURCE_IDS_AVAILABLE \copybrief CFE_ES_NO_RESOURCE_IDS_AVAILABLE ** ** \sa #CFE_ES_IncrementGenCounter, #CFE_ES_DeleteGenCounter, #CFE_ES_SetGenCount, #CFE_ES_GetGenCount, *#CFE_ES_GetGenCounterIDByName diff --git a/modules/core_api/fsw/inc/cfe_evs.h b/modules/core_api/fsw/inc/cfe_evs.h index 2af93607c..1bef0d83a 100644 --- a/modules/core_api/fsw/inc/cfe_evs.h +++ b/modules/core_api/fsw/inc/cfe_evs.h @@ -102,6 +102,7 @@ ** \retval #CFE_EVS_APP_FILTER_OVERLOAD \copybrief CFE_EVS_APP_FILTER_OVERLOAD ** \retval #CFE_EVS_UNKNOWN_FILTER \copybrief CFE_EVS_UNKNOWN_FILTER ** \retval #CFE_EVS_APP_ILLEGAL_APP_ID \copybrief CFE_EVS_APP_ILLEGAL_APP_ID +** \retval #CFE_ES_BAD_ARGUMENT \copybrief CFE_ES_BAD_ARGUMENT **/ CFE_Status_t CFE_EVS_Register(const void *Filters, uint16 NumEventFilters, uint16 FilterScheme); /**@}*/ @@ -133,7 +134,7 @@ CFE_Status_t CFE_EVS_Register(const void *Filters, uint16 NumEventFilters, uint1 ** \arg #CFE_EVS_EventType_ERROR ** \arg #CFE_EVS_EventType_CRITICAL ** -** \param[in] Spec A pointer to a null terminated text string describing the output format +** \param[in] Spec A pointer to a null terminated text string @nonnull describing the output format ** for the event. This is the same type of format string used for the ANSI ** \c printf function. Nominally the post-conversion string is limited to 80 ** characters, but this limit is configurable through the parameter @@ -148,6 +149,7 @@ CFE_Status_t CFE_EVS_Register(const void *Filters, uint16 NumEventFilters, uint1 ** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS ** \retval #CFE_EVS_APP_NOT_REGISTERED \copybrief CFE_EVS_APP_NOT_REGISTERED ** \retval #CFE_EVS_APP_ILLEGAL_APP_ID \copybrief CFE_EVS_APP_ILLEGAL_APP_ID +** \retval #CFE_EVS_INVALID_PARAMETER \copybrief CFE_EVS_INVALID_PARAMETER ** ** \sa #CFE_EVS_SendEventWithAppID, #CFE_EVS_SendTimedEvent ** @@ -181,7 +183,7 @@ CFE_Status_t CFE_EVS_SendEvent(uint16 EventID, uint16 EventType, const char *Spe ** ** \param[in] AppID The Application ID from which the event message should appear. ** -** \param[in] Spec A pointer to a null terminated text string describing the output format +** \param[in] Spec A pointer to a null terminated text string @nonnull describing the output format ** for the event. This is the same type of format string used for the ANSI ** \c printf function. Nominally the post-conversion string is limited to 80 ** characters, but this limit is configurable through the parameter @@ -196,6 +198,7 @@ CFE_Status_t CFE_EVS_SendEvent(uint16 EventID, uint16 EventType, const char *Spe ** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS ** \retval #CFE_EVS_APP_NOT_REGISTERED \copybrief CFE_EVS_APP_NOT_REGISTERED ** \retval #CFE_EVS_APP_ILLEGAL_APP_ID \copybrief CFE_EVS_APP_ILLEGAL_APP_ID +** \retval #CFE_EVS_INVALID_PARAMETER \copybrief CFE_EVS_INVALID_PARAMETER ** ** \sa #CFE_EVS_SendEvent, #CFE_EVS_SendTimedEvent ** @@ -230,7 +233,7 @@ CFE_Status_t CFE_EVS_SendEventWithAppID(uint16 EventID, uint16 EventType, CFE_ES ** \arg #CFE_EVS_EventType_ERROR ** \arg #CFE_EVS_EventType_CRITICAL ** -** \param[in] Spec A pointer to a null terminated text string describing the output format +** \param[in] Spec A pointer to a null terminated text string @nonnull describing the output format ** for the event. This is the same type of format string used for the ANSI ** \c printf function. Nominally the post-conversion string is limited to 80 ** characters, but this limit is configurable through the parameter @@ -245,6 +248,7 @@ CFE_Status_t CFE_EVS_SendEventWithAppID(uint16 EventID, uint16 EventType, CFE_ES ** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS ** \retval #CFE_EVS_APP_NOT_REGISTERED \copybrief CFE_EVS_APP_NOT_REGISTERED ** \retval #CFE_EVS_APP_ILLEGAL_APP_ID \copybrief CFE_EVS_APP_ILLEGAL_APP_ID +** \retval #CFE_EVS_INVALID_PARAMETER \copybrief CFE_EVS_INVALID_PARAMETER ** ** \sa #CFE_EVS_SendEvent, #CFE_EVS_SendEventWithAppID ** @@ -275,6 +279,7 @@ CFE_Status_t CFE_EVS_SendTimedEvent(CFE_TIME_SysTime_t Time, uint16 EventID, uin ** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS ** \retval #CFE_EVS_APP_NOT_REGISTERED \copybrief CFE_EVS_APP_NOT_REGISTERED ** \retval #CFE_EVS_APP_ILLEGAL_APP_ID \copybrief CFE_EVS_APP_ILLEGAL_APP_ID +** \retval #CFE_EVS_EVT_NOT_REGISTERED \copybrief CFE_EVS_EVT_NOT_REGISTERED ** ** \sa #CFE_EVS_ResetAllFilters ** diff --git a/modules/core_api/fsw/inc/cfe_fs.h b/modules/core_api/fsw/inc/cfe_fs.h index d55cfb5ba..c23b5dafe 100644 --- a/modules/core_api/fsw/inc/cfe_fs.h +++ b/modules/core_api/fsw/inc/cfe_fs.h @@ -60,13 +60,14 @@ ** -# File offset behavior: Agnostic on entry since it will move the offset to the start of the file, ** on success the offset will be at the end of the header, undefined offset behavior for error cases. ** -** \param[in, out] Hdr Pointer to a variable of type #CFE_FS_Header_t that will be +** \param[out] Hdr Pointer to a variable of type #CFE_FS_Header_t @nonnull that will be ** filled with the contents of the Standard cFE File Header. *Hdr is the contents of the ** Standard cFE File Header for the specified file. ** \param[in] FileDes File Descriptor obtained from a previous call to #OS_OpenCreate ** that is associated with the file whose header is to be read. ** ** \return Bytes read or error status from OSAL +** \retval #CFE_FS_BAD_ARGUMENT \copybrief CFE_FS_BAD_ARGUMENT ** ** \note This function invokes OSAL API routines and the current implementation may return ** OSAL error codes to the caller if failure occurs. In a future version of CFE, the @@ -88,7 +89,7 @@ CFE_Status_t CFE_FS_ReadHeader(CFE_FS_Header_t *Hdr, osal_id_t FileDes); ** \param[in] Hdr Pointer to a variable of type #CFE_FS_Header_t that will be ** cleared and initialized ** -** \param[in] *Description Initializes Header's Description +** \param[in] Description Initializes Header's Description @nonnull ** ** \param[in] SubType Initializes Header's SubType ** @@ -128,11 +129,12 @@ void CFE_FS_InitHeader(CFE_FS_Header_t *Hdr, const char *Description, uint32 Sub ** \param[in] FileDes File Descriptor obtained from a previous call to #OS_OpenCreate ** that is associated with the file whose header is to be read. ** -** \param[in, out] Hdr Pointer to a variable of type #CFE_FS_Header_t that will be -** filled with the contents of the Standard cFE File Header. *Hdr is the contents of the -** Standard cFE File Header for the specified file. +** \param[out] Hdr Pointer to a variable of type #CFE_FS_Header_t @nonnull that will be +** filled with the contents of the Standard cFE File Header. *Hdr is the contents of the +** Standard cFE File Header for the specified file. ** ** \return Bytes read or error status from OSAL +** \retval #CFE_FS_BAD_ARGUMENT \copybrief CFE_FS_BAD_ARGUMENT ** ** \note This function invokes OSAL API routines and the current implementation may return ** OSAL error codes to the caller if failure occurs. In a future version of CFE, the @@ -166,6 +168,8 @@ CFE_Status_t CFE_FS_WriteHeader(osal_id_t FileDes, CFE_FS_Header_t *Hdr); ** to be put into the file's Standard cFE File Header. ** ** \return Execution status, see \ref CFEReturnCodes, or OSAL status +** \retval #CFE_STATUS_EXTERNAL_RESOURCE_FAIL \copybrief CFE_STATUS_EXTERNAL_RESOURCE_FAIL +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS ** ** \note This function invokes OSAL API routines and the current implementation may return ** OSAL error codes to the caller if failure occurs. In a future version of CFE, the @@ -192,7 +196,8 @@ CFE_Status_t CFE_FS_SetTimestamp(osal_id_t FileDes, CFE_TIME_SysTime_t NewTimest ** This returns the expected directory for a given class of files in the form ** of a virtual OSAL mount point string. ** -** \returns String containing the mount point, or NULL if unkown/invalid +** \returns String containing the mount point +** \retval NULL if no mount point is known for the given file category */ const char *CFE_FS_GetDefaultMountPoint(CFE_FS_FileCategory_t FileCategory); @@ -208,7 +213,8 @@ const char *CFE_FS_GetDefaultMountPoint(CFE_FS_FileCategory_t FileCategory); ** build environment to get the default/expected extension for a given file ** category. ** -** \returns String containing the extension, or NULL if unkown/invalid +** \returns String containing the extension +** \retval NULL if no default extension is known for the given file category */ const char *CFE_FS_GetDefaultExtension(CFE_FS_FileCategory_t FileCategory); @@ -235,15 +241,19 @@ const char *CFE_FS_GetDefaultExtension(CFE_FS_FileCategory_t FileCategory); ** and does not need to be null terminated. However parsing will stop ** at the first null char, when the input is shorter than the maximum. ** -** \param[out] OutputBuffer Buffer to store result. -** \param[in] InputBuffer A input buffer that may contain a file name (e.g. from command). -** \param[in] OutputBufSize Maximum Size of output buffer. +** \param[out] OutputBuffer Buffer to store result @nonnull. +** \param[in] InputBuffer A input buffer that may contain a file name (e.g. from command) @nonnull. +** \param[in] OutputBufSize Maximum Size of output buffer @nonzero. ** \param[in] InputBufSize Maximum Size of input buffer. ** \param[in] DefaultInput Default value to use for input if InputBffer is empty ** \param[in] DefaultPath Default value to use for pathname if omitted from input ** \param[in] DefaultExtension Default value to use for extension if omitted from input ** ** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_FS_BAD_ARGUMENT \copybrief CFE_FS_BAD_ARGUMENT +** \retval #CFE_FS_FNAME_TOO_LONG \copybrief CFE_FS_FNAME_TOO_LONG +** \retval #CFE_FS_INVALID_PATH \copybrief CFE_FS_INVALID_PATH +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS ** ******************************************************************************/ int32 CFE_FS_ParseInputFileNameEx(char *OutputBuffer, const char *InputBuffer, size_t OutputBufSize, @@ -267,9 +277,9 @@ int32 CFE_FS_ParseInputFileNameEx(char *OutputBuffer, const char *InputBuffer, s ** ** \sa CFE_FS_ParseInputFileNameEx() ** -** \param[out] OutputBuffer Buffer to store result. -** \param[in] InputName A null terminated input string -** \param[in] OutputBufSize Maximum Size of output buffer. +** \param[out] OutputBuffer Buffer to store result @nonnull. +** \param[in] InputName A null terminated input string @nonnull. +** \param[in] OutputBufSize Maximum Size of output buffer @nonzero. ** \param[in] FileCategory The generalized category of file (implies default path/extension) ** ** \return Execution status, see \ref CFEReturnCodes @@ -293,10 +303,14 @@ int32 CFE_FS_ParseInputFileName(char *OutputBuffer, const char *InputName, size_ ** filenames separated by "/" characters. ** -# The extracted filename (including terminator) is no longer than #OS_MAX_PATH_LEN ** -** \param[in] OriginalPath The original path. -** \param[out] FileNameOnly The filename that is extracted from the path. +** \param[in] OriginalPath The original path @nonnull +** \param[out] FileNameOnly The filename that is extracted from the path @nonnull ** ** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_FS_BAD_ARGUMENT \copybrief CFE_FS_BAD_ARGUMENT +** \retval #CFE_FS_FNAME_TOO_LONG \copybrief CFE_FS_FNAME_TOO_LONG +** \retval #CFE_FS_INVALID_PATH \copybrief CFE_FS_INVALID_PATH +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS ** ******************************************************************************/ CFE_Status_t CFE_FS_ExtractFilenameFromPath(const char *OriginalPath, char *FileNameOnly); @@ -313,9 +327,13 @@ CFE_Status_t CFE_FS_ExtractFilenameFromPath(const char *OriginalPath, char *File ** it must remain accessible by the file writer task throughout the asynchronous ** job operation. ** -** \param[inout] Meta The background file write persistent state object +** \param[inout] Meta The background file write persistent state object @nonnull ** ** \return Execution status, see \ref CFEReturnCodes +** \retval #CFE_FS_BAD_ARGUMENT \copybrief CFE_FS_BAD_ARGUMENT +** \retval #CFE_FS_INVALID_PATH \copybrief CFE_FS_INVALID_PATH +** \retval #CFE_STATUS_REQUEST_ALREADY_PENDING \copybrief CFE_STATUS_REQUEST_ALREADY_PENDING +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS ** ******************************************************************************/ int32 CFE_FS_BackgroundFileDumpRequest(CFE_FS_FileWriteMetaData_t *Meta); @@ -331,9 +349,11 @@ int32 CFE_FS_BackgroundFileDumpRequest(CFE_FS_FileWriteMetaData_t *Meta); ** \par Assumptions, External Events, and Notes: ** None ** -** \param[inout] Meta The background file write persistent state object +** \param[inout] Meta The background file write persistent state object @nonnull ** -** \return true if request is already pending, false if not +** \return boolean value indicating if request is already pending +** \retval true if request is pending +** \retval false if request is not pending ** ******************************************************************************/ bool CFE_FS_BackgroundFileDumpIsPending(const CFE_FS_FileWriteMetaData_t *Meta); diff --git a/modules/core_api/fsw/inc/cfe_msg.h b/modules/core_api/fsw/inc/cfe_msg.h index aa013fe15..89a52a9be 100644 --- a/modules/core_api/fsw/inc/cfe_msg.h +++ b/modules/core_api/fsw/inc/cfe_msg.h @@ -52,7 +52,7 @@ * set to zero (based on size), defaults are set, then the * size and bits from MsgId are set. * - * \param[in, out] MsgPtr A pointer to the buffer that contains the message. + * \param[out] MsgPtr A pointer to the buffer that contains the message @nonnull. * \param[in] MsgId MsgId that corresponds to message * \param[in] Size Total size of the mesage (used to set length field) * @@ -69,8 +69,8 @@ CFE_Status_t CFE_MSG_Init(CFE_MSG_Message_t *MsgPtr, CFE_SB_MsgId_t MsgId, CFE_M * \par Description * This routine gets the total size of the message. * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] Size Total message size + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[out] Size Total message size @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -85,7 +85,7 @@ CFE_Status_t CFE_MSG_GetSize(const CFE_MSG_Message_t *MsgPtr, CFE_MSG_Size_t *Si * \par Description * This routine sets the total size of the message. * - * \param[in, out] MsgPtr A pointer to the buffer that contains the message. + * \param[in, out] MsgPtr A pointer to the buffer that contains the message @nonnull. * \param[in] Size Total message size * * \return Execution status, see \ref CFEReturnCodes @@ -101,8 +101,8 @@ CFE_Status_t CFE_MSG_SetSize(CFE_MSG_Message_t *MsgPtr, CFE_MSG_Size_t Size); * \par Description * This routine gets the message type. * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] Type Message type + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[out] Type Message type @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -117,7 +117,7 @@ CFE_Status_t CFE_MSG_GetType(const CFE_MSG_Message_t *MsgPtr, CFE_MSG_Type_t *Ty * \par Description * This routine sets the message type. * - * \param[in, out] MsgPtr A pointer to the buffer that contains the message. + * \param[in, out] MsgPtr A pointer to the buffer that contains the message @nonnull. * \param[in] Type Message type * * \return Execution status, see \ref CFEReturnCodes @@ -133,8 +133,8 @@ CFE_Status_t CFE_MSG_SetType(CFE_MSG_Message_t *MsgPtr, CFE_MSG_Type_t Type); * \par Description * This routine gets the message header version. * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] Version Header version + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[out] Version Header version @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -166,8 +166,8 @@ CFE_Status_t CFE_MSG_SetHeaderVersion(CFE_MSG_Message_t *MsgPtr, CFE_MSG_HeaderV * \par Description * This routine gets the message secondary header boolean. * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] HasSecondary Has secondary header flag + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[out] HasSecondary Has secondary header flag @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -183,7 +183,7 @@ CFE_Status_t CFE_MSG_GetHasSecondaryHeader(const CFE_MSG_Message_t *MsgPtr, bool * This routine sets the message has secondary header boolean. Typically only * set within message initialization and not used by APPs. * - * \param[in, out] MsgPtr A pointer to the buffer that contains the message. + * \param[in, out] MsgPtr A pointer to the buffer that contains the message @nonnull. * \param[in] HasSecondary Has secondary header flag * * \return Execution status, see \ref CFEReturnCodes @@ -199,8 +199,8 @@ CFE_Status_t CFE_MSG_SetHasSecondaryHeader(CFE_MSG_Message_t *MsgPtr, bool HasSe * \par Description * This routine gets the message application ID. * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] ApId Application ID + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[out] ApId Application ID @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -217,7 +217,7 @@ CFE_Status_t CFE_MSG_GetApId(const CFE_MSG_Message_t *MsgPtr, CFE_MSG_ApId_t *Ap * at initialization using the MsgId, but API available to set * bits that may not be included in MsgId. * - * \param[in, out] MsgPtr A pointer to the buffer that contains the message. + * \param[in, out] MsgPtr A pointer to the buffer that contains the message @nonnull. * \param[in] ApId Application ID * * \return Execution status, see \ref CFEReturnCodes @@ -233,8 +233,8 @@ CFE_Status_t CFE_MSG_SetApId(CFE_MSG_Message_t *MsgPtr, CFE_MSG_ApId_t ApId); * \par Description * This routine gets the message segmentation flag * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] SegFlag Segmentation flag + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[out] SegFlag Segmentation flag @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -249,7 +249,7 @@ CFE_Status_t CFE_MSG_GetSegmentationFlag(const CFE_MSG_Message_t *MsgPtr, CFE_MS * \par Description * This routine sets the message segmentation flag. * - * \param[in, out] MsgPtr A pointer to the buffer that contains the message. + * \param[in, out] MsgPtr A pointer to the buffer that contains the message @nonnull. * \param[in] SegFlag Segmentation flag * * \return Execution status, see \ref CFEReturnCodes @@ -265,8 +265,8 @@ CFE_Status_t CFE_MSG_SetSegmentationFlag(CFE_MSG_Message_t *MsgPtr, CFE_MSG_Segm * \par Description * This routine gets the message sequence count. * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] SeqCnt Sequence count + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[out] SeqCnt Sequence count @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -281,7 +281,7 @@ CFE_Status_t CFE_MSG_GetSequenceCount(const CFE_MSG_Message_t *MsgPtr, CFE_MSG_S * \par Description * This routine sets the message sequence count. * - * \param[in, out] MsgPtr A pointer to the buffer that contains the message. + * \param[in, out] MsgPtr A pointer to the buffer that contains the message @nonnull. * \param[in] SeqCnt Sequence count * * \return Execution status, see \ref CFEReturnCodes @@ -313,8 +313,8 @@ CFE_MSG_SequenceCount_t CFE_MSG_GetNextSequenceCount(CFE_MSG_SequenceCount_t Seq * \par Description * This routine gets the message EDS version. * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] Version EDS Version + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[out] Version EDS Version @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -329,7 +329,7 @@ CFE_Status_t CFE_MSG_GetEDSVersion(const CFE_MSG_Message_t *MsgPtr, CFE_MSG_EDSV * \par Description * This routine sets the message EDS version. * - * \param[in, out] MsgPtr A pointer to the buffer that contains the message. + * \param[in, out] MsgPtr A pointer to the buffer that contains the message @nonnull. * \param[in] Version EDS Version * * \return Execution status, see \ref CFEReturnCodes @@ -345,8 +345,8 @@ CFE_Status_t CFE_MSG_SetEDSVersion(CFE_MSG_Message_t *MsgPtr, CFE_MSG_EDSVersion * \par Description * This routine gets the message endian. * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] Endian Endian + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[out] Endian Endian @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -362,7 +362,7 @@ CFE_Status_t CFE_MSG_GetEndian(const CFE_MSG_Message_t *MsgPtr, CFE_MSG_Endian_t * This routine sets the message endian. Invalid endian selection * will set big endian. * - * \param[in, out] MsgPtr A pointer to the buffer that contains the message. + * \param[in, out] MsgPtr A pointer to the buffer that contains the message @nonnull. * \param[in] Endian Endian * * \return Execution status, see \ref CFEReturnCodes @@ -378,8 +378,8 @@ CFE_Status_t CFE_MSG_SetEndian(CFE_MSG_Message_t *MsgPtr, CFE_MSG_Endian_t Endia * \par Description * This routine gets the message playback flag. * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] PlayFlag Playback Flag + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[out] PlayFlag Playback Flag @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -394,7 +394,7 @@ CFE_Status_t CFE_MSG_GetPlaybackFlag(const CFE_MSG_Message_t *MsgPtr, CFE_MSG_Pl * \par Description * This routine sets the message playback flag. * - * \param[in, out] MsgPtr A pointer to the buffer that contains the message. + * \param[in, out] MsgPtr A pointer to the buffer that contains the message @nonnull. * \param[in] PlayFlag Playback Flag * * \return Execution status, see \ref CFEReturnCodes @@ -410,8 +410,8 @@ CFE_Status_t CFE_MSG_SetPlaybackFlag(CFE_MSG_Message_t *MsgPtr, CFE_MSG_Playback * \par Description * This routine gets the message subsystem * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] Subsystem Subsystem + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[out] Subsystem Subsystem @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -428,7 +428,7 @@ CFE_Status_t CFE_MSG_GetSubsystem(const CFE_MSG_Message_t *MsgPtr, CFE_MSG_Subsy * be set at initialization using the MsgId, but API available to set * bits that may not be included in MsgId. * - * \param[in, out] MsgPtr A pointer to the buffer that contains the message. + * \param[in, out] MsgPtr A pointer to the buffer that contains the message @nonnull. * \param[in] Subsystem Subsystem * * \return Execution status, see \ref CFEReturnCodes @@ -444,8 +444,8 @@ CFE_Status_t CFE_MSG_SetSubsystem(CFE_MSG_Message_t *MsgPtr, CFE_MSG_Subsystem_t * \par Description * This routine gets the message system id * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] System System + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[out] System System @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -462,7 +462,7 @@ CFE_Status_t CFE_MSG_GetSystem(const CFE_MSG_Message_t *MsgPtr, CFE_MSG_System_t * be set at initialization using the MsgId, but API available to set * bits that may not be included in MsgId. * - * \param[in, out] MsgPtr A pointer to the buffer that contains the message. + * \param[in, out] MsgPtr A pointer to the buffer that contains the message @nonnull. * \param[in] System System * * \return Execution status, see \ref CFEReturnCodes @@ -487,7 +487,7 @@ CFE_Status_t CFE_MSG_SetSystem(CFE_MSG_Message_t *MsgPtr, CFE_MSG_System_t Syste * include a checksum field, then this routine will return * #CFE_MSG_WRONG_MSG_TYPE * - * \param[in, out] MsgPtr A pointer to the buffer that contains the message. + * \param[in, out] MsgPtr A pointer to the buffer that contains the message @nonnull. * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -509,9 +509,9 @@ CFE_Status_t CFE_MSG_GenerateChecksum(CFE_MSG_Message_t *MsgPtr); * include a checksum field, then this routine will return * #CFE_MSG_WRONG_MSG_TYPE and set the IsValid parameter false. * - * \param[in] MsgPtr A pointer to the buffer that contains the message. + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. * This must point to the first byte of the message header. - * \param[out] IsValid Checksum validation result + * \param[out] IsValid Checksum validation result @nonnull * \arg true - valid * \arg false - invalid or not supported/implemented * @@ -534,7 +534,7 @@ CFE_Status_t CFE_MSG_ValidateChecksum(const CFE_MSG_Message_t *MsgPtr, bool *IsV * include a function code field, then this routine will do nothing to * the message contents and will return #CFE_MSG_WRONG_MSG_TYPE. * - * \param[in, out] MsgPtr A pointer to the buffer that contains the message. + * \param[in, out] MsgPtr A pointer to the buffer that contains the message @nonnull. * \param[in] FcnCode The function code to include in the message. * * \return Execution status, see \ref CFEReturnCodes @@ -557,8 +557,8 @@ CFE_Status_t CFE_MSG_SetFcnCode(CFE_MSG_Message_t *MsgPtr, CFE_MSG_FcnCode_t Fcn * include a function code field, then this routine will * set FcnCode to zero and return #CFE_MSG_WRONG_MSG_TYPE * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] FcnCode The function code from the message + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[out] FcnCode The function code from the message @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -580,8 +580,8 @@ CFE_Status_t CFE_MSG_GetFcnCode(const CFE_MSG_Message_t *MsgPtr, CFE_MSG_FcnCode * to zero and return #CFE_MSG_WRONG_MSG_TYPE * - Note default implementation of command messages do not have a time field. * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] Time Time from the message + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[out] Time Time from the message @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -606,7 +606,7 @@ CFE_Status_t CFE_MSG_GetMsgTime(const CFE_MSG_Message_t *MsgPtr, CFE_TIME_SysTim * and will return #CFE_MSG_WRONG_MSG_TYPE. * - Note default implementation of command messages do not have a time field. * - * \param[in, out] MsgPtr A pointer to the message. + * \param[in, out] MsgPtr A pointer to the message @nonnull. * \param[in] NewTime The time to include in the message. This will usually be a time * from #CFE_TIME_GetTime. * @@ -633,8 +633,8 @@ CFE_Status_t CFE_MSG_SetMsgTime(CFE_MSG_Message_t *MsgPtr, CFE_TIME_SysTime_t Ne * routing. Message id needs to be unique for each endpoint * in the system. * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] MsgId Message id + * \param[in] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[out] MsgId Message id @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -655,8 +655,8 @@ CFE_Status_t CFE_MSG_GetMsgId(const CFE_MSG_Message_t *MsgPtr, CFE_SB_MsgId_t *M * This API only sets the bits in the header that make up the message ID. * No other values in the header are modified. * - * \param[in] MsgPtr A pointer to the buffer that contains the message. - * \param[out] MsgId Message id + * \param[in, out] MsgPtr A pointer to the buffer that contains the message @nonnull. + * \param[in] MsgId Message id * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -672,7 +672,7 @@ CFE_Status_t CFE_MSG_SetMsgId(CFE_MSG_Message_t *MsgPtr, CFE_SB_MsgId_t MsgId); * This routine gets the message type using the message ID * * \param[in] MsgId Message id - * \param[out] Type Message type + * \param[out] Type Message type @nonnull * * \return Execution status, see \ref CFEReturnCodes * \retval #CFE_SUCCESS \copybrief CFE_SUCCESS diff --git a/modules/core_api/fsw/inc/cfe_resourceid.h b/modules/core_api/fsw/inc/cfe_resourceid.h index 5cb5e223e..bcb1c786b 100644 --- a/modules/core_api/fsw/inc/cfe_resourceid.h +++ b/modules/core_api/fsw/inc/cfe_resourceid.h @@ -212,7 +212,11 @@ CFE_ResourceId_t CFE_ResourceId_FindNext(CFE_ResourceId_t StartId, uint32 TableS * @param[in] BaseValue The respective ID base value corresponding to the ID type * @param[in] TableSize The actual size of the internal table (MAX index value + 1) * @param[out] Idx The output index - * @returns Status code, CFE_SUCCESS if successful. + * + * @return Execution status, see @ref CFEReturnCodes + * @retval #CFE_SUCCESS @copybrief CFE_SUCCESS + * @retval #CFE_ES_BAD_ARGUMENT @copybrief CFE_ES_BAD_ARGUMENT + * @retval #CFE_ES_ERR_RESOURCEID_NOT_VALID @copybrief CFE_ES_ERR_RESOURCEID_NOT_VALID */ int32 CFE_ResourceId_ToIndex(CFE_ResourceId_t Id, uint32 BaseValue, uint32 TableSize, uint32 *Idx); diff --git a/modules/core_api/fsw/inc/cfe_sb.h b/modules/core_api/fsw/inc/cfe_sb.h index 92f83c82c..0d8b30a7a 100644 --- a/modules/core_api/fsw/inc/cfe_sb.h +++ b/modules/core_api/fsw/inc/cfe_sb.h @@ -68,14 +68,14 @@ ** \par Assumptions, External Events, and Notes: ** None ** -** \param[in, out] PipeIdPtr A pointer to a variable of type #CFE_SB_PipeId_t, +** \param[out] PipeIdPtr A pointer to a variable of type #CFE_SB_PipeId_t @nonnull, ** which will be filled in with the pipe ID information ** by the #CFE_SB_CreatePipe routine. *PipeIdPtr is the identifier for the created pipe. ** ** \param[in] Depth The maximum number of messages that will be allowed on ** this pipe at one time. ** -** \param[in] PipeName A string to be used to identify this pipe in error messages +** \param[in] PipeName A string @nonnull to be used to identify this pipe in error messages ** and routing information telemetry. The string must be no ** longer than #OS_MAX_API_NAME (including terminator). ** Longer strings will be truncated. @@ -136,7 +136,7 @@ CFE_Status_t CFE_SB_DeletePipe(CFE_SB_PipeId_t PipeId); * for future use. * * @param[in] PipeID Pipe ID to convert - * @param[out] Idx Buffer where the calculated index will be stored + * @param[out] Idx Buffer where the calculated index will be stored @nonnull * * @return Execution status, see @ref CFEReturnCodes * @retval #CFE_SUCCESS @copybrief CFE_SUCCESS @@ -173,7 +173,7 @@ CFE_Status_t CFE_SB_SetPipeOpts(CFE_SB_PipeId_t PipeId, uint8 Opts); ** ** \param[in] PipeId The pipe ID of the pipe to get options from. ** -** \param[out] *OptsPtr A bit field of options: \ref CFESBPipeOptions +** \param[out] OptsPtr A bit field of options: \ref CFESBPipeOptions @nonnull ** ** \return Execution status, see \ref CFEReturnCodes ** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -190,9 +190,9 @@ CFE_Status_t CFE_SB_GetPipeOpts(CFE_SB_PipeId_t PipeId, uint8 *OptsPtr); ** \par Description ** This routine finds the pipe name for a pipe id. ** -** \param[out] PipeNameBuf The buffer to receive the pipe name. +** \param[out] PipeNameBuf The buffer to receive the pipe name @nonnull. ** -** \param[in] PipeNameSize The size (in chars) of the PipeName buffer. +** \param[in] PipeNameSize The size (in chars) of the PipeName buffer @nonzero. ** ** \param[in] PipeId The PipeId for that name. ** @@ -211,9 +211,9 @@ CFE_Status_t CFE_SB_GetPipeName(char *PipeNameBuf, size_t PipeNameSize, CFE_SB_P ** \par Description ** This routine finds the pipe id for a pipe name. ** -** \param[in] PipeName The name of the pipe. +** \param[in] PipeName The name of the pipe @nonnull. ** -** \param[out] PipeIdPtr The PipeId for that name. +** \param[out] PipeIdPtr The PipeId for that name @nonnull. ** ** \return Execution status, see \ref CFEReturnCodes ** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS @@ -411,7 +411,7 @@ CFE_Status_t CFE_SB_UnsubscribeLocal(CFE_SB_MsgId_t MsgId, CFE_SB_PipeId_t PipeI ** this message, that task may get to run before returning ** control to the caller. ** -** \param[in] MsgPtr A pointer to the message to be sent. This must point +** \param[in] MsgPtr A pointer to the message to be sent @nonnull. This must point ** to the first byte of the message header. ** \param[in] IncrementSequenceCount Boolean to increment the internally tracked ** sequence count and update the message if the @@ -439,7 +439,7 @@ CFE_Status_t CFE_SB_TransmitMsg(CFE_MSG_Message_t *MsgPtr, bool IncrementSequenc ** random. Therefore, it is recommended that the return code be tested ** for CFE_SUCCESS before processing the message. ** -** \param[in, out] BufPtr A pointer to the software bus buffer to receive to. +** \param[in, out] BufPtr A pointer to the software bus buffer to receive to @nonnull. ** Typically a caller declares a ptr of type CFE_SB_Buffer_t ** (i.e. CFE_SB_Buffer_t *Ptr) then gives the address of that ** pointer (&Ptr) as this parmeter. After a successful @@ -515,7 +515,7 @@ CFE_SB_Buffer_t *CFE_SB_AllocateMessageBuffer(size_t MsgSize); ** CFE_SB_AllocateMessageBuffer(), but (due to some error condition) never ** uses that pointer in a call to CFE_SB_TransmitBuffer(). ** -** \param[in] BufPtr A pointer to the SB internal buffer. This must be a +** \param[in] BufPtr A pointer to the SB internal buffer @nonnull. This must be a ** pointer returned by a call to CFE_SB_AllocateMessageBuffer(), ** but never used in a call to CFE_SB_TransmitBuffer(). ** @@ -555,7 +555,7 @@ CFE_Status_t CFE_SB_ReleaseMessageBuffer(CFE_SB_Buffer_t *BufPtr); ** -# This function will increment and apply the internally tracked ** sequence counter if set to do so. ** -** \param[in] BufPtr A pointer to the buffer to be sent. +** \param[in] BufPtr A pointer to the buffer to be sent @nonnull. ** \param[in] IncrementSequenceCount Boolean to increment the internally tracked ** sequence count and update the message if the ** buffer contains a telemetry message @@ -588,7 +588,7 @@ CFE_Status_t CFE_SB_TransmitBuffer(CFE_SB_Buffer_t *BufPtr, bool IncrementSequen ** - You must set a valid message ID in the SB message header before ** calling this function. ** -** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. +** \param[in] MsgPtr A pointer to the buffer that contains the software bus message @nonnull. ** This must point to the first byte of the message header. ** ** \param[in] DataLength The length to set (size of the user data, in bytes). @@ -608,7 +608,7 @@ void CFE_SB_SetUserDataLength(CFE_MSG_Message_t *MsgPtr, size_t DataLength); ** - If the underlying implementation of software bus messages does not ** include a time field, then this routine will do nothing. ** -** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. +** \param[in] MsgPtr A pointer to the buffer that contains the software bus message @nonnull. ** This must point to the first byte of the message header. **/ void CFE_SB_TimeStampMsg(CFE_MSG_Message_t *MsgPtr); @@ -637,12 +637,13 @@ void CFE_SB_TimeStampMsg(CFE_MSG_Message_t *MsgPtr); ** implementation. It is only necessary to use this when termination of the source ** buffer is not guaranteed. ** -** \param[out] DestStringPtr Pointer to destination buffer (component of SB message definition) -** \param[in] SourceStringPtr Pointer to source buffer +** \param[out] DestStringPtr Pointer to destination buffer (component of SB message definition) @nonnull +** \param[in] SourceStringPtr Pointer to source buffer @nonnull ** \param[in] DestMaxSize Size of destination buffer as defined by the message definition ** \param[in] SourceMaxSize Size of source buffer ** ** \return Number of characters copied or error code, see \ref CFEReturnCodes +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT ** */ int32 CFE_SB_MessageStringSet(char *DestStringPtr, const char *SourceStringPtr, size_t DestMaxSize, @@ -666,7 +667,7 @@ int32 CFE_SB_MessageStringSet(char *DestStringPtr, const char *SourceStringPtr, ** \par Assumptions, External Events, and Notes: ** None ** -** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. +** \param[in] MsgPtr A pointer to the buffer that contains the software bus message @nonnull. ** ** \return A pointer to the first byte of user data within the software bus message. **/ @@ -682,7 +683,7 @@ void *CFE_SB_GetUserData(CFE_MSG_Message_t *MsgPtr); ** \par Assumptions, External Events, and Notes: ** None ** -** \param[in] MsgPtr A pointer to the buffer that contains the software bus message. +** \param[in] MsgPtr A pointer to the buffer that contains the software bus message @nonnull. ** This must point to the first byte of the message header. ** ** \return The size (in bytes) of the user data in the software bus message. @@ -720,13 +721,14 @@ size_t CFE_SB_GetUserDataLength(const CFE_MSG_Message_t *MsgPtr); ** If the destination buffer is too small to store the entire string, it will be ** truncated, but it will still be null terminated. ** -** \param[out] DestStringPtr Pointer to destination buffer -** \param[in] SourceStringPtr Pointer to source buffer (component of SB message definition) +** \param[out] DestStringPtr Pointer to destination buffer @nonnull +** \param[in] SourceStringPtr Pointer to source buffer (component of SB message definition) @nonnull ** \param[in] DefaultString Default string to use if source is empty ** \param[in] DestMaxSize Size of destination storage buffer (must be at least 2) ** \param[in] SourceMaxSize Size of source buffer as defined by the message definition ** ** \return Number of characters copied or error code, see \ref CFEReturnCodes +** \retval #CFE_SB_BAD_ARGUMENT \copybrief CFE_SB_BAD_ARGUMENT ** */ int32 CFE_SB_MessageStringGet(char *DestStringPtr, const char *SourceStringPtr, const char *DefaultString, diff --git a/modules/core_api/fsw/inc/cfe_tbl.h b/modules/core_api/fsw/inc/cfe_tbl.h index abb46723b..e4f03a552 100644 --- a/modules/core_api/fsw/inc/cfe_tbl.h +++ b/modules/core_api/fsw/inc/cfe_tbl.h @@ -64,7 +64,7 @@ ** their own tables. An application should create any table(s) and provide the handle(s) ** to the interrupt service routine. ** -** \param[in, out] TblHandlePtr a pointer to a #CFE_TBL_Handle_t type variable that will be assigned the table's +** \param[out] TblHandlePtr a pointer to a #CFE_TBL_Handle_t type variable @nonnull that will be assigned the table's ** handle. The table handle is required for other API calls when accessing the data ** contained in the table. *TblHandlePtr is the handle used to identify table to cFE ** when performing Table operations. This value is returned at ddress specified by @@ -75,7 +75,8 @@ ** This application specific name will be used in commands ** for modifying or viewing the contents of the table. ** -** \param[in] Size The size, in bytes, of the table to be created. This is the size that will be +** \param[in] Size The size, in bytes, of the table to be created @nonzero. This is the size that will +*be ** allocated as a shared memory resource between the Table Management Service and ** the calling application. ** @@ -180,6 +181,10 @@ ** \retval #CFE_TBL_ERR_INVALID_SIZE \copybrief CFE_TBL_ERR_INVALID_SIZE ** \retval #CFE_TBL_ERR_INVALID_NAME \copybrief CFE_TBL_ERR_INVALID_NAME ** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_BAD_ARGUMENT \copybrief CFE_TBL_BAD_ARGUMENT +** \retval #CFE_TBL_ERR_INVALID_OPTIONS \copybrief CFE_TBL_ERR_INVALID_OPTIONS +** \retval #CFE_TBL_WARN_DUPLICATE \copybrief CFE_TBL_WARN_DUPLICATE +** \retval #CFE_TBL_WARN_NOT_CRITICAL \copybrief CFE_TBL_WARN_NOT_CRITICAL ** ** \sa #CFE_TBL_Unregister, #CFE_TBL_Share **/ @@ -199,7 +204,7 @@ CFE_Status_t CFE_TBL_Register(CFE_TBL_Handle_t *TblHandlePtr, const char *Name, ** \par Assumptions, External Events, and Notes: ** None ** -** \param[in, out] TblHandlePtr A pointer to a #CFE_TBL_Handle_t type variable +** \param[out] TblHandlePtr A pointer to a #CFE_TBL_Handle_t type variable @nonnull ** that will be assigned the table's handle. The ** table handle is required for other API calls ** when accessing the data contained in the table. *TblHandlePtr is the handle used to @@ -216,6 +221,7 @@ CFE_Status_t CFE_TBL_Register(CFE_TBL_Handle_t *TblHandlePtr, const char *Name, ** \retval #CFE_TBL_ERR_HANDLES_FULL \copybrief CFE_TBL_ERR_HANDLES_FULL ** \retval #CFE_TBL_ERR_INVALID_NAME \copybrief CFE_TBL_ERR_INVALID_NAME ** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_BAD_ARGUMENT \copybrief CFE_TBL_BAD_ARGUMENT ** ** \sa #CFE_TBL_Unregister, #CFE_TBL_Register ** @@ -290,7 +296,7 @@ CFE_Status_t CFE_TBL_Unregister(CFE_TBL_Handle_t TblHandle); ** \arg #CFE_TBL_SRC_FILE - \copybrief CFE_TBL_SRC_FILE ** \arg #CFE_TBL_SRC_ADDRESS - \copybrief CFE_TBL_SRC_ADDRESS ** -** \param[in] SrcDataPtr Pointer to either a character string specifying a filename or +** \param[in] SrcDataPtr Pointer @nonnull to either a character string specifying a filename or ** a memory address of a block of binary data to be loaded into a table or, ** if the table was registered with the #CFE_TBL_OPT_USR_DEF_ADDR option, ** the address of the active table buffer. @@ -310,6 +316,8 @@ CFE_Status_t CFE_TBL_Unregister(CFE_TBL_Handle_t TblHandle); ** \retval #CFE_TBL_ERR_FILE_TOO_LARGE \copybrief CFE_TBL_ERR_FILE_TOO_LARGE ** \retval #CFE_TBL_ERR_BAD_CONTENT_ID \copybrief CFE_TBL_ERR_BAD_CONTENT_ID ** \retval #CFE_TBL_ERR_PARTIAL_LOAD \copybrief CFE_TBL_ERR_PARTIAL_LOAD +** \retval #CFE_TBL_BAD_ARGUMENT \copybrief CFE_TBL_BAD_ARGUMENT +** \retval #CFE_TBL_WARN_PARTIAL_LOAD \copybrief CFE_TBL_WARN_PARTIAL_LOAD ** ** \sa #CFE_TBL_Update, #CFE_TBL_Validate, #CFE_TBL_Manage ** @@ -389,11 +397,14 @@ CFE_Status_t CFE_TBL_Validate(CFE_TBL_Handle_t TblHandle); ** identifies the Table to be managed. ** ** \return Execution status, see \ref CFEReturnCodes -** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS -** \retval #CFE_TBL_INFO_UPDATED \copybrief CFE_TBL_INFO_UPDATED -** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID -** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS -** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE +** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS +** \retval #CFE_TBL_INFO_UPDATED \copybrief CFE_TBL_INFO_UPDATED +** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID +** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS +** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE +** \retval #CFE_TBL_INFO_DUMP_PENDING \copybrief CFE_TBL_INFO_DUMP_PENDING +** \retval #CFE_TBL_INFO_UPDATE_PENDING \copybrief CFE_TBL_INFO_UPDATE_PENDING +** \retval #CFE_TBL_INFO_VALIDATION_PENDING \copybrief CFE_TBL_INFO_VALIDATION_PENDING ** ** \sa #CFE_TBL_Update, #CFE_TBL_Validate, #CFE_TBL_Load, #CFE_TBL_DumpToBuffer ** @@ -420,6 +431,7 @@ CFE_Status_t CFE_TBL_Manage(CFE_TBL_Handle_t TblHandle); ** \retval #CFE_TBL_ERR_BAD_APP_ID \copybrief CFE_TBL_ERR_BAD_APP_ID ** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS ** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE +** \retval #CFE_TBL_INFO_DUMP_PENDING \copybrief CFE_TBL_INFO_DUMP_PENDING ** ** \sa #CFE_TBL_Manage ** @@ -484,7 +496,7 @@ CFE_Status_t CFE_TBL_Modified(CFE_TBL_Handle_t TblHandle); ** This pointer mush be released with the #CFE_TBL_ReleaseAddress API before ** the table can be loaded with data. ** -** \param[in, out] TblPtr The address of a pointer that will be loaded with the address of +** \param[out] TblPtr The address of a pointer @nonnull that will be loaded with the address of ** the first byte of the table. This pointer can then be typecast ** by the calling application to the appropriate table data structure. *TblPtr is the address of ** the first byte of data associated with the specified table. @@ -500,6 +512,7 @@ CFE_Status_t CFE_TBL_Modified(CFE_TBL_Handle_t TblHandle); ** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE ** \retval #CFE_TBL_ERR_UNREGISTERED \copybrief CFE_TBL_ERR_UNREGISTERED ** \retval #CFE_TBL_ERR_NEVER_LOADED \copybrief CFE_TBL_ERR_NEVER_LOADED +** \retval #CFE_TBL_BAD_ARGUMENT \copybrief CFE_TBL_BAD_ARGUMENT ** ** \sa #CFE_TBL_ReleaseAddress, #CFE_TBL_GetAddresses, #CFE_TBL_ReleaseAddresses ** @@ -563,7 +576,7 @@ CFE_Status_t CFE_TBL_ReleaseAddress(CFE_TBL_Handle_t TblHandle); ** This pointer mush be released with the #CFE_TBL_ReleaseAddress API before ** the table can be loaded with data. ** -** \param[in, out] TblPtrs Array of Pointers to variables that calling Application +** \param[out] TblPtrs Array of Pointers @nonnull to variables that calling Application ** wishes to hold the start addresses of the Tables. *TblPtrs is an array of addresses of the ** first byte of data associated with the specified tables. ** @@ -580,6 +593,7 @@ CFE_Status_t CFE_TBL_ReleaseAddress(CFE_TBL_Handle_t TblHandle); ** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE ** \retval #CFE_TBL_ERR_UNREGISTERED \copybrief CFE_TBL_ERR_UNREGISTERED ** \retval #CFE_TBL_ERR_NEVER_LOADED \copybrief CFE_TBL_ERR_NEVER_LOADED +** \retval #CFE_TBL_BAD_ARGUMENT \copybrief CFE_TBL_BAD_ARGUMENT ** ** \sa #CFE_TBL_GetAddress, #CFE_TBL_ReleaseAddress, #CFE_TBL_ReleaseAddresses ** @@ -602,7 +616,7 @@ CFE_Status_t CFE_TBL_GetAddresses(void **TblPtrs[], uint16 NumTables, const CFE_ ** ** \param[in] NumTables Size of TblHandles array. ** -** \param[in] TblHandles Array of Table Handles, previously obtained from #CFE_TBL_Register or #CFE_TBL_Share, +** \param[in] TblHandles Array of Table Handles @nonnull, previously obtained from #CFE_TBL_Register or #CFE_TBL_Share, ** of those tables whose start addresses are to be released. ** ** \return Execution status, see \ref CFEReturnCodes @@ -612,6 +626,7 @@ CFE_Status_t CFE_TBL_GetAddresses(void **TblPtrs[], uint16 NumTables, const CFE_ ** \retval #CFE_TBL_ERR_NO_ACCESS \copybrief CFE_TBL_ERR_NO_ACCESS ** \retval #CFE_TBL_ERR_INVALID_HANDLE \copybrief CFE_TBL_ERR_INVALID_HANDLE ** \retval #CFE_TBL_ERR_NEVER_LOADED \copybrief CFE_TBL_ERR_NEVER_LOADED +** \retval #CFE_TBL_BAD_ARGUMENT \copybrief CFE_TBL_BAD_ARGUMENT ** ** \sa #CFE_TBL_GetAddress, #CFE_TBL_ReleaseAddress, #CFE_TBL_GetAddresses ** @@ -670,11 +685,11 @@ CFE_Status_t CFE_TBL_GetStatus(CFE_TBL_Handle_t TblHandle); ** \par Assumptions, External Events, and Notes: ** None ** -** \param[in, out] TblInfoPtr A pointer to a CFE_TBL_Info_t data structure that is to be populated +** \param[out] TblInfoPtr A pointer to a CFE_TBL_Info_t data structure @nonnull that is to be populated ** with table characteristics and information. *TblInfoPtr is the description of the tables ** characteristics and registry information stored in the #CFE_TBL_Info_t data structure ** format. -** \param[in] TblName The application specific name of the table of the form "AppName.RawTableName", +** \param[in] TblName The application specific name @nonnull of the table of the form "AppName.RawTableName", ** where RawTableName is the name specified in the #CFE_TBL_Register API call. ** Example: "ACS.TamParams" for a table called "TamParams" ** that was registered by the application called "ACS". @@ -682,6 +697,7 @@ CFE_Status_t CFE_TBL_GetStatus(CFE_TBL_Handle_t TblHandle); ** \return Execution status, see \ref CFEReturnCodes ** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS ** \retval #CFE_TBL_ERR_INVALID_NAME \copybrief CFE_TBL_ERR_INVALID_NAME +** \retval #CFE_TBL_BAD_ARGUMENT \copybrief CFE_TBL_BAD_ARGUMENT ** ** \sa #CFE_TBL_GetStatus ** diff --git a/modules/core_api/fsw/inc/cfe_time.h b/modules/core_api/fsw/inc/cfe_time.h index 23ae0cc7f..a13e71e35 100644 --- a/modules/core_api/fsw/inc/cfe_time.h +++ b/modules/core_api/fsw/inc/cfe_time.h @@ -633,9 +633,12 @@ void CFE_TIME_ExternalTime(CFE_TIME_SysTime_t NewTime); ** If an application requires triggering multiple child tasks at 1Hz, it should distribute ** the timing signal internally, rather than registering for multiple callbacks. ** +** \param[in] CallbackFuncPtr Function to call at synchronization interval @nonnull +** ** \return Execution status, see \ref CFEReturnCodes ** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS ** \retval #CFE_TIME_TOO_MANY_SYNCH_CALLBACKS \copybrief CFE_TIME_TOO_MANY_SYNCH_CALLBACKS +** \retval #CFE_TIME_BAD_ARGUMENT \copybrief CFE_TIME_BAD_ARGUMENT ** ** \sa #CFE_TIME_UnregisterSynchCallback ** @@ -655,9 +658,12 @@ CFE_Status_t CFE_TIME_RegisterSynchCallback(CFE_TIME_SynchCallbackPtr_t Callback ** Only a single callback per application is supported, and this function should only ** be called from a single thread within each application (typically the apps main thread). ** +** \param[in] CallbackFuncPtr Function to remove from synchronization call list @nonnull +** ** \return Execution status, see \ref CFEReturnCodes ** \retval #CFE_SUCCESS \copybrief CFE_SUCCESS ** \retval #CFE_TIME_CALLBACK_NOT_REGISTERED \copybrief CFE_TIME_CALLBACK_NOT_REGISTERED +** \retval #CFE_TIME_BAD_ARGUMENT \copybrief CFE_TIME_BAD_ARGUMENT ** ** \sa #CFE_TIME_RegisterSynchCallback ** @@ -696,7 +702,7 @@ CFE_Status_t CFE_TIME_UnregisterSynchCallback(CFE_TIME_SynchCallbackPtr_t Callba ** the maximum amount of time represented by a CFE_TIME_SysTime ** structure is approximately 136 years. ** -** \param[in, out] PrintBuffer Pointer to a character array of at least +** \param[out] PrintBuffer Pointer to a character array @nonnull of at least ** #CFE_TIME_PRINTED_STRING_SIZE characters in length. *PrintBuffer is the time as a ** character string as described above. **