Fix #17: Update function description blocks across OSAL #21
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Update all block comments for OSAL functions to follow a consistent style and ensure correctness of the descriptions. - All documentation covering the specific details, inputs/outputs and return values should be on the function _declaration_, not the definition. - The definition should also contain a block comment for visual distinction in the source file, but should be brief and refer back to the prototype/declaration for detail. Any detail information that was indicated only with the definition is moved to the declaration. - Add doxygen tags/markup to external/public API block comments and expand the descriptions of these functions where needed. - Add block comments to the internal API prototypes, but _not_ as doxygen tags/markup. Note these functions are internal use, not part of the public API, and are not necessarily intended to be stable across OSAL releases like the public API is. - Removed stray prototypes for functions where there was no actual definition/implementation.
|
Suggest adding OS_TimerSet note about cancelling with OS_TimerDelete. |
skliper
approved these changes
Sep 24, 2019
This was referenced Jan 22, 2020
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Describe the contribution
Fix #17
Update inline block comments in function/file headers across all of OSAL and ensure consistency with the code itself.
All documentation covering the specific details, inputs/outputs
and return values should be on the function declaration, not the
definition.
The definition should also contain a block comment for visual
distinction in the source file, but should be brief and refer
back to the prototype/declaration for detail. Any detail information
that was indicated only with the definition is moved to the
declaration.
Add doxygen tags/markup to external/public API block comments
and expand the descriptions of these functions where needed.
Add block comments to the internal API prototypes, but not
as doxygen tags/markup. Note these functions are internal use,
not part of the public API, and are not necessarily intended
to be stable across OSAL releases like the public API is.
Removed stray prototypes for functions where there was no
actual definition/implementation.
NOTE: All changes are primarily confined to comments, except where unused/unimplemented prototypes were removed.
Testing performed
Rebuilt CFE/OSAL per default config, with unit test enabled. Confirm build as successful and unit tests execute.
Expected behavior changes
No impact to behavior
System(s) tested on:
Ubuntu 18.04 (64-bit)
Contributor Info
Joseph Hickey, Vantage Systems, Inc.