Task #3199
closed
Enable clang's -Wdocumentation
30%
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.
Updated by Davide Pesavento over 8 years ago
- Status changed from New to Code review
- % Done changed from 0 to 90
Updated by Junxiao Shi over 8 years ago
"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?
Updated by Davide Pesavento over 8 years ago
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
-Wdocumentationcould 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.
Updated by Alex Afanasyev over 8 years ago
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.
Updated by Davide Pesavento over 8 years ago
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...
Updated by Davide Pesavento over 8 years ago
- 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".
Updated by Alex Afanasyev over 8 years ago
- Related to Task #3210: Fix doxygen errors and enable strict documentation check in Jenkins CI added
Updated by Alex Afanasyev over 8 years ago
- Status changed from Code review to Rejected