Skip to content

Commit

Permalink
Partial #1724, update in/out status and nonnull/nonzero tags
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@jphickey
jphickey committed Aug 11, 2021
1 parent eb9c523 commit 052ad37
Show file tree
Hide file tree
Showing 8 changed files with 252 additions and 168 deletions.
153 changes: 92 additions & 61 deletions modules/core_api/fsw/inc/cfe_es.h
View file

Large diffs are not rendered by default.

11 changes: 8 additions & 3 deletions modules/core_api/fsw/inc/cfe_evs.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
/**@}*/
Expand Down Expand Up @@ -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
Expand All @@ -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
**
Expand Down Expand Up @@ -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
Expand All @@ -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
**
Expand Down Expand Up @@ -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
Expand All @@ -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
**
Expand Down Expand Up @@ -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
**
Expand Down
56 changes: 38 additions & 18 deletions modules/core_api/fsw/inc/cfe_fs.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
**
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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);

Expand All @@ -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);

Expand All @@ -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,
Expand All @@ -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
Expand All @@ -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);
Expand All @@ -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);
Expand All @@ -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);
Expand Down
Loading

0 comments on commit 052ad37

Please sign in to comment.