It warns for for comments like
/** \pre \em */
where \em has no argument
This warning is enabled with the -Wdocumentation option.
Differential D64696
Adds a warning when an inline Doxygen comment has no argument Mordante on Jul 13 2019, 9:04 AM. Authored by
Details It warns for for comments like where \em has no argument This warning is enabled with the -Wdocumentation option.
Diff Detail
Event TimelineComment Actions All inline commands defined in include/clang/AST/CommentCommands.td require an argument. The escape commands, like \&, are handled in the switch starting at lib/AST/CommentLexer.cpp:366. They are stored as Text and not as an InlineCommand. If you want I can add an extra field in the Command class in include/clang/AST/CommentCommands.td. Something like bit IsEmptyInlineCommandAllowed = 0;. Comment Actions Thank you! Do you have commit access or would you like me to commit this patch for you? Comment Actions Thanks for the review. I don't have commit access. So yes please commit the patch for me. Comment Actions Hello – This change seems to have exposed a bug in -Wdocumentation argument parsing. For example, this warns when it shouldn't(?): /// \c @foobar Comment Actions I think it should warn; according to the documentation [1] \c expects a word. Testing with Doxygen indeed gives a warning. Can you post the real comment where this occurs? Comment Actions From the Swift language source (http://github.com/apple/swift): include/swift/AST/Attr.h:/ A limited variant of \c @objc that's used for classes with generic ancestry. Comment Actions Unfortunately I'm not able to quickly find the Doxygen output of Swift online. When I process: Can you verify whether the Doxygen output for the Swift documentation is correct without escaping the \c @foo ? Or do you have a link to the online version? Comment Actions I don't think anybody is running doxygen over the Swift source right now, so I'll just escape the @ sign. That being said, can we improve this diagnostic? "command does not have an argument" is confusing when a given command does have an argument, just a malformed one. What do you think about "command must precede a word"? At least that gives a hint that the argument is not a "word" according to doxygen. |