clang-tools  14.0.0git
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 "llvm/Support/JSON.h"
16 #include <limits>
17 #include <utility>
18 
19 namespace clang {
20 namespace clangd {
21 namespace {
22 
23 bool isInformativeQualifierChunk(CodeCompletionString::Chunk const &Chunk) {
24  return Chunk.Kind == CodeCompletionString::CK_Informative &&
25  llvm::StringRef(Chunk.Text).endswith("::");
26 }
27 
28 void appendEscapeSnippet(const llvm::StringRef Text, std::string *Out) {
29  for (const auto Character : Text) {
30  if (Character == '$' || Character == '}' || Character == '\\')
31  Out->push_back('\\');
32  Out->push_back(Character);
33  }
34 }
35 
36 void appendOptionalChunk(const CodeCompletionString &CCS, std::string *Out) {
37  for (const CodeCompletionString::Chunk &C : CCS) {
38  switch (C.Kind) {
39  case CodeCompletionString::CK_Optional:
40  assert(C.Optional &&
41  "Expected the optional code completion string to be non-null.");
42  appendOptionalChunk(*C.Optional, Out);
43  break;
44  default:
45  *Out += C.Text;
46  break;
47  }
48  }
49 }
50 
51 bool looksLikeDocComment(llvm::StringRef CommentText) {
52  // We don't report comments that only contain "special" chars.
53  // This avoids reporting various delimiters, like:
54  // =================
55  // -----------------
56  // *****************
57  return CommentText.find_first_not_of("/*-= \t\r\n") != llvm::StringRef::npos;
58 }
59 
60 } // namespace
61 
62 std::string getDocComment(const ASTContext &Ctx,
63  const CodeCompletionResult &Result,
64  bool CommentsFromHeaders) {
65  // FIXME: clang's completion also returns documentation for RK_Pattern if they
66  // contain a pattern for ObjC properties. Unfortunately, there is no API to
67  // get this declaration, so we don't show documentation in that case.
68  if (Result.Kind != CodeCompletionResult::RK_Declaration)
69  return "";
70  return Result.getDeclaration() ? getDeclComment(Ctx, *Result.getDeclaration())
71  : "";
72 }
73 
74 std::string getDeclComment(const ASTContext &Ctx, const NamedDecl &Decl) {
75  if (isa<NamespaceDecl>(Decl)) {
76  // Namespaces often have too many redecls for any particular redecl comment
77  // to be useful. Moreover, we often confuse file headers or generated
78  // comments with namespace comments. Therefore we choose to just ignore
79  // the comments for namespaces.
80  return "";
81  }
82  const RawComment *RC = getCompletionComment(Ctx, &Decl);
83  if (!RC)
84  return "";
85  // Sanity check that the comment does not come from the PCH. We choose to not
86  // write them into PCH, because they are racy and slow to load.
87  assert(!Ctx.getSourceManager().isLoadedSourceLocation(RC->getBeginLoc()));
88  std::string Doc =
89  RC->getFormattedText(Ctx.getSourceManager(), Ctx.getDiagnostics());
90  if (!looksLikeDocComment(Doc))
91  return "";
92  // Clang requires source to be UTF-8, but doesn't enforce this in comments.
93  if (!llvm::json::isUTF8(Doc))
94  Doc = llvm::json::fixUTF8(Doc);
95  return Doc;
96 }
97 
98 void getSignature(const CodeCompletionString &CCS, std::string *Signature,
99  std::string *Snippet, std::string *RequiredQualifiers,
100  bool CompletingPattern) {
101  // Placeholder with this index will be ${0:…} to mark final cursor position.
102  // Usually we do not add $0, so the cursor is placed at end of completed text.
103  unsigned CursorSnippetArg = std::numeric_limits<unsigned>::max();
104  if (CompletingPattern) {
105  // In patterns, it's best to place the cursor at the last placeholder, to
106  // handle cases like
107  // namespace ${1:name} {
108  // ${0:decls}
109  // }
110  CursorSnippetArg =
111  llvm::count_if(CCS, [](const CodeCompletionString::Chunk &C) {
112  return C.Kind == CodeCompletionString::CK_Placeholder;
113  });
114  }
115  unsigned SnippetArg = 0;
116  bool HadObjCArguments = false;
117  bool HadInformativeChunks = false;
118  for (const auto &Chunk : CCS) {
119  // Informative qualifier chunks only clutter completion results, skip
120  // them.
121  if (isInformativeQualifierChunk(Chunk))
122  continue;
123 
124  switch (Chunk.Kind) {
125  case CodeCompletionString::CK_TypedText:
126  // The typed-text chunk is the actual name. We don't record this chunk.
127  // C++:
128  // In general our string looks like <qualifiers><name><signature>.
129  // So once we see the name, any text we recorded so far should be
130  // reclassified as qualifiers.
131  //
132  // Objective-C:
133  // Objective-C methods expressions may have multiple typed-text chunks,
134  // so we must treat them carefully. For Objective-C methods, all
135  // typed-text and informative chunks will end in ':' (unless there are
136  // no arguments, in which case we can safely treat them as C++).
137  //
138  // Completing a method declaration itself (not a method expression) is
139  // similar except that we use the `RequiredQualifiers` to store the
140  // text before the selector, e.g. `- (void)`.
141  if (!llvm::StringRef(Chunk.Text).endswith(":")) { // Treat as C++.
142  if (RequiredQualifiers)
143  *RequiredQualifiers = std::move(*Signature);
144  Signature->clear();
145  Snippet->clear();
146  } else { // Objective-C method with args.
147  // If this is the first TypedText to the Objective-C method, discard any
148  // text that we've previously seen (such as previous parameter selector,
149  // which will be marked as Informative text).
150  //
151  // TODO: Make previous parameters part of the signature for Objective-C
152  // methods.
153  if (!HadObjCArguments) {
154  HadObjCArguments = true;
155  // If we have no previous informative chunks (informative selector
156  // fragments in practice), we treat any previous chunks as
157  // `RequiredQualifiers` so they will be added as a prefix during the
158  // completion.
159  //
160  // e.g. to complete `- (void)doSomething:(id)argument`:
161  // - Completion name: `doSomething:`
162  // - RequiredQualifiers: `- (void)`
163  // - Snippet/Signature suffix: `(id)argument`
164  //
165  // This differs from the case when we're completing a method
166  // expression with a previous informative selector fragment.
167  //
168  // e.g. to complete `[self doSomething:nil ^somethingElse:(id)]`:
169  // - Previous Informative Chunk: `doSomething:`
170  // - Completion name: `somethingElse:`
171  // - Snippet/Signature suffix: `(id)`
172  if (!HadInformativeChunks) {
173  if (RequiredQualifiers)
174  *RequiredQualifiers = std::move(*Signature);
175  Snippet->clear();
176  }
177  Signature->clear();
178  } else { // Subsequent argument, considered part of snippet/signature.
179  *Signature += Chunk.Text;
180  *Snippet += Chunk.Text;
181  }
182  }
183  break;
184  case CodeCompletionString::CK_Text:
185  *Signature += Chunk.Text;
186  *Snippet += Chunk.Text;
187  break;
188  case CodeCompletionString::CK_Optional:
189  assert(Chunk.Optional);
190  // No need to create placeholders for default arguments in Snippet.
191  appendOptionalChunk(*Chunk.Optional, Signature);
192  break;
193  case CodeCompletionString::CK_Placeholder:
194  *Signature += Chunk.Text;
195  ++SnippetArg;
196  *Snippet +=
197  "${" +
198  std::to_string(SnippetArg == CursorSnippetArg ? 0 : SnippetArg) + ':';
199  appendEscapeSnippet(Chunk.Text, Snippet);
200  *Snippet += '}';
201  break;
202  case CodeCompletionString::CK_Informative:
203  HadInformativeChunks = true;
204  // For example, the word "const" for a const method, or the name of
205  // the base class for methods that are part of the base class.
206  *Signature += Chunk.Text;
207  // Don't put the informative chunks in the snippet.
208  break;
209  case CodeCompletionString::CK_ResultType:
210  // This is not part of the signature.
211  break;
212  case CodeCompletionString::CK_CurrentParameter:
213  // This should never be present while collecting completion items,
214  // only while collecting overload candidates.
215  llvm_unreachable("Unexpected CK_CurrentParameter while collecting "
216  "CompletionItems");
217  break;
218  case CodeCompletionString::CK_LeftParen:
219  case CodeCompletionString::CK_RightParen:
220  case CodeCompletionString::CK_LeftBracket:
221  case CodeCompletionString::CK_RightBracket:
222  case CodeCompletionString::CK_LeftBrace:
223  case CodeCompletionString::CK_RightBrace:
224  case CodeCompletionString::CK_LeftAngle:
225  case CodeCompletionString::CK_RightAngle:
226  case CodeCompletionString::CK_Comma:
227  case CodeCompletionString::CK_Colon:
228  case CodeCompletionString::CK_SemiColon:
229  case CodeCompletionString::CK_Equal:
230  case CodeCompletionString::CK_HorizontalSpace:
231  *Signature += Chunk.Text;
232  *Snippet += Chunk.Text;
233  break;
234  case CodeCompletionString::CK_VerticalSpace:
235  *Snippet += Chunk.Text;
236  // Don't even add a space to the signature.
237  break;
238  }
239  }
240 }
241 
242 std::string formatDocumentation(const CodeCompletionString &CCS,
243  llvm::StringRef DocComment) {
244  // Things like __attribute__((nonnull(1,3))) and [[noreturn]]. Present this
245  // information in the documentation field.
246  std::string Result;
247  const unsigned AnnotationCount = CCS.getAnnotationCount();
248  if (AnnotationCount > 0) {
249  Result += "Annotation";
250  if (AnnotationCount == 1) {
251  Result += ": ";
252  } else /* AnnotationCount > 1 */ {
253  Result += "s: ";
254  }
255  for (unsigned I = 0; I < AnnotationCount; ++I) {
256  Result += CCS.getAnnotation(I);
257  Result.push_back(I == AnnotationCount - 1 ? '\n' : ' ');
258  }
259  }
260  // Add brief documentation (if there is any).
261  if (!DocComment.empty()) {
262  if (!Result.empty()) {
263  // This means we previously added annotations. Add an extra newline
264  // character to make the annotations stand out.
265  Result.push_back('\n');
266  }
267  Result += DocComment;
268  }
269  return Result;
270 }
271 
272 std::string getReturnType(const CodeCompletionString &CCS) {
273  for (const auto &Chunk : CCS)
274  if (Chunk.Kind == CodeCompletionString::CK_ResultType)
275  return Chunk.Text;
276  return "";
277 }
278 
279 } // namespace clangd
280 } // namespace clang
clang::clangd::getDeclComment
std::string getDeclComment(const ASTContext &Ctx, const NamedDecl &Decl)
Similar to getDocComment, but returns the comment for a NamedDecl.
Definition: CodeCompletionStrings.cpp:74
Ctx
Context Ctx
Definition: TUScheduler.cpp:454
Snippet
std::string Snippet
Definition: CodeCompletionStringsTests.cpp:38
clang::clangd::remote::Character
char Character
Definition: Header.h:5
clang::clangd::getDocComment
std::string getDocComment(const ASTContext &Ctx, const CodeCompletionResult &Result, bool CommentsFromHeaders)
Gets a minimally formatted documentation comment of Result, with comment markers stripped.
Definition: CodeCompletionStrings.cpp:62
clang::clangd::formatDocumentation
std::string formatDocumentation(const CodeCompletionString &CCS, llvm::StringRef DocComment)
Assembles formatted documentation for a completion result.
Definition: CodeCompletionStrings.cpp:242
Decl
const FunctionDecl * Decl
Definition: AvoidBindCheck.cpp:100
CodeCompletionStrings.h
clang::clangd::getSignature
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.
Definition: CodeCompletionStrings.cpp:98
C
const Criteria C
Definition: FunctionCognitiveComplexityCheck.cpp:93
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
clang::clangd::getReturnType
std::string getReturnType(const CodeCompletionString &CCS)
Gets detail to be used as the detail field in an LSP completion item.
Definition: CodeCompletionStrings.cpp:272
Out
CompiledFragmentImpl & Out
Definition: ConfigCompile.cpp:100
Signature
std::string Signature
Definition: CodeComplete.cpp:432