clang-tools  9.0.0
CodeCompletionStrings.cpp
Go to the documentation of this file.
1 //===--- CodeCompletionStrings.cpp -------------------------------*- C++-*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
10 #include "clang/AST/ASTContext.h"
11 #include "clang/AST/DeclObjC.h"
12 #include "clang/AST/RawCommentList.h"
13 #include "clang/Basic/SourceManager.h"
14 #include "clang/Sema/CodeCompleteConsumer.h"
15 #include <limits>
16 #include <utility>
17 
18 namespace clang {
19 namespace clangd {
20 namespace {
21 
22 bool isInformativeQualifierChunk(CodeCompletionString::Chunk const &Chunk) {
23  return Chunk.Kind == CodeCompletionString::CK_Informative &&
24  llvm::StringRef(Chunk.Text).endswith("::");
25 }
26 
27 void appendEscapeSnippet(const llvm::StringRef Text, std::string *Out) {
28  for (const auto Character : Text) {
29  if (Character == '$' || Character == '}' || Character == '\\')
30  Out->push_back('\\');
31  Out->push_back(Character);
32  }
33 }
34 
35 bool looksLikeDocComment(llvm::StringRef CommentText) {
36  // We don't report comments that only contain "special" chars.
37  // This avoids reporting various delimiters, like:
38  // =================
39  // -----------------
40  // *****************
41  return CommentText.find_first_not_of("/*-= \t\r\n") != llvm::StringRef::npos;
42 }
43 
44 } // namespace
45 
46 std::string getDocComment(const ASTContext &Ctx,
47  const CodeCompletionResult &Result,
48  bool CommentsFromHeaders) {
49  // FIXME: clang's completion also returns documentation for RK_Pattern if they
50  // contain a pattern for ObjC properties. Unfortunately, there is no API to
51  // get this declaration, so we don't show documentation in that case.
52  if (Result.Kind != CodeCompletionResult::RK_Declaration)
53  return "";
54  return Result.getDeclaration() ? getDeclComment(Ctx, *Result.getDeclaration())
55  : "";
56 }
57 
58 std::string getDeclComment(const ASTContext &Ctx, const NamedDecl &Decl) {
59  if (isa<NamespaceDecl>(Decl)) {
60  // Namespaces often have too many redecls for any particular redecl comment
61  // to be useful. Moreover, we often confuse file headers or generated
62  // comments with namespace comments. Therefore we choose to just ignore
63  // the comments for namespaces.
64  return "";
65  }
66  const RawComment *RC = getCompletionComment(Ctx, &Decl);
67  if (!RC)
68  return "";
69  // Sanity check that the comment does not come from the PCH. We choose to not
70  // write them into PCH, because they are racy and slow to load.
71  assert(!Ctx.getSourceManager().isLoadedSourceLocation(RC->getBeginLoc()));
72  std::string Doc =
73  RC->getFormattedText(Ctx.getSourceManager(), Ctx.getDiagnostics());
74  return looksLikeDocComment(Doc) ? Doc : "";
75 }
76 
77 void getSignature(const CodeCompletionString &CCS, std::string *Signature,
78  std::string *Snippet, std::string *RequiredQualifiers,
79  bool CompletingPattern) {
80  // Placeholder with this index will be ${0:…} to mark final cursor position.
81  // Usually we do not add $0, so the cursor is placed at end of completed text.
82  unsigned CursorSnippetArg = std::numeric_limits<unsigned>::max();
83  if (CompletingPattern) {
84  // In patterns, it's best to place the cursor at the last placeholder, to
85  // handle cases like
86  // namespace ${1:name} {
87  // ${0:decls}
88  // }
89  CursorSnippetArg =
90  llvm::count_if(CCS, [](const CodeCompletionString::Chunk &C) {
91  return C.Kind == CodeCompletionString::CK_Placeholder;
92  });
93  }
94  unsigned SnippetArg = 0;
95  bool HadObjCArguments = false;
96  for (const auto &Chunk : CCS) {
97  // Informative qualifier chunks only clutter completion results, skip
98  // them.
99  if (isInformativeQualifierChunk(Chunk))
100  continue;
101 
102  switch (Chunk.Kind) {
103  case CodeCompletionString::CK_TypedText:
104  // The typed-text chunk is the actual name. We don't record this chunk.
105  // C++:
106  // In general our string looks like <qualifiers><name><signature>.
107  // So once we see the name, any text we recorded so far should be
108  // reclassified as qualifiers.
109  //
110  // Objective-C:
111  // Objective-C methods may have multiple typed-text chunks, so we must
112  // treat them carefully. For Objective-C methods, all typed-text chunks
113  // will end in ':' (unless there are no arguments, in which case we
114  // can safely treat them as C++).
115  if (!llvm::StringRef(Chunk.Text).endswith(":")) { // Treat as C++.
116  if (RequiredQualifiers)
117  *RequiredQualifiers = std::move(*Signature);
118  Signature->clear();
119  Snippet->clear();
120  } else { // Objective-C method with args.
121  // If this is the first TypedText to the Objective-C method, discard any
122  // text that we've previously seen (such as previous parameter selector,
123  // which will be marked as Informative text).
124  //
125  // TODO: Make previous parameters part of the signature for Objective-C
126  // methods.
127  if (!HadObjCArguments) {
128  HadObjCArguments = true;
129  Signature->clear();
130  } else { // Subsequent argument, considered part of snippet/signature.
131  *Signature += Chunk.Text;
132  *Snippet += Chunk.Text;
133  }
134  }
135  break;
136  case CodeCompletionString::CK_Text:
137  *Signature += Chunk.Text;
138  *Snippet += Chunk.Text;
139  break;
140  case CodeCompletionString::CK_Optional:
141  break;
142  case CodeCompletionString::CK_Placeholder:
143  *Signature += Chunk.Text;
144  ++SnippetArg;
145  *Snippet +=
146  "${" +
147  std::to_string(SnippetArg == CursorSnippetArg ? 0 : SnippetArg) + ':';
148  appendEscapeSnippet(Chunk.Text, Snippet);
149  *Snippet += '}';
150  break;
151  case CodeCompletionString::CK_Informative:
152  // For example, the word "const" for a const method, or the name of
153  // the base class for methods that are part of the base class.
154  *Signature += Chunk.Text;
155  // Don't put the informative chunks in the snippet.
156  break;
157  case CodeCompletionString::CK_ResultType:
158  // This is not part of the signature.
159  break;
160  case CodeCompletionString::CK_CurrentParameter:
161  // This should never be present while collecting completion items,
162  // only while collecting overload candidates.
163  llvm_unreachable("Unexpected CK_CurrentParameter while collecting "
164  "CompletionItems");
165  break;
166  case CodeCompletionString::CK_LeftParen:
167  case CodeCompletionString::CK_RightParen:
168  case CodeCompletionString::CK_LeftBracket:
169  case CodeCompletionString::CK_RightBracket:
170  case CodeCompletionString::CK_LeftBrace:
171  case CodeCompletionString::CK_RightBrace:
172  case CodeCompletionString::CK_LeftAngle:
173  case CodeCompletionString::CK_RightAngle:
174  case CodeCompletionString::CK_Comma:
175  case CodeCompletionString::CK_Colon:
176  case CodeCompletionString::CK_SemiColon:
177  case CodeCompletionString::CK_Equal:
178  case CodeCompletionString::CK_HorizontalSpace:
179  *Signature += Chunk.Text;
180  *Snippet += Chunk.Text;
181  break;
182  case CodeCompletionString::CK_VerticalSpace:
183  *Snippet += Chunk.Text;
184  // Don't even add a space to the signature.
185  break;
186  }
187  }
188 }
189 
190 std::string formatDocumentation(const CodeCompletionString &CCS,
191  llvm::StringRef DocComment) {
192  // Things like __attribute__((nonnull(1,3))) and [[noreturn]]. Present this
193  // information in the documentation field.
194  std::string Result;
195  const unsigned AnnotationCount = CCS.getAnnotationCount();
196  if (AnnotationCount > 0) {
197  Result += "Annotation";
198  if (AnnotationCount == 1) {
199  Result += ": ";
200  } else /* AnnotationCount > 1 */ {
201  Result += "s: ";
202  }
203  for (unsigned I = 0; I < AnnotationCount; ++I) {
204  Result += CCS.getAnnotation(I);
205  Result.push_back(I == AnnotationCount - 1 ? '\n' : ' ');
206  }
207  }
208  // Add brief documentation (if there is any).
209  if (!DocComment.empty()) {
210  if (!Result.empty()) {
211  // This means we previously added annotations. Add an extra newline
212  // character to make the annotations stand out.
213  Result.push_back('\n');
214  }
215  Result += DocComment;
216  }
217  return Result;
218 }
219 
220 std::string getReturnType(const CodeCompletionString &CCS) {
221  for (const auto &Chunk : CCS)
222  if (Chunk.Kind == CodeCompletionString::CK_ResultType)
223  return Chunk.Text;
224  return "";
225 }
226 
227 } // namespace clangd
228 } // namespace clang
std::string getDocComment(const ASTContext &Ctx, const CodeCompletionResult &Result, bool CommentsFromHeaders)
Gets a minimally formatted documentation comment of Result, with comment markers stripped.
std::string getReturnType(const CodeCompletionString &CCS)
Gets detail to be used as the detail field in an LSP completion item.
Context Ctx
std::string Signature
std::string formatDocumentation(const CodeCompletionString &CCS, llvm::StringRef DocComment)
Assembles formatted documentation for a completion result.
std::string getDeclComment(const ASTContext &Ctx, const NamedDecl &Decl)
Similar to getDocComment, but returns the comment for a NamedDecl.
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
void getSignature(const CodeCompletionString &CCS, std::string *Signature, std::string *Snippet, std::string *RequiredQualifiers, bool CompletingPattern)
Formats the signature for an item, as a display string and snippet.
llvm::Optional< llvm::Expected< tooling::AtomicChanges > > Result
Definition: Rename.cpp:36