-Wdocumentation should ignore period after \param.

[JDevlieghere]

Bugzilla Link	47263
Version	unspecified
OS	All
CC	@gribozavr,@zygoloid

Extended Description

Consider the following example:

/// Sentence that ends with \param bar.
int foo(int bar) { }

When compiled with -Wdocumentation this results in warning:

$ clang -c -Wdocumentation /tmp/repro.c
/tmp/repro.c:1:39: warning: empty paragraph passed to '\param' command [-Wdocumentation]
/// Sentence that ends with \param bar.
                            ~~~~~~~~~~^
/tmp/repro.c:1:36: warning: parameter 'bar.' not found in the function declaration [-Wdocumentation]
/// Sentence that ends with \param bar.
                                   ^~~~
/tmp/repro.c:1:36: note: did you mean 'bar'?
/// Sentence that ends with \param bar.
                                   ^~~~
                                   bar

This is silly and particularly annoying for projects such as LLVM that require comments to be sentences terminated with a period.

[JDevlieghere]

Looking at the code there's two (obvious) ways to fix this:

1. We rtrim('.') the ParamName in CommentSema.cpp:754.
2. We exclude periods from the ParamCommandComment.

I feel like the second approach would be more canonical, but also more invasive. Before deciding on a solution I'd like to get some input from someone more familiar with this code.

[zygoloid]

\param is used to document parameters. To refer to a parameter, you should use \p instead. See:

https://www.doxygen.nl/manual/commands.html#cmdparam
https://www.doxygen.nl/manual/commands.html#cmdp

The warning is correct; your documentation is wrong.

Perhaps we should detect the case of a \param not at the start of a line and suggest that \p may have been intended instead?