[IDE] Add full documentation to code completion result

include/swift/AST/ASTDemangler.h

@@ -32,8 +32,10 @@
 #include <optional>
 
 namespace swift {
-
+
+class Decl;
 class TypeDecl;
+class DeclName;
 
 namespace Demangle {
 SWIFT_BEGIN_INLINE_NAMESPACE
@@ -50,6 +52,9 @@ TypeDecl *getTypeDeclForUSR(ASTContext &ctx,
                             llvm::StringRef usr,
                             GenericSignature genericSig=GenericSignature());
 
+Decl *getDeclForUSR(ASTContext &ctx, llvm::StringRef usr,
+                    GenericSignature genericSig = GenericSignature());
+
 /// An implementation of MetadataReader's BuilderType concept that
 /// just finds and builds things in the AST.
 class ASTBuilder {
@@ -122,6 +127,17 @@ class ASTBuilder {
 
   Demangle::NodeFactory &getNodeFactory() { return Factory; }
 
+  /// Finds the \c Decl associated with the provided \p node.
+  /// Attempts to find a type declaration using \c createTypeDecl, if not found,
+  /// it performs a lookup for the declaration and returns the first declaration
+  /// for which \c isMatchingValueDecl returns true.
+  ///
+  /// \note \p isMatchingValueDecl is not evaluated for type declarations, it's
+  /// only used to choose among lookup results when \c createTypeDecl fails.
+  Decl *
+  findDecl(NodePointer node,
+           llvm::function_ref<bool(const ValueDecl *)> isMatchingValueDecl);
+
   Type decodeMangledType(NodePointer node, bool forRequirement = true);
   Type createBuiltinType(StringRef builtinName, StringRef mangledName);
 
@@ -286,7 +302,8 @@ class ASTBuilder {
   /// The module name encoded in the node is either the module's real or ABI
   /// name. Multiple modules can share the same name. This function returns
   /// all modules that contain that name.
-  llvm::ArrayRef<ModuleDecl *> findPotentialModules(NodePointer node);
+  llvm::ArrayRef<ModuleDecl *> findPotentialModules(NodePointer node,
+                                                    ModuleDecl *&scratch);
 
   Demangle::NodePointer findModuleNode(NodePointer node);
 

include/swift/AST/Decl.h

@@ -2909,6 +2909,10 @@ class ValueDecl : public Decl {
     /// a null pointer.
     unsigned noOpaqueResultType : 1;
 
+    /// Whether the ClangUSRGenerationRequest request was evaluated and produced
+    /// a std::nullopt.
+    unsigned noClangUSR : 1;
+
     /// Whether the "isFinal" bit has been computed yet.
     unsigned isFinalComputed : 1;
 
@@ -2943,6 +2947,7 @@ class ValueDecl : public Decl {
   friend class OpaqueResultTypeRequest;
   friend class ApplyAccessNoteRequest;
   friend class AvailabilityDomainForDeclRequest;
+  friend class ClangUSRGenerationRequest;
 
   friend class Decl;
   SourceLoc getLocFromSource() const { return NameLoc; }

include/swift/AST/DeclNameExtractor.h

@@ -0,0 +1,58 @@
+//===--- DeclNameExtractor.h - Decl Name Demangling -------------*- C++ -*-===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2025 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+//
+// This file defines the DeclNameExtractor utility.
+//
+//===----------------------------------------------------------------------===//
+
+#include "swift/AST/ASTContext.h"
+#include "swift/AST/Identifier.h"
+
+namespace swift {
+namespace Demangle {
+
+class Node;
+
+class DeclNameExtractor {
+private:
+  ASTContext &Ctx;
+
+public:
+  DeclNameExtractor(ASTContext &ctx) : Ctx(ctx) {}
+
+  /// Extract a DeclName from a demangling node
+  /// \returns true if a \c DeclName is found, false otherwise.
+  bool extractDeclName(Node *node, DeclName &name,
+                       Identifier &privateDiscriminator);
+
+private:
+  bool extractIdentifierName(Node *node, DeclName &declName,
+                             Identifier &privateDiscriminator);
+  bool extractFunctionLikeName(Node *node, DeclName &declName,
+                               Identifier &privateDiscriminator);
+  void extractArgLabelsFromLabelList(Node *LabelList,
+                                     SmallVectorImpl<Identifier> &ArgLabels);
+  void extractArgLabelsFromType(Node *Type,
+                                SmallVectorImpl<Identifier> &ArgLabels);
+  DeclBaseName extractOperatorName(Node *node);
+};
+
+/// Returns an identifier with the given name, automatically removing any
+/// surrounding backticks that are present for raw identifiers.
+Identifier getIdentifier(ASTContext &Ctx, StringRef name);
+
+bool extractNameNodeInfo(ASTContext &Ctx, Node *node, StringRef &name,
+                         StringRef &relatedEntityKind,
+                         Identifier &privateDiscriminator);
+
+} // namespace Demangle
+} // namespace swift

include/swift/AST/TypeCheckRequests.h

@@ -757,20 +757,70 @@ class RequirementRequest :
   bool isCached() const;
 };
 
+/// Generate the Clang USR for the given declaration.
+class ClangUSRGenerationRequest
+    : public SimpleRequest<ClangUSRGenerationRequest,
+                           std::optional<std::string>(const ValueDecl *),
+                           RequestFlags::SeparatelyCached |
+                               RequestFlags::SplitCached> {
+public:
+  using SimpleRequest::SimpleRequest;
+
+private:
+  friend SimpleRequest;
+
+  // Evaluation.
+  std::optional<std::string> evaluate(Evaluator &eval,
+                                      const ValueDecl *d) const;
+
+public:
+  // Split caching.
+  bool isCached() const { return true; }
+  std::optional<std::optional<std::string>> getCachedResult() const;
+  void cacheResult(std::optional<std::string> result) const;
+};
+
+/// Generate the Swift USR for the given declaration.
+class SwiftUSRGenerationRequest
+    : public SimpleRequest<SwiftUSRGenerationRequest,
+                           std::string(const ValueDecl *),
+                           RequestFlags::Cached> {
+public:
+  using SimpleRequest::SimpleRequest;
+
+private:
+  friend SimpleRequest;
+
+  // Evaluation.
+  std::string evaluate(Evaluator &eval, const ValueDecl *d) const;
+
+public:
+  // Caching
+  bool isCached() const { return true; }
+};
+
 struct USRGenerationOptions {
   /// @brief Whether to emit USRs using the Swift declaration when it is
   /// synthesized from a Clang based declaration. Useful in cases where Swift
   /// declarations are synthesized from Clang nodes but the caller actually
   /// wants the USR of the Swift declaration.
   bool distinguishSynthesizedDecls;
 
+  /// @brief Whether to emit USRs using the Swift declaration for all
+  /// declarations specifically, emits a Swift USR for all Clang-based
+  /// declarations.
+  bool useSwiftUSR;
+
   friend llvm::hash_code hash_value(const USRGenerationOptions &options) {
-    return llvm::hash_value(options.distinguishSynthesizedDecls);
+    return llvm::hash_combine(
+        llvm::hash_value(options.distinguishSynthesizedDecls),
+        llvm::hash_value(options.useSwiftUSR));
   }
 
   friend bool operator==(const USRGenerationOptions &lhs,
                          const USRGenerationOptions &rhs) {
-    return lhs.distinguishSynthesizedDecls == rhs.distinguishSynthesizedDecls;
+    return lhs.distinguishSynthesizedDecls == rhs.distinguishSynthesizedDecls &&
+           lhs.useSwiftUSR == rhs.useSwiftUSR;
   }
 
   friend bool operator!=(const USRGenerationOptions &lhs,
@@ -783,10 +833,12 @@ void simple_display(llvm::raw_ostream &out,
                     const USRGenerationOptions &options);
 
 /// Generate the USR for the given declaration.
+/// This is an umbrella request that forwards to ClangUSRGenerationRequest or
+/// SwiftUSRGenerationRequest.
 class USRGenerationRequest
     : public SimpleRequest<USRGenerationRequest,
                            std::string(const ValueDecl *, USRGenerationOptions),
-                           RequestFlags::Cached> {
+                           RequestFlags::Uncached> {
 public:
   using SimpleRequest::SimpleRequest;
 
@@ -796,10 +848,6 @@ class USRGenerationRequest
   // Evaluation.
   std::string evaluate(Evaluator &eval, const ValueDecl *d,
                        USRGenerationOptions options) const;
-
-public:
-  // Caching
-  bool isCached() const { return true; }
 };
 
 /// Generate the mangling for the given local type declaration.

include/swift/AST/TypeCheckerTypeIDZone.def

@@ -364,9 +364,15 @@ SWIFT_REQUEST(TypeChecker, TypeCheckASTNodeAtLocRequest,
               Uncached, NoLocationInfo)
 SWIFT_REQUEST(TypeChecker, UnderlyingTypeRequest, Type(TypeAliasDecl *),
               SeparatelyCached, NoLocationInfo)
+SWIFT_REQUEST(TypeChecker, ClangUSRGenerationRequest,
+              std::optional<std::string>(const ValueDecl *),
+              SeparatelyCached | SplitCached, NoLocationInfo)
+SWIFT_REQUEST(TypeChecker, SwiftUSRGenerationRequest,
+              std::string(const ValueDecl *),
+              Cached, NoLocationInfo)
 SWIFT_REQUEST(TypeChecker, USRGenerationRequest,
               std::string(const ValueDecl *, USRGenerationOptions),
-              Cached, NoLocationInfo)
+              Uncached, NoLocationInfo)
 SWIFT_REQUEST(TypeChecker, IsABICompatibleOverrideRequest,
               bool(ValueDecl *), Cached, NoLocationInfo)
 SWIFT_REQUEST(TypeChecker, IsStaticRequest,

include/swift/AST/USRGeneration.h

@@ -45,9 +45,20 @@ bool printDeclTypeUSR(const ValueDecl *D, raw_ostream &OS);
 /// Prints out the USR for the given ValueDecl.
 /// @param distinguishSynthesizedDecls Whether to use the USR of the
 /// synthesized declaration instead of the USR of the underlying Clang USR.
+/// @param useSwiftUSR Whether to generate a Swift USR for all Clang
+/// declarations as well.
 /// \returns true if it failed, false on success.
 bool printValueDeclUSR(const ValueDecl *D, raw_ostream &OS,
-                       bool distinguishSynthesizedDecls = false);
+                       bool distinguishSynthesizedDecls = false,
+                       bool useSwiftUSR = false);
+
+/// Prints out the Swift USR for the given ValueDecl regardless of its source
+/// (Swift or Clang). Equivalent to `printValueDeclUSR(D, OS, false,
+/// /*useSwiftUSR=*/true)`
+inline bool printValueDeclSwiftUSR(const ValueDecl *D, raw_ostream &OS) {
+  return printValueDeclUSR(D, OS, /*distinguishSynthesizedDecls=*/false,
+                           /*useSwiftUSR=*/true);
+}
 
 /// Prints out the USR for the given ModuleEntity.
 /// In case module aliasing is used, it prints the real module name. For example,

include/swift/IDE/CodeCompletionContext.h

@@ -86,6 +86,9 @@ class CodeCompletionContext {
     return CurrentResults.addCallWithNoDefaultArgs;
   }
 
+  void setVerifyUSRToDecl(bool flag) { CurrentResults.verifyUSRToDecl = flag; }
+  bool verifyUSRToDecl() const { return CurrentResults.verifyUSRToDecl; }
+
   /// Allocate a string owned by the code completion context.
   StringRef copyString(StringRef Str) {
     return Str.copy(*CurrentResults.Allocator);