Task #3199
closed
Enable clang's -Wdocumentation
Added by Davide Pesavento over 8 years ago.
Updated over 8 years ago.
Description
Since version 3.2, clang supports a -Wdocumentation flag that enables parsing of doxygen-style comments and reporting of syntactic and semantic errors.
I propose to enable this flag by default (and fix all current warnings). This should improve the quality of our documentation.
- Status changed from New to Code review
- % Done changed from 0 to 90
"Clang now supports documentation comments written in a Doxygen-like syntax", but there's no guarantee that the support is exactly same as Doxygen, and therefore -Wdocumentation could cause false negatives.
Why not compile the documentation and emit warnings using Doxygen itself?
Junxiao Shi wrote:
"Clang now supports documentation comments written in a Doxygen-like syntax", but there's no guarantee that the support is exactly same as Doxygen, and therefore -Wdocumentation could cause false negatives.
Sure, but if that ever happens, it'll be for minor things... also doxygen syntax doesn't change every day...
Why not compile the documentation and emit warnings using Doxygen itself?
Well who did that so far? I bet nobody given the current state full of errors... That's the problem with optional things: they end up being ignored.
Why not compile the documentation and emit warnings using Doxygen itself?
Well who did that so far? I bet nobody given the current state full of errors... That's the problem with optional things: they end up being ignored.
What Junxiao meant is that we can set up Jenkins to build documentation and fail build if there are problems.
Alex Afanasyev wrote:
What Junxiao meant is that we can set up Jenkins to build documentation and fail build if there are problems.
Fine with me, but I will not implement such change. Btw, are you sure doxygen won't give false positive as well? From my past experience, doxygen is quite verbose and its C++ parser doesn't understand certain complicated constructs...
- Assignee deleted (
Davide Pesavento)
- Priority changed from Normal to Low
- Target version deleted (
v0.4)
- % Done changed from 90 to 30
I've amended http://gerrit.named-data.net/2442 to only fix doxygen errors.
Feel free to close this task if there's no interest, or keep it open as a reminder for "the future".
- Related to Task #3210: Fix doxygen errors and enable strict documentation check in Jenkins CI added
- Status changed from Code review to Rejected
Also available in: Atom
PDF
Updated by 
Updated by 
Updated by