search

ARMmbed / mbed-crypto

The development of Mbed Crypto has moved to Mbed TLS. No updates will be made to the mbed-crypto repository anymore.
Apache License 2.0
104 stars 97 forks source link

Doxygen misses "end group" markup (\}) in multiple .h files #356

Closed tomlogic closed 4 years ago

tomlogic commented 4 years ago

https://github.com/ARMmbed/mbed-crypto/blob/819799cfc68e4c4381673a8a27af19802c8263f2/include/mbedtls/ctr_drbg.h#L139

This is just one example, but I noticed Doxygen failing to parse some comments in mbedtls files included in my project, and leaving the "group" open. I was able to fix this by updating those comments to start with /** instead of /* as follows:

-/* \} name SECTION: Module settings */
+/** \} name SECTION: Module settings */

It might be a good idea to look for that pattern and fix it throughout the repository in a single commit. Unless you're using something other than Doxygen to generate documentation, or perhaps some configuration options that I wasn't using in my doxyconfig.

ciarmcom commented 4 years ago

Internal Jira reference: https://jira.arm.com/browse/IOTCRYPT-1043

mpg commented 4 years ago

Thanks for your report! This looks like a bug indeed, but can you clarify how it shows (in the generated output, or output of the doxygen command) that the end-of-section markers are not closed?

Note: we have a script, tests/scripts/check-doxy-blocks.pl, which is precisely intended to "Detect comment blocks that are likely meant to be doxygen blocks but aren't" but is clearly not catching this, we probably want to fix/extend that script as well.

tomlogic commented 4 years ago

Here's the output of my Doxygen run, with the paths truncated. That's what turned me on to the problem originally, as I was fixing Doxygen markup in my main project (that includes some of mbedtls).

.../include/mbedtls/ctr_drbg.h:381: warning: end of file with unbalanced grouping commands
.../include/mbedtls/entropy.h:290: warning: end of file with unbalanced grouping commands
.../include/mbedtls/platform.h:420: warning: end of file with unbalanced grouping commands
mpg commented 4 years ago

Thanks!

Ok, so there must but some difference between your project's and ours, or our versions of doxygen, because we're not seeing this warning (as evidence by the fact that tests/scripts/doxygen.sh passes). (I tried locally with doxygen 1.8.11, and I think our CI is using the same version.)

Anyway, this is a bug and it needs fixing. It would be ideal to know how to reproduce the warning so that we can avoid regressions in the future, but even without that we can fix the bug.

tomlogic commented 4 years ago

I was seeing the warning with 1.8.16 and 1.8.17.

Here's the project's Doxyfile: https://github.com/digidotcom/xbee_ansic_library/blob/master/Doxyfile

mpg commented 4 years ago

Thanks for the info! I was able to test with doxygen 1.8.17 and got the same warnings (and several others actually).

For reference, here's the list of unique warnings and their number of occurrences, obtained with tests/scripts/doxygen.sh | sed -e 's/.*warning://' -e "s/PSA_[^']*/PSA_XXX/" -e 's/psa_[^ ]*/psa_xxx/' | sort | uniq -c:

I suggest we keep this issue about the grouping warnings in mbed-crypto ("end of file while inside a group" and "end of file with unbalanced grouping commands"), and I'll open other issues for the other types of warnings. Edit: see #359 and #360.

Thanks again for reporting the issue and providing information allowing us to reproduce it!

mpg commented 4 years ago

Let's continue this in ARMmbed/mbedtls#3497