llvm / llvm/llvm-project

[clang-doc] Certain comment types should be single paragraphs

Open
#169,006 1 comment 0 reactions 0 assignees View on GitHub
clang-doc
Dominant language
LLVM
Stars
40.5k
Forks
18.7k
PR merge metrics
PR metrics pending

Description

Certain Doxygen special commands are concatenated regardless of the order they're written. For example:
```
/// \return Foo
/// \brief Brief!
/// \return Bar
```
will look like:
```
*Return*
Foo
Bar
```
See [the return special command](https://www.doxygen.nl/manual/commands.html#cmdreturn). Currently, the JSON backend treats these as separate comment paragraphs, and the JSON looks like the following:
```
"ReturnComments": [
[
"TextComment": "Foo"
],
[
"TextComment": "Bar
]
]
```
This JSON should be emitted as a single array.

Contributor guide

Open the contributing guide

Research direction

Start by locating clang-doc's JSON backend and its tests for repeated Doxygen special commands. Compare the current output for repeated return comments with the expected single array, then add or update a regression test; done means the comments are emitted as one array while preserving their text order.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, json
Domain
documentation, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.