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 cfadad6 commit 98bc267
Show file tree
Hide file tree
Showing 7 changed files with 179 additions and 154 deletions.
128 changes: 73 additions & 55 deletions modules/core_api/fsw/inc/cfe_es.h
View file

Large diffs are not rendered by default.

6 changes: 3 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 @@ -133,7 +133,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 Down Expand Up @@ -181,7 +181,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 Down Expand Up @@ -230,7 +230,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 Down
36 changes: 19 additions & 17 deletions modules/core_api/fsw/inc/cfe_fs.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@
** -# 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
Expand Down Expand Up @@ -88,7 +88,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,9 +128,9 @@ 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
**
Expand Down Expand Up @@ -192,7 +192,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 +209,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,9 +237,9 @@ 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
Expand Down Expand Up @@ -267,9 +269,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,8 +295,8 @@ 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
**
Expand All @@ -313,7 +315,7 @@ 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
**
Expand All @@ -331,7 +333,7 @@ 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
**
Expand Down
Loading

0 comments on commit 98bc267

Please sign in to comment.