Skip to content

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

Merged
merged 1 commit into from
Oct 9, 2017

Conversation

c1728p9
Copy link
Contributor

@c1728p9 c1728p9 commented Oct 2, 2017

Turn on doxygen for tests. This allows testing functions to be referenced, which will be used for various parts of the HAL specification.

Turn on doxygen for tests. This allows testing functions to be
referenced, which will be used for various parts of the HAL
specification.
@c1728p9
Copy link
Contributor Author

c1728p9 commented Oct 2, 2017

/morph test

@c1728p9 c1728p9 mentioned this pull request Oct 2, 2017
@mbed-bot
Copy link

mbed-bot commented Oct 3, 2017

Result: ABORTED

Your command has finished executing! Here's what you wrote!

/morph test

Copy link
Contributor

@SeppoTakalo SeppoTakalo left a 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)

@c1728p9
Copy link
Contributor Author

c1728p9 commented Oct 4, 2017

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:

doxygen

Copy link
Contributor

@SeppoTakalo SeppoTakalo left a 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.

@c1728p9
Copy link
Contributor Author

c1728p9 commented Oct 5, 2017

/morph test

@mbed-bot
Copy link

mbed-bot commented Oct 5, 2017

Result: SUCCESS

Your command has finished executing! Here's what you wrote!

/morph test

Output

mbed Build Number: 1530

All builds and test passed!

@0xc0170
Copy link
Contributor

0xc0170 commented Oct 6, 2017

Thanks @SeppoTakalo

The last call for reviews

@pan- @maciejbocianski @mprse @fkjagodzinski

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants