Inline documentation on OSAL routines is incorrect/outdated in many places #17
Comments
jphickey
added a commit
to jphickey/osal
that referenced
this issue
Sep 18, 2019
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.
skliper
added a commit
that referenced
this issue
Oct 1, 2019
Fix #17: Update function description blocks across OSAL
skliper
pushed a commit
that referenced
this issue
Oct 1, 2019
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.
skliper
added a commit
that referenced
this issue
Oct 1, 2019
Reviewed and approved at 2019-09-25 CCB
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Describe the bug
The comments in the function headers of many of the OSAL calls have become outdated and incorrect.
To Reproduce
N/A. This reflects source code comments only. Most evident on the "implementation" files which copied the comment block from the external function call.
Expected behavior
Comment blocks should better reflect reality of what the code does. The "real" comment block that describes the function should reside with the function prototype. The definition should also have a comment block but primarily for visual differentiation in the source code. This block should not re-describe the function, as this results in multiple copies of the same description and thus could become stale/divergent again.
Reporter Info
Joseph Hickey, Vantage Systems, Inc.
The text was updated successfully, but these errors were encountered: