Merge pull request #75666 from ahoppen/share-is-static

[IDE] Call into `matchWitnessStructure` to check if we should inherit a comment from an overridden declaration

Author: ahoppen

include/swift/AST/Comment.h

@@ -96,14 +96,6 @@ class DocComment {
 DocComment *getSingleDocComment(swift::markup::MarkupContext &Context,
                                 const Decl *D);
 
-/// Get the declaration that actually provides a doc comment for another.
-const Decl *getDocCommentProvidingDecl(const Decl *D);
-
-/// Attempt to get a doc comment from the declaration, or other inherited
-/// sources, like from base classes or protocols.
-DocComment *getCascadingDocComment(swift::markup::MarkupContext &MC,
-                                   const Decl *D);
-
 /// Extract comments parts from the given Markup node.
 swift::markup::CommentParts
 extractCommentParts(swift::markup::MarkupContext &MC,

include/swift/AST/Decl.h

@@ -1206,6 +1206,9 @@ class alignas(1 << DeclAlignInBits) Decl : public ASTAllocated<Decl> {
 
   std::optional<unsigned> getSourceOrder() const;
 
+  /// Get the declaration that actually provides a doc comment for another.
+  const Decl *getDocCommentProvidingDecl() const;
+
   /// \returns The brief comment attached to this declaration, or the brief
   /// comment attached to the comment providing decl.
   StringRef getSemanticBriefComment() const;

include/swift/AST/PrintOptions.h

@@ -734,13 +734,6 @@ struct PrintOptions {
     return CurrentPrintabilityChecker->shouldPrint(P, *this);
   }
 
-  /// Retrieve the print options that are suitable to print the testable interface.
-  static PrintOptions printTestableInterface(bool printFullConvention) {
-    PrintOptions result = printInterface(printFullConvention);
-    result.AccessFilter = AccessLevel::Internal;
-    return result;
-  }
-
   /// Retrieve the print options that are suitable to print interface for a
   /// swift file.
   static PrintOptions printSwiftFileInterface(bool printFullConvention) {

include/swift/AST/TypeCheckRequests.h

@@ -4684,6 +4684,24 @@ class RawCommentRequest
   bool isCached() const { return true; }
 };
 
+/// Get the declaration that actually provides a doc comment for another.
+class DocCommentProvidingDeclRequest
+    : public SimpleRequest<DocCommentProvidingDeclRequest,
+                           const Decl *(const Decl *), RequestFlags::Cached> {
+public:
+  using SimpleRequest::SimpleRequest;
+
+private:
+  friend SimpleRequest;
+
+  // Evaluation.
+  const Decl *evaluate(Evaluator &evaluator, const Decl *D) const;
+
+public:
+  // Separate caching.
+  bool isCached() const { return true; }
+};
+
 /// Retrieve the brief portion of a declaration's document comment, potentially
 /// walking to find the comment providing decl if needed.
 class SemanticBriefCommentRequest

include/swift/AST/TypeCheckerTypeIDZone.def

@@ -530,6 +530,9 @@ SWIFT_REQUEST(TypeChecker, LocalDiscriminatorsRequest,
 SWIFT_REQUEST(TypeChecker, RawCommentRequest,
               RawComment(const Decl *),
               Cached, NoLocationInfo)
+SWIFT_REQUEST(TypeChecker, DocCommentProvidingDeclRequest,
+              const Decl *(const Decl *),
+              Cached, NoLocationInfo)
 SWIFT_REQUEST(TypeChecker, SemanticBriefCommentRequest,
               StringRef(const Decl *),
               Cached, NoLocationInfo)

lib/AST/ASTPrinter.cpp

@@ -744,7 +744,7 @@ class PrintAST : public ASTVisitor<PrintAST> {
 
   void printSwiftDocumentationComment(const Decl *D) {
     if (Options.CascadeDocComment)
-      D = getDocCommentProvidingDecl(D);
+      D = D->getDocCommentProvidingDecl();
     if (!D)
       return;
     auto RC = D->getRawComment();

lib/AST/DocComment.cpp

@@ -392,225 +392,13 @@ DocComment *swift::getSingleDocComment(swift::markup::MarkupContext &MC,
   return DocComment::create(D, MC, RC);
 }
 
-namespace {
-/// Helper class for finding the comment providing decl for either a brief or
-/// raw comment.
-template <typename Result>
-class CommentProviderFinder final {
-  using ResultWithDecl = std::pair<Result, const Decl *>;
-  using VisitFnTy = std::optional<Result> (*)(const Decl *);
-
-  VisitFnTy VisitFn;
-
-public:
-  CommentProviderFinder(VisitFnTy visitFn) : VisitFn(visitFn) {}
-
-private:
-  std::optional<ResultWithDecl> visit(const Decl *D) {
-    // Adapt the provided visitor function to also return the decl.
-    if (auto result = VisitFn(D))
-      return {{*result, D}};
-    return std::nullopt;
-  }
-
-  std::optional<ResultWithDecl> findOverriddenDecl(const ValueDecl *VD) {
-    // Only applies to class member.
-    if (!VD->getDeclContext()->getSelfClassDecl())
-      return std::nullopt;
-
-    while (auto *baseDecl = VD->getOverriddenDecl()) {
-      if (auto result = visit(baseDecl))
-        return result;
-
-      VD = baseDecl;
-    }
-    return std::nullopt;
-  }
-
-  /// Check if there is an inherited protocol that has a default implementation
-  /// of `VD` with a doc comment.
-  std::optional<ResultWithDecl> findDefaultProvidedDecl(const ValueDecl *VD) {
-    NominalTypeDecl *nominalType =
-        dyn_cast_or_null<NominalTypeDecl>(VD->getDeclContext()->getAsDecl());
-    if (!nominalType) {
-      nominalType = VD->getDeclContext()->getExtendedProtocolDecl();
-    }
-    if (!nominalType)
-      return std::nullopt;
-
-    SmallVector<ValueDecl *, 2> members;
-    nominalType->lookupQualified(nominalType, DeclNameRef(VD->getName()),
-                                 VD->getLoc(), NLOptions::NL_ProtocolMembers,
-                                 members);
-
-    std::optional<ResultWithDecl> result;
-    Type vdComparisonTy = VD->getInterfaceType();
-    if (!vdComparisonTy) {
-      return std::nullopt;
-    }
-    if (auto fnTy = vdComparisonTy->getAs<AnyFunctionType>()) {
-      // Strip off the 'Self' parameter.
-      vdComparisonTy = fnTy->getResult();
-    }
-
-    for (auto *member : members) {
-      if (isa<AbstractFunctionDecl>(member) || isa<AbstractStorageDecl>(member)) {
-        if (VD->isStatic() != member->isStatic()) {
-          continue;
-        }
-        Type memberComparisonTy = member->getInterfaceType();
-        if (!memberComparisonTy) {
-          continue;
-        }
-        if (auto fnTy = memberComparisonTy->getAs<AnyFunctionType>()) {
-          // Strip off the 'Self' parameter.
-          memberComparisonTy = fnTy->getResult();
-        }
-        if (!vdComparisonTy->matches(memberComparisonTy, TypeMatchFlags::AllowOverride)) {
-          continue;
-        }
-      }
-      auto newResult = visit(member);
-      if (!newResult)
-        continue;
-
-      if (result) {
-        // Found two or more decls with doc-comment.
-        return std::nullopt;
-      }
-      result = newResult;
-    }
-    return result;
-  }
-
-  std::optional<ResultWithDecl> findRequirementDecl(const ValueDecl *VD) {
-    std::queue<const ValueDecl *> requirements;
-    while (true) {
-      for (auto *req : VD->getSatisfiedProtocolRequirements()) {
-        if (auto result = visit(req))
-          return result;
-
-        requirements.push(req);
-      }
-      if (requirements.empty())
-        return std::nullopt;
-
-      VD = requirements.front();
-      requirements.pop();
-    }
-  }
-
-public:
-  std::optional<ResultWithDecl> findCommentProvider(const Decl *D) {
-    if (auto result = visit(D))
-      return result;
-
-    auto *VD = dyn_cast<ValueDecl>(D);
-    if (!VD)
-      return std::nullopt;
-
-    if (auto result = findOverriddenDecl(VD))
-      return result;
-
-    if (auto result = findRequirementDecl(VD))
-      return result;
-
-    if (auto result = findDefaultProvidedDecl(VD))
-      return result;
-
-    return std::nullopt;
-  }
-};
-} // end anonymous namespace
-
-const Decl *swift::getDocCommentProvidingDecl(const Decl *D) {
-  // Search for the first decl we see with a non-empty raw comment.
-  auto finder = CommentProviderFinder<RawComment>(
-      [](const Decl *D) -> std::optional<RawComment> {
-        auto comment = D->getRawComment();
-        if (comment.isEmpty())
-          return std::nullopt;
-        return comment;
-      });
-
-  auto result = finder.findCommentProvider(D);
-  return result ? result->second : nullptr;
-}
-
-DocComment *swift::getCascadingDocComment(swift::markup::MarkupContext &MC,
-                                          const Decl *D) {
-  auto *docD = getDocCommentProvidingDecl(D);
-  if (!docD)
-    return nullptr;
-
-  auto *doc = getSingleDocComment(MC, docD);
-  assert(doc && "getDocCommentProvidingDecl() returned decl with no comment");
-
-  // If the doc-comment is inherited from other decl, add a note about it.
-  if (docD != D) {
-    doc->setDecl(D);
-    if (auto baseD = docD->getDeclContext()->getSelfNominalTypeDecl()) {
-      doc->addInheritanceNote(MC, baseD);
-
-      // If the doc is inherited from protocol requirement, associate the
-      // requirement with the doc-comment.
-      // FIXME: This is to keep the old behavior.
-      if (isa<ProtocolDecl>(baseD))
-        doc->setDecl(docD);
-    }
-  }
-
-  return doc;
-}
-
-/// Retrieve the brief comment for a given decl \p D, without attempting to
-/// walk any requirements or overrides.
-static std::optional<StringRef> getDirectBriefComment(const Decl *D) {
-  if (!D->canHaveComment())
-    return std::nullopt;
-
-  auto *ModuleDC = D->getDeclContext()->getModuleScopeContext();
-  auto &Ctx = ModuleDC->getASTContext();
-
-  // If we expect the comment to be in the swiftdoc, check for it if we loaded a
-  // swiftdoc. If missing from the swiftdoc, we know it will not be in the
-  // swiftsourceinfo either, so we can bail early.
-  if (auto *Unit = dyn_cast<FileUnit>(ModuleDC)) {
-    if (Unit->hasLoadedSwiftDoc()) {
-      auto target = getDocCommentSerializationTargetFor(D);
-      if (target == DocCommentSerializationTarget::SwiftDocAndSourceInfo) {
-        auto C = Unit->getCommentForDecl(D);
-        if (!C)
-          return std::nullopt;
-
-        return C->Brief;
-      }
-    }
-  }
-
-  // Otherwise, parse the brief from the raw comment itself. This will look into
-  // the swiftsourceinfo if needed.
-  auto RC = D->getRawComment();
-  if (RC.isEmpty())
-    return std::nullopt;
-
-  SmallString<256> BriefStr;
-  llvm::raw_svector_ostream OS(BriefStr);
-  printBriefComment(RC, OS);
-  return Ctx.AllocateCopy(BriefStr.str());
-}
-
-StringRef SemanticBriefCommentRequest::evaluate(Evaluator &evaluator,
-                                                const Decl *D) const {
-  // Perform a walk over the potential providers of the brief comment,
-  // retrieving the first one we come across.
-  CommentProviderFinder<StringRef> finder(getDirectBriefComment);
-  auto result = finder.findCommentProvider(D);
-  return result ? result->first : StringRef();
+const Decl *Decl::getDocCommentProvidingDecl() const {
+  return evaluateOrDefault(getASTContext().evaluator,
+                           DocCommentProvidingDeclRequest{this}, nullptr);
 }
 
 StringRef Decl::getSemanticBriefComment() const {
-  if (!this->canHaveComment())
+  if (!canHaveComment())
     return StringRef();
 
   auto &eval = getASTContext().evaluator;

lib/IDE/CommentConversion.cpp

@@ -469,6 +469,32 @@ std::string ide::extractPlainTextFromComment(const StringRef Text) {
   return getLineListFromComment(SourceMgr, MC, Text).str();
 }
 
+static DocComment *getCascadingDocComment(swift::markup::MarkupContext &MC,
+                                          const Decl *D) {
+  auto *docD = D->getDocCommentProvidingDecl();
+  if (!docD)
+    return nullptr;
+
+  auto *doc = getSingleDocComment(MC, docD);
+  assert(doc && "getDocCommentProvidingDecl() returned decl with no comment");
+
+  // If the doc-comment is inherited from other decl, add a note about it.
+  if (docD != D) {
+    doc->setDecl(D);
+    if (auto baseD = docD->getDeclContext()->getSelfNominalTypeDecl()) {
+      doc->addInheritanceNote(MC, baseD);
+
+      // If the doc is inherited from protocol requirement, associate the
+      // requirement with the doc-comment.
+      // FIXME: This is to keep the old behavior.
+      if (isa<ProtocolDecl>(baseD))
+        doc->setDecl(docD);
+    }
+  }
+
+  return doc;
+}
+
 bool ide::getDocumentationCommentAsXML(const Decl *D, raw_ostream &OS,
                                        TypeOrExtensionDecl SynthesizedTarget) {
   auto MaybeClangNode = D->getClangNode();
@@ -519,7 +545,7 @@ bool ide::getRawDocumentationComment(const Decl *D, raw_ostream &OS) {
     return true;
   }
 
-  const Decl *docD = getDocCommentProvidingDecl(D);
+  const Decl *docD = D->getDocCommentProvidingDecl();
   if (!docD) {
     return false;
   }

lib/Sema/CMakeLists.txt

@@ -2,6 +2,7 @@
 add_swift_host_library(swiftSema STATIC
   AssociatedTypeInference.cpp
   BuilderTransform.cpp
+  Comment.cpp
   CSApply.cpp
   CSBindings.cpp
   CSSyntacticElement.cpp