Clang warning: empty paragraph passed to '...B' command [-Wdocumentation] (warn_doc_block_command_empty_paragraph)

Text	error: empty paragraph passed to ' \ @ B' command
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

The warning is issued by the Clang compiler when a documentation comment contains an empty paragraph that is supposed to provide information for a specific documentation command, marked with either a backslash (\) or an at-symbol (@). This situation arises in the context of comments intended to be processed by documentation tools to generate external documentation from the source code. Specifically, an empty paragraph is identified when there is a lack of content following a command which expects textual information, such as @param or \brief. The compiler flags this as a warning under the -Wdocumentation option, indicating a potential issue in the documentation comment that might lead to incomplete or missing information in the generated documentation. This warning serves as a reminder to review and ensure that all intended descriptions or details are properly included in the documentation comments, adhering to best practices for maintaining clear and comprehensive code documentation.

AI Generated

Example

In the following example, a function is defined with a documentation comment above it that uses the @param command. However, the command is followed by an empty space instead of the expected description of the function's parameter. This lack of description triggers the warning, as the documentation generator expects the @param command to be accompanied by an explanation for the parameter. The example illustrates how the compiler identifies and warns about the absence of necessary information in documentation comments that use specific commands expecting subsequent descriptive text.

AI Generated

Flags	-Wdocumentation -xc++	[Try out in Compiler Explorer]
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]