-
Notifications
You must be signed in to change notification settings - Fork 3k
Include doxygen from test directories #5238
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Include doxygen from test directories #5238
Conversation
Turn on doxygen for tests. This allows testing functions to be referenced, which will be used for various parts of the HAL specification.
/morph test |
Result: ABORTEDYour command has finished executing! Here's what you wrote!
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't really agree nor see any benefit of referencing test cases from Doxygen.
Might generate really messy documentation.
The end result of proper API testing would be that there is two to ten times more tests than functions in the API. Why would be actually want bulk of our documentation to be just test functions.
Also, test functions might not make any sense without actually knowing the test strategy or test plan. (Those are not yet public)
Hi @SeppoTakalo, the HAL specification documents the defined behavior of each HAL API. This is backed by tests which ensure each implementation of the API meets these defined behaviors. By referencing the the tests which validate this behavior, there is a traceable connection between the high level defined behavior and how this behavior is guarenteed. Referencing specific test functions should add minimal additional information and add the benefit of traceability. Furthermore, CI checks the doxygen so if one of the specification tests is removed or renamed, CI testing will fail unless the specification doxygen is also updated in sync with the code. For reference, below is this change used to document the RTC specification. Do you still have concerns with the amount of documentation, and if so do you think this outweights the benefits mentioned above? RTC Specification documentation: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I changed my mind as Russ explained that leaving test code undocumented would not cause any build failures and is the correct way to hide them from Doxygen.
/morph test |
Result: SUCCESSYour command has finished executing! Here's what you wrote!
OutputAll builds and test passed! |
Thanks @SeppoTakalo The last call for reviews |
Turn on doxygen for tests. This allows testing functions to be referenced, which will be used for various parts of the HAL specification.