[Clang][Comments] Support for parsing headers in Doxygen \par commands (#91100)

### Background

Doxygen's `\par` command
([link](https://www.doxygen.nl/manual/commands.html#cmdpar)) has an
optio

[Clang][Comments] Support for parsing headers in Doxygen \par commands (#91100)

### 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

show more ...

[Clang][Comments] Add argument parsing for @throw @throws @exception (#84726)

Doxygen allows for the `@throw`, `@throws`, and `@exception` commands to
have an attached argument indicating the type

[Clang][Comments] Add argument parsing for @throw @throws @exception (#84726)

Doxygen allows for the `@throw`, `@throws`, and `@exception` commands to
have an attached argument indicating the type being thrown. Currently,
Clang's AST parsing doesn't support parsing out this argument from doc
comments. The result is missing compatibility with Doxygen.

This PR implements parsing of arguments for the `@throw`, `@throws`, and
`@exception` commands. Each command can only have one argument, matching
the semantics of Doxygen.

show more ...

Add missing `llvm::to_underlying` in `AST/CommentParser.cpp` unit test

This fixed a test failure introduced in f2d8a0ac1dd1fe55b2c3b358c525fbc01b0121ed.

[clang][NFC] Refactor `ParamCommandComment::PassDirection`

This patch converts `ParamCommandComment::PassDirection` to a scoped enum at namespace scope, making it eligible for forward declaring. Thi

[clang][NFC] Refactor `ParamCommandComment::PassDirection`

This patch converts `ParamCommandComment::PassDirection` to a scoped enum at namespace scope, making it eligible for forward declaring. This is useful for e.g. annotating bit-fields with `preferred_type`.

show more ...

[clang] Use std::size instead of llvm::array_lengthof

LLVM contains a helpful function for getting the size of a C-style
array: `llvm::array_lengthof`. This is useful prior to C++17, but not as
help

[clang] Use std::size instead of llvm::array_lengthof

LLVM contains a helpful function for getting the size of a C-style
array: `llvm::array_lengthof`. This is useful prior to C++17, but not as
helpful for C++17 or later: `std::size` already has support for C-style
arrays.

Change call sites to use `std::size` instead. Leave the few call sites that
use a locally defined `array_lengthof` that are meant to test previous bugs
with NTTPs in clang analyzer and SemaTemplate.

Differential Revision: https://reviews.llvm.org/D133520

show more ...

Revert "Rename llvm::array_lengthof into llvm::size to match std::size from C++17"

This reverts commit ef8206320769ad31422a803a0d6de6077fd231d2.

- It conflicts with the existing llvm::size in STLEx

Revert "Rename llvm::array_lengthof into llvm::size to match std::size from C++17"

This reverts commit ef8206320769ad31422a803a0d6de6077fd231d2.

- It conflicts with the existing llvm::size in STLExtras, which will now
never be called.
- Calling it without llvm:: breaks C++17 compat

show more ...

Rename llvm::array_lengthof into llvm::size to match std::size from C++17

As a conquence move llvm::array_lengthof from STLExtras.h to
STLForwardCompat.h (which is included by STLExtras.h so no buil

Rename llvm::array_lengthof into llvm::size to match std::size from C++17

As a conquence move llvm::array_lengthof from STLExtras.h to
STLForwardCompat.h (which is included by STLExtras.h so no build
breakage expected).

show more ...

[AST] Fixed string list in test

[AST] Fixed string concatenation warnings

[clang][NFC] Store a pointer to the ASTContext in ASTDumper and TextNodeDumper

In general there is no way to get to the ASTContext from most AST nodes
(Decls are one of the exception). This will be

[clang][NFC] Store a pointer to the ASTContext in ASTDumper and TextNodeDumper

In general there is no way to get to the ASTContext from most AST nodes
(Decls are one of the exception). This will be a problem when implementing
the rest of APValue::dump since we need the ASTContext to dump some kinds of
APValues.

The ASTContext* in ASTDumper and TextNodeDumper is not always non-null.
This is because we still want to be able to use the various dump() functions
in a debugger.

No functional changes intended.

Reverted in fcf4d5e4499a391dff42ea1a096f146db44147b6 since a few dump()
functions in lldb where missed.

show more ...

Revert "[clang][NFC] Store a pointer to the ASTContext in ASTDumper and TextNodeDumper"

This reverts commit aa7fd905e4e1bc510448431da9310e8cf5197523.

I missed some dump() functions.

[clang][NFC] Store a pointer to the ASTContext in ASTDumper and TextNodeDumper

In general there is no way to get to the ASTContext from most AST nodes
(Decls are one of the exception). This will be

[clang][NFC] Store a pointer to the ASTContext in ASTDumper and TextNodeDumper

In general there is no way to get to the ASTContext from most AST nodes
(Decls are one of the exception). This will be a problem when implementing
the rest of APValue::dump since we need the ASTContext to dump some kinds of
APValues.

The ASTContext* in ASTDumper and TextNodeDumper is not always
non-null. This is because we still want to be able to use the various
dump() functions in a debugger.

No functional changes intended.

show more ...

[unittests][AST] CommentParser: don't name variable 'DEBUG'

It's may be an already-defined macro name,
resulting in compilation errors.

llvm-svn: 370650

Update the file headers across all of the LLVM projects in the monorepo
to reflect the new license.

We understand that people may be surprised that we're moving the header
entirely to discuss the ne

Update the file headers across all of the LLVM projects in the monorepo
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

show more ...

[NFC] Header cleanup

Summary: Removed unused headers, replaced some headers with forward class declarations

Patch by: Eugene <claprix@yandex.ru>

Differential Revision: https://reviews.llvm.org/D20

[NFC] Header cleanup

Summary: Removed unused headers, replaced some headers with forward class declarations

Patch by: Eugene <claprix@yandex.ru>

Differential Revision: https://reviews.llvm.org/D20100

llvm-svn: 275882

show more ...

unique_ptrify SourceManager::createFileID

llvm-svn: 216715

Update for LLVM api change.

llvm-svn: 216585

[C++11] Use 'nullptr'. Unittests edition.

llvm-svn: 210423

Rename SourceManager::createFileIDForMemBuffer()

It makes more sense to just overload createFileID().

Gardening only.

llvm-svn: 209002

Comment parsing: don't crash while parsing \deprecated in a standalone comment
(comment without a decl).

I think this can not happen during normal compilation with -Wdocumentation,
only while using

Comment parsing: don't crash while parsing \deprecated in a standalone comment
(comment without a decl).

I think this can not happen during normal compilation with -Wdocumentation,
only while using Clang APIs to parse comments outside of a source file.

Based on a patch by Olivier Goffart.

llvm-svn: 200230

show more ...

Comment parsing: fix a bug where a line with whitespace between two paragraphs
would cause us to concatenate these paragraphs into a single one.

The no-op whitespace churn in test/Index test happene

Comment parsing: fix a bug where a line with whitespace between two paragraphs
would cause us to concatenate these paragraphs into a single one.

The no-op whitespace churn in test/Index test happened because these tests
don't use the correct approach for testing and are more strict than required
for they are testing.

llvm-svn: 189126

show more ...

[Doc parsing] Provide diagnostics for unknown documentation
commands. // rdar://12381408

llvm-svn: 181071

Comment parsing: add CommentOptions to allow specifying custom comment block commands

Add an ability to specify custom documentation block comment commands via a new
class CommentOptions. The inten

Comment parsing: add CommentOptions to allow specifying custom comment block commands

Add an ability to specify custom documentation block comment commands via a new
class CommentOptions. The intention is that this class will hold future
customizations for comment parsing, including defining documentation comments
with specific numbers of parameters, etc.

CommentOptions instance is a member of LangOptions.

CommentOptions is controlled by a new command-line parameter
-fcomment-block-commands=Foo,Bar,Baz.

llvm-svn: 175892

show more ...

Really sort the #include lines in unittests/...

I forgot to re-sort after fixing main module headers.

llvm-svn: 169244

Sort the #include lines for unittests/...

I've tried to place sensible headers at the top as main-module headers.

llvm-svn: 169243