Merge pull request #24813 from rintaro/comment-refactor

[AST] Inherit doc-brief comment from protocol, superclass, and requirement

Author: rintaro

include/swift/AST/ASTPrinter.h

@@ -286,7 +286,6 @@ class ASTPrinter {
 
   /// To sanitize a malformed utf8 string to a well-formed one.
   static std::string sanitizeUtf8(StringRef Text);
-  static ValueDecl* findConformancesWithDocComment(ValueDecl *VD);
 
 private:
   virtual void anchor();

include/swift/AST/Comment.h

@@ -18,20 +18,26 @@
 
 namespace swift {
 class Decl;
-class DocComment;
+class TypeDecl;
 struct RawComment;
 
 class DocComment {
   const Decl *D;
-  const swift::markup::Document *Doc = nullptr;
-  const swift::markup::CommentParts Parts;
+  swift::markup::Document *Doc = nullptr;
+  swift::markup::CommentParts Parts;
 
-public:
   DocComment(const Decl *D, swift::markup::Document *Doc,
              swift::markup::CommentParts Parts)
       : D(D), Doc(Doc), Parts(Parts) {}
 
+public:
+  static DocComment *create(const Decl *D, swift::markup::MarkupContext &MC,
+                            RawComment RC);
+
+  void addInheritanceNote(swift::markup::MarkupContext &MC, TypeDecl *base);
+
   const Decl *getDecl() const { return D; }
+  void setDecl(const Decl *D) { this->D = D; }
 
   const swift::markup::Document *getDocument() const { return Doc; }
 
@@ -87,19 +93,23 @@ class DocComment {
 };
 
 /// Get a parsed documentation comment for the declaration, if there is one.
-Optional<DocComment *>getSingleDocComment(swift::markup::MarkupContext &Context,
-                                          const Decl *D);
+DocComment *getSingleDocComment(swift::markup::MarkupContext &Context,
+                                const Decl *D);
+
+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.
-Optional<DocComment *> getCascadingDocComment(swift::markup::MarkupContext &MC,
-                                             const Decl *D);
+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,
                     swift::markup::MarkupASTNode *Node);
+
+/// Extract brief comment from \p RC, and print it to \p OS .
+void printBriefComment(RawComment RC, llvm::raw_ostream &OS);
 } // namespace swift
 
 #endif // LLVM_SWIFT_AST_COMMENT_H
-

include/swift/AST/PrintOptions.h

@@ -349,7 +349,7 @@ struct PrintOptions {
 
   /// Whether to print the doc-comment from the conformance if a member decl
   /// has no associated doc-comment by itself.
-  bool ElevateDocCommentFromConformance = false;
+  bool CascadeDocComment = false;
 
   /// Whether to print the content of an extension decl inside the type decl where it
   /// extends from.
@@ -480,7 +480,7 @@ struct PrintOptions {
     result.SkipDeinit = true;
     result.ExcludeAttrList.push_back(DAK_DiscardableResult);
     result.EmptyLineBetweenMembers = true;
-    result.ElevateDocCommentFromConformance = true;
+    result.CascadeDocComment = true;
     result.ShouldQualifyNestedDeclarations =
         QualifyNestedDeclarations::Always;
     result.PrintDocumentationComments = true;

lib/AST/ASTPrinter.cpp

@@ -19,6 +19,7 @@
 #include "swift/AST/ASTMangler.h"
 #include "swift/AST/ASTVisitor.h"
 #include "swift/AST/Attr.h"
+#include "swift/AST/Comment.h"
 #include "swift/AST/Decl.h"
 #include "swift/AST/Expr.h"
 #include "swift/AST/GenericEnvironment.h"
@@ -250,24 +251,6 @@ std::string ASTPrinter::sanitizeUtf8(StringRef Text) {
   return Builder.str();
 }
 
-ValueDecl* ASTPrinter::findConformancesWithDocComment(ValueDecl *VD) {
-  assert(VD->getRawComment().isEmpty());
-  std::queue<ValueDecl*> AllConformances;
-  AllConformances.push(VD);
-  while (!AllConformances.empty()) {
-    auto *VD = AllConformances.front();
-    AllConformances.pop();
-    if (VD->getRawComment().isEmpty()) {
-      for (auto *Req : VD->getSatisfiedProtocolRequirements()) {
-        AllConformances.push(Req);
-      }
-    } else {
-      return VD;
-    }
-  }
-  return nullptr;
-}
-
 void ASTPrinter::anchor() {}
 
 void ASTPrinter::printIndent() {
@@ -569,20 +552,14 @@ class PrintAST : public ASTVisitor<PrintAST> {
   }
 
   void printSwiftDocumentationComment(const Decl *D) {
+    if (Options.CascadeDocComment)
+      D = getDocCommentProvidingDecl(D);
+    if (!D)
+      return;
     auto RC = D->getRawComment();
-    if (RC.isEmpty() && !Options.ElevateDocCommentFromConformance)
+    if (RC.isEmpty())
       return;
-
-    if (RC.isEmpty()) {
-      if (auto *VD = dyn_cast<ValueDecl>(D)) {
-        if (auto *Req = ASTPrinter::findConformancesWithDocComment(
-            const_cast<ValueDecl*>(VD))) {
-          printRawComment(Req->getRawComment());
-        }
-      }
-    } else {
-      printRawComment(RC);
-    }
+    printRawComment(RC);
   }
 
   void printDocumentationComment(const Decl *D) {