COMP: Fix the WDocumentation warnings for enum class. #4661
Conversation
github-actions
bot
added
type:Compiler
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Thank you for contributing a pull request! 🙏
Welcome to the ITK community! 🤗👋☀️
We are glad you are here and appreciate your contribution. Please keep in mind our community participation guidelines. 📜
More support and guidance on the contribution process can be found in our contributing guide. 📖
This is an automatic message. Allow for time for the ITK community to be able to read the pull request and comment
on it.
|
@dzenanz @hjmjohnson @N-Dekker : @andrei-sandor is a student working with me this summer, and he's going to take a stab at fixing some warnings in ITK with the goal of being able to enable a few more warning flags on our nightly submissions to cdash. |
|
Thanks @andrei-sandor ! Cool! I'm interested to hear if these changes will affect the Doxygen output, for example at https://itk.org/Doxygen/html/classitk_1_1CommonEnums.html The proposed changes look fine to me, but they caused some (undeserved) KWStyle errors. Looking at https://open.cdash.org/tests/1552684315
Probably coming from https://github.com/Kitware/KWStyle/blob/6971e89ec4c763601edf1d0ea0d6f71d42fbca5d/kwsCheckComments.cxx#L203 Do you (or anyone) know how to address those as well? |
|
Maybe this condition needs to be updated to consider |
| * \class CellGeometry | ||
| * \enum CellGeometry | ||
| * \ingroup ITKCommon | ||
| * Enums used to specify cell type */ | ||
| enum class CellGeometry : uint8_t |
There was a problem hiding this comment.
Ideally I think Doxygen should be able to automatically "defer" that CellGeometry is an enum, just by looking at the code. So then the whole line saying * \... CellGeometry might simply be removed. But that may be beyond the scope of this pull request, so for now replacing \class with \enum looks fine to me.
There was a problem hiding this comment.
Indeed. We could do this instead. But it would be a massive change touching many files.
Is there some reason ITK is explicitly using \class? Did someone think it was required? Is it a stylistic preference to be explicit? Or...?
There was a problem hiding this comment.
If it works, that's fine with me.
There was a problem hiding this comment.
After removing the \enum, the following warning is produced Modules/Core/Common/include/itkFloatingPointExceptions.h:37: error: comment doesn't have \class. What are the possible options? Should a modification be done like here style overwrite rules? Or maybe here this condition (adding an enum might be more complex)?
There was a problem hiding this comment.
Anyone have any thoughts on how should we proceed?
There was a problem hiding this comment.
@andrei-sandor @seanm I think a style overwrite rule is appropriate in this case.
Thank you for your continued contributions 🙏
There was a problem hiding this comment.
Is there a way to run KWStyle locally on all ITK files, from our local computers? (So that we don't have to depend on github CI.)
andrei-sandor
force-pushed
the
WdocTrivial
branch
from
4cf3788
to
730dcde
Compare
Removed the \enum doxygen comments to let doxygen figure it out by itself. KWStyle is applied to these files
andrei-sandor
force-pushed
the
WdocTrivial
branch
2 times, most recently
from
0d7394f
to
546aa73
Compare
andrei-sandor
force-pushed
the
WdocTrivial
branch
from
546aa73
to
5eac570
Compare
| @@ -33,3 +33,14 @@ itkMultiThreaderBase.h Comments Disable | |||
| itkSingleton\.cxx Namespace Disable | |||
| itkExceptionObject\.h IfNDefDefine Disable | |||
| itkConceptChecking\.h Template Disable | |||
| itkCommonEnums\.h Comments Disable | |||
There was a problem hiding this comment.
Thanks for your great work! Do I understand correctly that Comments Disable might as well just be applied to each and every source file? Because it just isn't a useful warning anyway?
There was a problem hiding this comment.
@thewtex and @blowekamp might have some comments about this.
There was a problem hiding this comment.
The use of \class ClassName was a style decision, I believe. We could add these Comments Disable for the enum class files. Or, we could change our style, but we probably want to do it consistently throughout and then disable the option globally with the KWStyle rules:
ITK/Utilities/KWStyle/ITK.kws.xml
Line 12 in 6861944
|
Should this be merged, or reviewed by someone else too? |
|
I think it's ready to merge, but I personally don't know much about the KWStyle suppression stuff... |
Used with clang
Replaced \class Doxygen annotations with \enum to avoid warnings