tools/doccheck: extend script to also check for Doxygen groups defined multiple times

[aabadie]

Contribution description

While reworking #8939, I noticed several nucleo boards were having their Doxygen groups (e.g. boards_nucleo-xxx) defined in doc.txt and periph_conf.h.

After looking into it a bit more, it appears that some other Doxygen groups, in different parts of the code, have the same problem.

The idea of this PR is to extend the doccheck script to also check groups that are defined multiple times and to return the number of times and files where the groups are defined.

For the moment, the script doesn't exit with a return code != 0 in case of problem but simply prints the problematic groups with a warning. So it can be merged without bad consequences on static tests.

Previous checks still work (according to my local tests).

I'll open another PR with all reported doxygen group fixed and a change to make the script return an error if one or several groups are defined multiple times.

Testing procedure

• Run make static-test and check the output
• Verify the listed groups are indeed problematic
• CI should not fail

Issues/PRs references

The PR containing all the fixes will arrive soon. All problems found are fixed by #11814

[cladmi]

No ideas about how doxygen groups should be handled.

[aabadie]

Thanks for having a first look @cladmi.

No ideas about how doxygen groups should be handled.

I tend to think that there should only one call to defgroup for a given group, even if Doxygen doesn't raise a warning when there are duplicate defgroup.

Your previous comments should be addressed now. I reworked a bit the initial version of this PR following them.

[miri64]

Please rebase and squash so I can have another look with #11814 merged.

[aabadie]

Done

[aabadie]

Do they have to be counted?

If you think it's not needed, then i'm fine with removing the counts. It will simplify quite a few this PR (it was a nightmare to make it work correctly with the counts ;) ).

[miri64]

Do they have to be counted?

If you think it's not needed, then i'm fine with removing the counts. It will simplify quite a few this PR (it was a nightmare to make it work correctly with the counts ;) ).

I always prefer exact numbers over no numbers, however in this case I don't think they justify the code complexity that is introduced here ;-).

[aabadie]

@miri64. I reworked the script like you suggested in a fixup commit. I added a second commit with the same print improvement for undefined groups (only compute the list of groups and files if there are undefined groups found).

[miri64]

:-)

[miri64]

Will look into it in detail and test tomorrow.

[miri64]

ACK. If I execute dist/tools/doccheck/check.sh on the branch of this PR as is, I get no error output.

If I revert e.g. bd816f3 from #11814, I get

ERROR There are 1 Doxygen groups defined multiple times:

pkg_lwip defined in:
	pkg/lwip/doc.txt
	pkg/lwip/include/lwip.h

[aabadie]

@miri64, merge ?

[miri64]

Yepp, sorry, lost track.