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