Skip to content

Commit a3e2b64

Browse files
tcottinemaxx-google
tcottin
and
emaxx-google
authored
[clangd] extend and rearrange doxygen hover documentation (#152918)
This is the final patch to solve clangd/clangd#529. This uses the patches from [#140498](#140498) and [#150790](#150790) to improve the hover content for doxygen documented code. The patch uses the information from the parsed doxygen comment to extend and rearrange the hover documentation: - own section for brief, notes and warning documentation - for functions add parameter/template parameter documentation - for functions add return documentation Note: this requires to configure ```yaml Documentation: CommentFormat: Doxygen ``` in your `.clangd` configuration. --------- Co-authored-by: Maksim Ivanov <[email protected]>
1 parent a49df8e commit a3e2b64

File tree

11 files changed

+697
-125
lines changed

11 files changed

+697
-125
lines changed

‎clang-tools-extra/clangd/CodeComplete.cpp‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,9 @@ toCompletionItemKind(index::SymbolKind Kind,
9797
const llvm::StringRef *Signature = nullptr) {
9898
using SK = index::SymbolKind;
9999
switch (Kind) {
100+
// FIXME: for backwards compatibility, the include directive kind is treated
101+
// the same as Unknown
102+
case SK::IncludeDirective:
100103
case SK::Unknown:
101104
return CompletionItemKind::Missing;
102105
case SK::Module:

‎clang-tools-extra/clangd/CodeCompletionStrings.cpp‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ std::string getDeclComment(const ASTContext &Ctx, const NamedDecl &Decl) {
112112
std::string Doc;
113113

114114
if (Cfg.Documentation.CommentFormat == Config::CommentFormatPolicy::Doxygen &&
115-
isa<ParmVarDecl>(Decl)) {
115+
isa<ParmVarDecl, TemplateTypeParmDecl>(Decl)) {
116116
// Parameters are documented in their declaration context (function or
117117
// template function).
118118
const NamedDecl *ND = dyn_cast<NamedDecl>(Decl.getDeclContext());
@@ -135,7 +135,11 @@ std::string getDeclComment(const ASTContext &Ctx, const NamedDecl &Decl) {
135135
std::string RawDoc;
136136
llvm::raw_string_ostream OS(RawDoc);
137137

138-
V.parameterDocToString(dyn_cast<ParmVarDecl>(&Decl)->getName(), OS);
138+
if (auto *PVD = dyn_cast<ParmVarDecl>(&Decl))
139+
V.parameterDocToString(PVD->getName(), OS);
140+
else
141+
V.templateTypeParmDocToString(
142+
cast<TemplateTypeParmDecl>(&Decl)->getName(), OS);
139143

140144
Doc = StringRef(RawDoc).trim().str();
141145
} else {

‎clang-tools-extra/clangd/Hover.cpp‎

Lines changed: 82 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1274,10 +1274,10 @@ std::optional<HoverInfo> getHover(ParsedAST &AST, Position Pos,
12741274
HoverCountMetric.record(1, "include");
12751275
HoverInfo HI;
12761276
HI.Name = std::string(llvm::sys::path::filename(Inc.Resolved));
1277-
// FIXME: We don't have a fitting value for Kind.
12781277
HI.Definition =
12791278
URIForFile::canonicalize(Inc.Resolved, AST.tuPath()).file().str();
12801279
HI.DefinitionLanguage = "";
1280+
HI.Kind = index::SymbolKind::IncludeDirective;
12811281
maybeAddUsedSymbols(AST, HI, Inc);
12821282
return HI;
12831283
}
@@ -1483,10 +1483,6 @@ void HoverInfo::sizeToMarkupParagraph(markup::Paragraph &P) const {
14831483
}
14841484

14851485
markup::Document HoverInfo::presentDoxygen() const {
1486-
// NOTE: this function is currently almost identical to presentDefault().
1487-
// This is to have a minimal change when introducing the doxygen parser.
1488-
// This function will be changed when rearranging the output for doxygen
1489-
// parsed documentation.
14901486

14911487
markup::Document Output;
14921488
// Header contains a text of the form:
@@ -1502,45 +1498,108 @@ markup::Document HoverInfo::presentDoxygen() const {
15021498
// level 1 and 2 headers in a huge font, see
15031499
// https://github.com/microsoft/vscode/issues/88417 for details.
15041500
markup::Paragraph &Header = Output.addHeading(3);
1505-
if (Kind != index::SymbolKind::Unknown)
1501+
if (Kind != index::SymbolKind::Unknown &&
1502+
Kind != index::SymbolKind::IncludeDirective)
15061503
Header.appendText(index::getSymbolKindString(Kind)).appendSpace();
15071504
assert(!Name.empty() && "hover triggered on a nameless symbol");
15081505

1509-
Header.appendCode(Name);
1506+
if (Kind == index::SymbolKind::IncludeDirective) {
1507+
Header.appendCode(Name);
1508+
1509+
if (!Definition.empty())
1510+
Output.addParagraph().appendCode(Definition);
1511+
1512+
if (!UsedSymbolNames.empty()) {
1513+
Output.addRuler();
1514+
usedSymbolNamesToMarkup(Output);
1515+
}
1516+
1517+
return Output;
1518+
}
1519+
1520+
if (!Definition.empty()) {
1521+
Output.addRuler();
1522+
definitionScopeToMarkup(Output);
1523+
} else {
1524+
Header.appendCode(Name);
1525+
}
15101526

15111527
if (!Provider.empty()) {
15121528
providerToMarkupParagraph(Output);
15131529
}
15141530

15151531
// Put a linebreak after header to increase readability.
15161532
Output.addRuler();
1517-
// Print Types on their own lines to reduce chances of getting line-wrapped by
1518-
// editor, as they might be long.
1519-
if (ReturnType) {
1520-
// For functions we display signature in a list form, e.g.:
1521-
// → `x`
1522-
// Parameters:
1523-
// - `bool param1`
1524-
// - `int param2 = 5`
1525-
Output.addParagraph().appendText("→ ").appendCode(
1526-
llvm::to_string(*ReturnType));
1527-
}
15281533

15291534
SymbolDocCommentVisitor SymbolDoc(Documentation, CommentOpts);
15301535

1536+
if (SymbolDoc.hasBriefCommand()) {
1537+
SymbolDoc.briefToMarkup(Output.addParagraph());
1538+
Output.addRuler();
1539+
}
1540+
1541+
// For functions we display signature in a list form, e.g.:
1542+
// Template Parameters:
1543+
// - `typename T` - description
1544+
// Parameters:
1545+
// - `bool param1` - description
1546+
// - `int param2 = 5` - description
1547+
// Returns
1548+
// `type` - description
1549+
if (TemplateParameters && !TemplateParameters->empty()) {
1550+
Output.addParagraph().appendBoldText("Template Parameters:");
1551+
markup::BulletList &L = Output.addBulletList();
1552+
for (const auto &Param : *TemplateParameters) {
1553+
markup::Paragraph &P = L.addItem().addParagraph();
1554+
P.appendCode(llvm::to_string(Param));
1555+
if (SymbolDoc.isTemplateTypeParmDocumented(llvm::to_string(Param.Name))) {
1556+
P.appendText(" - ");
1557+
SymbolDoc.templateTypeParmDocToMarkup(llvm::to_string(Param.Name), P);
1558+
}
1559+
}
1560+
Output.addRuler();
1561+
}
1562+
15311563
if (Parameters && !Parameters->empty()) {
1532-
Output.addParagraph().appendText("Parameters:");
1564+
Output.addParagraph().appendBoldText("Parameters:");
15331565
markup::BulletList &L = Output.addBulletList();
15341566
for (const auto &Param : *Parameters) {
15351567
markup::Paragraph &P = L.addItem().addParagraph();
15361568
P.appendCode(llvm::to_string(Param));
15371569

15381570
if (SymbolDoc.isParameterDocumented(llvm::to_string(Param.Name))) {
1539-
P.appendText(" -");
1571+
P.appendText(" - ");
15401572
SymbolDoc.parameterDocToMarkup(llvm::to_string(Param.Name), P);
15411573
}
15421574
}
1575+
Output.addRuler();
1576+
}
1577+
1578+
// Print Types on their own lines to reduce chances of getting line-wrapped by
1579+
// editor, as they might be long.
1580+
if (ReturnType &&
1581+
((ReturnType->Type != "void" && !ReturnType->AKA.has_value()) ||
1582+
(ReturnType->AKA.has_value() && ReturnType->AKA != "void"))) {
1583+
Output.addParagraph().appendBoldText("Returns:");
1584+
markup::Paragraph &P = Output.addParagraph();
1585+
P.appendCode(llvm::to_string(*ReturnType));
1586+
1587+
if (SymbolDoc.hasReturnCommand()) {
1588+
P.appendText(" - ");
1589+
SymbolDoc.returnToMarkup(P);
1590+
}
1591+
Output.addRuler();
15431592
}
1593+
1594+
// add specially handled doxygen commands.
1595+
SymbolDoc.warningsToMarkup(Output);
1596+
SymbolDoc.notesToMarkup(Output);
1597+
1598+
// add any other documentation.
1599+
SymbolDoc.docToMarkup(Output);
1600+
1601+
Output.addRuler();
1602+
15441603
// Don't print Type after Parameters or ReturnType as this will just duplicate
15451604
// the information
15461605
if (Type && !ReturnType && !Parameters)
@@ -1561,13 +1620,6 @@ markup::Document HoverInfo::presentDoxygen() const {
15611620
calleeArgInfoToMarkupParagraph(Output.addParagraph());
15621621
}
15631622

1564-
SymbolDoc.docToMarkup(Output);
1565-
1566-
if (!Definition.empty()) {
1567-
Output.addRuler();
1568-
definitionScopeToMarkup(Output);
1569-
}
1570-
15711623
if (!UsedSymbolNames.empty()) {
15721624
Output.addRuler();
15731625
usedSymbolNamesToMarkup(Output);
@@ -1591,7 +1643,8 @@ markup::Document HoverInfo::presentDefault() const {
15911643
// level 1 and 2 headers in a huge font, see
15921644
// https://github.com/microsoft/vscode/issues/88417 for details.
15931645
markup::Paragraph &Header = Output.addHeading(3);
1594-
if (Kind != index::SymbolKind::Unknown)
1646+
if (Kind != index::SymbolKind::Unknown &&
1647+
Kind != index::SymbolKind::IncludeDirective)
15951648
Header.appendText(index::getSymbolKindString(Kind)).appendSpace();
15961649
assert(!Name.empty() && "hover triggered on a nameless symbol");
15971650
Header.appendCode(Name);
@@ -1615,7 +1668,7 @@ markup::Document HoverInfo::presentDefault() const {
16151668
}
16161669

16171670
if (Parameters && !Parameters->empty()) {
1618-
Output.addParagraph().appendText("Parameters: ");
1671+
Output.addParagraph().appendText("Parameters:");
16191672
markup::BulletList &L = Output.addBulletList();
16201673
for (const auto &Param : *Parameters)
16211674
L.addItem().addParagraph().appendCode(llvm::to_string(Param));

‎clang-tools-extra/clangd/Protocol.cpp‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -297,6 +297,9 @@ SymbolKind adjustKindToCapability(SymbolKind Kind,
297297

298298
SymbolKind indexSymbolKindToSymbolKind(index::SymbolKind Kind) {
299299
switch (Kind) {
300+
// FIXME: for backwards compatibility, the include directive kind is treated
301+
// the same as Unknown
302+
case index::SymbolKind::IncludeDirective:
300303
case index::SymbolKind::Unknown:
301304
return SymbolKind::Variable;
302305
case index::SymbolKind::Module:

‎clang-tools-extra/clangd/Quality.cpp‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,9 @@ categorize(const index::SymbolInfo &D) {
143143
case index::SymbolKind::Parameter:
144144
case index::SymbolKind::NonTypeTemplateParm:
145145
return SymbolQualitySignals::Variable;
146+
// FIXME: for backwards compatibility, the include directive kind is treated
147+
// the same as Unknown
148+
case index::SymbolKind::IncludeDirective:
146149
case index::SymbolKind::Using:
147150
case index::SymbolKind::Module:
148151
case index::SymbolKind::Unknown:

‎clang-tools-extra/clangd/SymbolDocumentation.cpp‎

Lines changed: 96 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,8 @@ void commandToMarkup(markup::Paragraph &Out, StringRef Command,
3333
comments::CommandMarkerKind CommandMarker,
3434
StringRef Args) {
3535
Out.appendBoldText(commandMarkerAsString(CommandMarker) + Command.str());
36+
Out.appendSpace();
3637
if (!Args.empty()) {
37-
Out.appendSpace();
3838
Out.appendEmphasizedText(Args.str());
3939
}
4040
}
@@ -132,7 +132,8 @@ class ParagraphToMarkupDocument
132132
const comments::CommandTraits &Traits;
133133

134134
/// If true, the next leading space after a new line is trimmed.
135-
bool LastChunkEndsWithNewline = false;
135+
/// Initially set it to true, to always trim the first text line.
136+
bool LastChunkEndsWithNewline = true;
136137
};
137138

138139
class ParagraphToString
@@ -263,8 +264,76 @@ class BlockCommentToMarkupDocument
263264
StringRef CommentEscapeMarker;
264265
};
265266

266-
void SymbolDocCommentVisitor::parameterDocToMarkup(StringRef ParamName,
267-
markup::Paragraph &Out) {
267+
void SymbolDocCommentVisitor::visitBlockCommandComment(
268+
const comments::BlockCommandComment *B) {
269+
switch (B->getCommandID()) {
270+
case comments::CommandTraits::KCI_brief: {
271+
if (!BriefParagraph) {
272+
BriefParagraph = B->getParagraph();
273+
return;
274+
}
275+
break;
276+
}
277+
case comments::CommandTraits::KCI_return:
278+
case comments::CommandTraits::KCI_returns:
279+
if (!ReturnParagraph) {
280+
ReturnParagraph = B->getParagraph();
281+
return;
282+
}
283+
break;
284+
case comments::CommandTraits::KCI_retval:
285+
RetvalParagraphs.push_back(B->getParagraph());
286+
return;
287+
case comments::CommandTraits::KCI_warning:
288+
WarningParagraphs.push_back(B->getParagraph());
289+
return;
290+
case comments::CommandTraits::KCI_note:
291+
NoteParagraphs.push_back(B->getParagraph());
292+
return;
293+
default:
294+
break;
295+
}
296+
297+
// For all other commands, we store them in the UnhandledCommands map.
298+
// This allows us to keep the order of the comments.
299+
UnhandledCommands[CommentPartIndex] = B;
300+
CommentPartIndex++;
301+
}
302+
303+
void SymbolDocCommentVisitor::paragraphsToMarkup(
304+
markup::Document &Out,
305+
const llvm::SmallVectorImpl<const comments::ParagraphComment *> &Paragraphs)
306+
const {
307+
if (Paragraphs.empty())
308+
return;
309+
310+
for (const auto *P : Paragraphs) {
311+
ParagraphToMarkupDocument(Out.addParagraph(), Traits).visit(P);
312+
}
313+
}
314+
315+
void SymbolDocCommentVisitor::briefToMarkup(markup::Paragraph &Out) const {
316+
if (!BriefParagraph)
317+
return;
318+
ParagraphToMarkupDocument(Out, Traits).visit(BriefParagraph);
319+
}
320+
321+
void SymbolDocCommentVisitor::returnToMarkup(markup::Paragraph &Out) const {
322+
if (!ReturnParagraph)
323+
return;
324+
ParagraphToMarkupDocument(Out, Traits).visit(ReturnParagraph);
325+
}
326+
327+
void SymbolDocCommentVisitor::notesToMarkup(markup::Document &Out) const {
328+
paragraphsToMarkup(Out, NoteParagraphs);
329+
}
330+
331+
void SymbolDocCommentVisitor::warningsToMarkup(markup::Document &Out) const {
332+
paragraphsToMarkup(Out, WarningParagraphs);
333+
}
334+
335+
void SymbolDocCommentVisitor::parameterDocToMarkup(
336+
StringRef ParamName, markup::Paragraph &Out) const {
268337
if (ParamName.empty())
269338
return;
270339

@@ -274,7 +343,7 @@ void SymbolDocCommentVisitor::parameterDocToMarkup(StringRef ParamName,
274343
}
275344

276345
void SymbolDocCommentVisitor::parameterDocToString(
277-
StringRef ParamName, llvm::raw_string_ostream &Out) {
346+
StringRef ParamName, llvm::raw_string_ostream &Out) const {
278347
if (ParamName.empty())
279348
return;
280349

@@ -283,15 +352,35 @@ void SymbolDocCommentVisitor::parameterDocToString(
283352
}
284353
}
285354

286-
void SymbolDocCommentVisitor::docToMarkup(markup::Document &Out) {
355+
void SymbolDocCommentVisitor::docToMarkup(markup::Document &Out) const {
287356
for (unsigned I = 0; I < CommentPartIndex; ++I) {
288-
if (const auto *BC = BlockCommands.lookup(I)) {
357+
if (const auto *BC = UnhandledCommands.lookup(I)) {
289358
BlockCommentToMarkupDocument(Out, Traits).visit(BC);
290359
} else if (const auto *P = FreeParagraphs.lookup(I)) {
291360
ParagraphToMarkupDocument(Out.addParagraph(), Traits).visit(P);
292361
}
293362
}
294363
}
295364

365+
void SymbolDocCommentVisitor::templateTypeParmDocToMarkup(
366+
StringRef TemplateParamName, markup::Paragraph &Out) const {
367+
if (TemplateParamName.empty())
368+
return;
369+
370+
if (const auto *TP = TemplateParameters.lookup(TemplateParamName)) {
371+
ParagraphToMarkupDocument(Out, Traits).visit(TP->getParagraph());
372+
}
373+
}
374+
375+
void SymbolDocCommentVisitor::templateTypeParmDocToString(
376+
StringRef TemplateParamName, llvm::raw_string_ostream &Out) const {
377+
if (TemplateParamName.empty())
378+
return;
379+
380+
if (const auto *P = TemplateParameters.lookup(TemplateParamName)) {
381+
ParagraphToString(Out, Traits).visit(P->getParagraph());
382+
}
383+
}
384+
296385
} // namespace clangd
297386
} // namespace clang

0 commit comments

Comments
 (0)