### Background
Doxygen's `\par` command
([link](https://www.doxygen.nl/manual/commands.html#cmdpar)) has an
optional argument, which denotes the header of the paragraph started by
a given `\par` command.
In short, the paragraph command can be used with a heading, or without
one. The code block below shows both forms and how the current version
of LLVM/Clang parses this code:
```
$ cat test.cpp
/// \par User defined paragraph:
/// Contents of the paragraph.
///
/// \par
/// New paragraph under the same heading.
///
/// \par
/// A second paragraph.
class A {};
$ clang++ -cc1 -ast-dump -fcolor-diagnostics -std=c++20 test.cpp
`-CXXRecordDecl 0x1530f3a78 <test.cpp:11:1, col:10> col:7 class A definition
|-FullComment 0x1530fea38 <line:2:4, line:9:23>
| |-ParagraphComment 0x1530fe7e0 <line:2:4>
| | `-TextComment 0x1530fe7b8 <col:4> Text=" "
| |-BlockCommandComment 0x1530fe800 <col:5, line:3:30> Name="par"
| | `-ParagraphComment 0x1530fe878 <line:2:9, line:3:30>
| | |-TextComment 0x1530fe828 <line:2:9, col:32> Text=" User defined paragraph:"
| | `-TextComment 0x1530fe848 <line:3:4, col:30> Text=" Contents of the paragraph."
| |-ParagraphComment 0x1530fe8c0 <line:5:4>
| | `-TextComment 0x1530fe898 <col:4> Text=" "
| |-BlockCommandComment 0x1530fe8e0 <col:5, line:6:41> Name="par"
| | `-ParagraphComment 0x1530fe930 <col:4, col:41>
| | `-TextComment 0x1530fe908 <col:4, col:41> Text=" New paragraph under the same heading."
| |-ParagraphComment 0x1530fe978 <line:8:4>
| | `-TextComment 0x1530fe950 <col:4> Text=" "
| `-BlockCommandComment 0x1530fe998 <col:5, line:9:23> Name="par"
| `-ParagraphComment 0x1530fe9e8 <col:4, col:23>
| `-TextComment 0x1530fe9c0 <col:4, col:23> Text=" A second paragraph."
`-CXXRecordDecl 0x1530f3bb0 <line:11:1, col:7> col:7 implicit class A
```
As we can see above, the optional paragraph heading (`"User defined
paragraph"`) is not an argument of the `\par` `BlockCommandComment`, but
instead a child `TextComment`.
For documentation generators like [hdoc](https://hdoc.io/), it would be
ideal if we could parse Doxygen documentation comments with these
semantics in mind. Currently that's not possible.
### Change
This change parses `\par` command according to how Doxygen parses them,
making an optional header available as a an argument if it is present.
In addition:
- AST unit tests are defined to test this functionality when an argument
is present, isn't present, with additional spacing, etc.
- TableGen is updated with an `IsParCommand` to support this
functionality
- `lit` tests are updated where needed
These should be all the commands from [1] except those that are marked
obsolete, and "link" / "endlink", as that conflicts with the existing
HeaderDoc pair "link / "/link". For some commands we don't have the
ideal category, but it should work good enough for most cases.
There seems to be no existing test for most commands (except the ones
interpreted by -Wdocumentation), and to some extent such a test wouldn't
look very interesting. But I added a test for the correct parsing of
formulas, as they're a bit special. And I had to adapt
comment-lots-of-unknown-commands.c because typo correction was kicking
in and recognizing some of the commands.
This should fix a couple of reported bugs: PR17437, PR19581, PR24062
(partially, no diagnostic for matching cond/endcond), PR32909, PR37813,
PR44243 (partially, email@domain.com must be addressed separately).
[1] https://www.doxygen.nl/manual/commands.html
Reviewed By: gribozavr2
Differential Revision: https://reviews.llvm.org/D111190
This is how it should've been and brings it more in line with
std::string_view. There should be no functional change here.
This is mostly mechanical from a custom clang-tidy check, with a lot of
manual fixups. It uncovers a lot of minor inefficiencies.
This doesn't actually modify StringRef yet, I'll do that in a follow-up.
to reflect the new license.
We understand that people may be surprised that we're moving the header
entirely to discuss the new license. We checked this carefully with the
Foundation's lawyer and we believe this is the correct approach.
Essentially, all code in the project is now made available by the LLVM
project under our new license, so you will see that the license headers
include that license only. Some of our contributors have contributed
code under our old license, and accordingly, we have retained a copy of
our old license notice in the top-level files in each project and
repository.
llvm-svn: 351636
If the type isn't trivially moveable emplace can skip a potentially
expensive move. It also saves a couple of characters.
Call sites were found with the ASTMatcher + some semi-automated cleanup.
memberCallExpr(
argumentCountIs(1), callee(methodDecl(hasName("push_back"))),
on(hasType(recordDecl(has(namedDecl(hasName("emplace_back")))))),
hasArgument(0, bindTemporaryExpr(
hasType(recordDecl(hasNonTrivialDestructor())),
has(constructExpr()))),
unless(isInTemplateInstantiation()))
No functional change intended.
llvm-svn: 238601
This change introduces a 'kind' attribute for the <Para> tag, that captures the
kind of the parent block command.
For example:
\todo Meow.
used to be just <Para>Meow.</Para>, but now it is
<Para kind="todo">Meow.</Para>
llvm-svn: 174216
deprecation attribute ('deprecated', 'availability' or 'unavailable').
This warning is under a separate flag, -Wdocumentation-deprecated-sync, so it
can be turned off easily while leaving other -Wdocumentation warnings on.
llvm-svn: 164467
should be fine to use it without further explanations in the attached
paragraph, so the warning about empty paragraph was turned off for it.
llvm-svn: 163836
Now we have a list of all commands. This is a good thing in itself, but it
also enables us to easily implement typo correction for command names.
With this change we have objects that contain information about each command,
so it makes sense to resolve command name just once during lexing (currently we
store command names as strings and do a linear search every time some property
value is needed). Thus comment token and AST nodes were changed to contain a
command ID -- index into a tables of builtin and registered commands. Unknown
commands are registered during parsing and thus are also uniformly assigned an
ID. Using an ID instead of a StringRef is also a nice memory optimization
since ID is a small integer that fits into a common bitfield in Comment class.
This change implies that to get any information about a command (even a command
name) we need a CommandTraits object to resolve the command ID to CommandInfo*.
Currently a fresh temporary CommandTraits object is created whenever it is
needed since it does not have any state. But with this change it has state --
new commands can be registered, so a CommandTraits object was added to
ASTContext.
Also, in libclang CXComment has to be expanded to include a CXTranslationUnit
so that all functions working on comment AST nodes can get a CommandTraits
object. This breaks binary compatibility of CXComment APIs.
Now clang_FullComment_getAsXML(CXTranslationUnit TU, CXComment CXC) doesn't
need TU parameter anymore, so it was removed. This is a source-incompatible
change for this C API.
llvm-svn: 163540
