Clang warning: empty paragraph passed to '...B' command [-Wdocumentation] (warn_doc_block_command_empty_paragraph)
Jump to navigation
Jump to search
Text |
| ||||||
---|---|---|---|---|---|---|---|
Type | Warning | ||||||
Category | Documentation Issue | ||||||
Internal Id | warn_doc_block_command_empty_paragraph | ||||||
Active by Default | No | ||||||
Flags | -Wdocumentation (25 elements) | ||||||
Internal Message | empty paragraph passed to '%select{\|@}0%1' command
| ||||||
Regular Expression | (?:warning|error|fatal error)\: empty paragraph passed to '(?:\\|@)(.*?)' command \[(?:\-Werror,)?\-Wdocumentation[^\]]*\]
| ||||||
First Commit | 2012-07-11 f26054f0fb53 Enable comment parsing and semantic analysis to emit diagnostics. A few |
Description
Example
Flags | -Wdocumentation -xc++
|
|
---|---|---|
Source |
/** @param */
void f() {}
| |
Compiler Output |
<source>:1:11: warning: empty paragraph passed to '@param' command [-Wdocumentation] |
Clang Internals (17.0.6)
Git Commit Message
Enable comment parsing and semantic analysis to emit diagnostics. A few diagnostics implemented -- see testcases. I created a new TableGen file for comment diagnostics, DiagnosticCommentKinds.td, because comment diagnostics don't logically fit into AST diagnostics file. But I don't feel strongly about it. This also implements support for self-closing HTML tags in comment lexer and parser (for example,
). In order to issue precise diagnostics CommentSema needs to know the declaration the comment is attached to. There is no easy way to find a decl by comment, so we match comments and decls in lockstep: after parsing one declgroup we check if we have any new, not yet attached comments. If we do -- then we do the usual comment-finding process. It is interesting that this automatically handles trailing comments. We pick up not only comments that precede the declaration, but also comments that *follow* the declaration -- thanks to the lookahead in the lexer: after parsing the declgroup we've consumed the semicolon and looked ahead through comments. Added -Wdocumentation-html flag for semantic HTML errors to allow the user to disable only HTML warnings (but not HTML parse errors, which we emit as warnings in -Wdocumentation). llvm-svn: 160078
Used in Clang Sources
This section lists all occurrences of the diagnostic within the Clang's codebase. For each occurrence, an auto-extracted snipped from the source code is listed including key elements like control structures, functions, or classes. It should illustrate the conditions under which the diagnostic is activated.
clang/lib/AST/CommentSema.cpp (line 548)
void Sema::checkBlockCommandEmptyParagraph(BlockCommandComment *Command) {
// ...
if (Paragraph->isWhitespace()) {
// ...
Diag(DiagLoc, diag::warn_doc_block_command_empty_paragraph) << Command->getCommandMarker() << Command->getCommandName(Traits) << Command->getSourceRange();
Triggered in Clang Tests
This section lists all internal Clang test cases that trigger the diagnostic.
clang/test/Sema/warn-documentation-crlf.c
- clang/test/Sema/warn-documentation-crlf.c:10:13: warning: empty paragraph passed to '@param' command [-Wdocumentation]