Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Harmonise Doxygen comments in drivers, events, platform and rtos dirs #11437

Merged
merged 1 commit into from Sep 10, 2019
Merged

Harmonise Doxygen comments in drivers, events, platform and rtos dirs #11437

merged 1 commit into from Sep 10, 2019

Conversation

hugueskamba
Copy link
Collaborator

@hugueskamba hugueskamba commented Sep 6, 2019 •
edited

Description

When a Doxygen group has been defined (created), all is needed to add
documentation to that group is \addtogroup. Since all the information
about the group is preserved, it is not necessary to mention the group
hierarchy again with \ingroup. This PR removes unnecessary Doxygen lines
across the drivers, events, platform and rtos directories.

It also ensures that new groups are created with \defgroup once and
referenced with \addtogroup whenever documentation needs to be added to
an existing group.

Pull request type

[ ] Fix
[ ] Refactor
[ ] Target update
[ ] Functionality change
[X] Docs update
[ ] Test update
[ ] Breaking change

Reviewers

@evedon @gpsimenos

Release Notes

This PR also correctly puts the MIDIMessage class documentation in /Internal API/Drivers/USB/ instead of /

@hugueskamba
Copy link
Collaborator Author

I am not quite sure why the doxy-spellcheck test fails on the CI as it passes locally:

hugkam01 at <host-name> in ~/projects/mbed-os-projects/mbed-os on hk-harmonize-doxygen-grouping [$]
$ ./tools/test/travis-ci/doxy-spellchecker/spell.sh rtos
rtos/ConditionVariable.h
rtos/Semaphore.h
rtos/Mail.h
rtos/mbed_rtos_types.h
rtos/mbed_rtos_storage.h
rtos/Thread.h
rtos/Queue.h
rtos/MemoryPool.h
rtos/Mutex.h
rtos/EventFlags.h
rtos/RtosTimer.h
rtos/rtos.h
rtos/source/rtos_handlers.h
rtos/source/rtos_idle.h
rtos/ThisThread.h
rtos/Kernel.h
rtos/mbed_rtos1_types.h
----------------------------------------------------------------------------------
Total Errors Found: 0

@ciarmcom ciarmcom requested a review from evedon September 7, 2019 01:00
@ciarmcom
Copy link
Member

ciarmcom commented Sep 7, 2019

@hugueskamba, thank you for your changes.
@gpsimenos @evedon @ARMmbed/mbed-os-core @ARMmbed/mbed-os-maintainers please review.

@ciarmcom ciarmcom requested review from gpsimenos and a team September 7, 2019 01:00
@hugueskamba hugueskamba changed the title Harmonise Doxygen comments in drivers, events and rtos dirs Harmonise Doxygen comments in drivers, events, platform and rtos dirs Sep 7, 2019
@0xc0170
Copy link
Contributor

0xc0170 commented Sep 9, 2019

travis-ci/doxy-spellcheck — Test failed.

Are the errors valid in the Travis? If yes, please fix

@hugueskamba
Harmonise Doxygen comments in drivers, events, platform and rtos dirs
5933dec 
When a Doxygen group has been defined (created), all its needed to add
documentation to that group is `\addtogroup`. Since all the information
about the group is preserved, it is not necessary to mention the group
hierarchy again with `\ingroup`. This PR removes unnecessary Doxygen lines
across the `drivers`, `events`, `platform` and `rtos` directories.

It also ensures that new groups are created with `\defgroup` once and
referenced with `\addtogroup` whenever documentation needs to be added to
an existing group.
@hugueskamba
Copy link
Collaborator Author

This force-push adds the word api in the list of words to ignore by the doxy-spellchecker script in an attempt to solve the CI error.

@0xc0170
Copy link
Contributor

0xc0170 commented Sep 9, 2019

How does doxygen (tree) looks like before and after this change = to illustrate what changes are done here - or is it the same just not required symbols removed? I think the former is true.

@hugueskamba
Copy link
Collaborator Author

How does doxygen (tree) looks like before and after this change = to illustrate what changes are done here - or is it the same just not required symbols removed? I think the former is true.

The tree looks exactly the same.

evedon
evedon approved these changes Sep 9, 2019
View reviewed changes
Copy link
Contributor

@evedon evedon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Manually checked the generated doxygen

@0xc0170
Copy link
Contributor

0xc0170 commented Sep 9, 2019

CI started

@mbed-ci
Copy link

mbed-ci commented Sep 9, 2019

Test run: SUCCESS

Summary: 11 of 11 test jobs passed
Build number : 1
Build artifacts

@0xc0170 0xc0170 merged commit 0f1962e into ARMmbed:master Sep 10, 2019
@hugueskamba hugueskamba deleted the hk-harmonize-doxygen-grouping branch November 18, 2019 15:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@0xc0170 0xc0170 0xc0170 approved these changes

@evedon evedon evedon approved these changes

@gpsimenos gpsimenos Awaiting requested review from gpsimenos

@AnotherButler AnotherButler Awaiting requested review from AnotherButler

Assignees
No one assigned
Labels
release-version: 5.14.1
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
5 participants
@hugueskamba @ciarmcom @0xc0170 @mbed-ci @evedon