ModulePrinting: For decls without doc-comment, we print the doc-comment associated with their conformances, if any.

Inspired by rdar://24409720

Author: nkcsgexi

include/swift/AST/ASTPrinter.h

@@ -29,6 +29,7 @@ namespace swift {
   class Pattern;
   class ExtensionDecl;
   class NominalTypeDecl;
+  class ValueDecl;
   struct PrintOptions;
 
 /// Describes the context in which a name is being printed, which
@@ -253,6 +254,7 @@ class ASTPrinter {
 
   /// To sanitize a malformed utf8 string to a well-formed one.
   static std::string sanitizeUtf8(StringRef Text);
+  static ValueDecl* findConformancesWithDocComment(ValueDecl *VD);
   static bool printTypeInterface(Type Ty, DeclContext *DC, std::string &Result);
   static bool printTypeInterface(Type Ty, DeclContext *DC, llvm::raw_ostream &Out);
 

include/swift/AST/PrintOptions.h

@@ -243,6 +243,10 @@ struct PrintOptions {
     BothAlways,
   };
 
+  /// Whether to print the doc-comment from the conformance if a member decl
+  /// has no associated doc-comment by itself.
+  bool ElevateDocCommentFromConformance = false;
+
   /// Whether to print the content of an extension decl inside the type decl where it
   /// extends from.
   std::function<bool(const ExtensionDecl *)> printExtensionContentAsMembers =
@@ -322,6 +326,7 @@ struct PrintOptions {
     result.SkipDeinit = true;
     result.ExcludeAttrList.push_back(DAK_WarnUnusedResult);
     result.EmptyLineBetweenMembers = true;
+    result.ElevateDocCommentFromConformance = true;
     return result;
   }
 

include/swift/IDE/ModuleInterfacePrinting.h

@@ -43,7 +43,7 @@ typedef OptionSet<ModuleTraversal> ModuleTraversalOptions;
 ArrayRef<StringRef> collectModuleGroups(ModuleDecl *M,
                                         std::vector<StringRef> &Scratch);
 
-void printModuleInterface(ModuleDecl *M,
+void printModuleInterface(ModuleDecl *M, Optional<StringRef> Group,
                           ModuleTraversalOptions TraversalOptions,
                           ASTPrinter &Printer, const PrintOptions &Options,
                           const bool PrintSynthesizedExtensions);

lib/AST/ASTPrinter.cpp

@@ -46,6 +46,7 @@
 #include "llvm/Support/raw_ostream.h"
 #include "llvm/Support/SaveAndRestore.h"
 #include <algorithm>
+#include <queue>
 
 using namespace swift;
 namespace swift {
@@ -708,6 +709,24 @@ 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;
+}
+
 bool ASTPrinter::printTypeInterface(Type Ty, DeclContext *DC,
                                     llvm::raw_ostream &OS) {
   if (!Ty)
@@ -969,11 +988,7 @@ class PrintAST : public ASTVisitor<PrintAST> {
     }
   }
 
-  void printSwiftDocumentationComment(const Decl *D) {
-    auto RC = D->getRawComment();
-    if (RC.isEmpty())
-      return;
-
+  void printRawComment(RawComment RC) {
     indent();
 
     SmallVector<StringRef, 8> Lines;
@@ -991,6 +1006,23 @@ class PrintAST : public ASTVisitor<PrintAST> {
     }
   }
 
+  void printSwiftDocumentationComment(const Decl *D) {
+    auto RC = D->getRawComment();
+    if (RC.isEmpty() && !Options.ElevateDocCommentFromConformance)
+      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);
+    }
+  }
+
   void printDocumentationComment(const Decl *D) {
     if (!Options.PrintDocumentationComments)
       return;

lib/IDE/ModuleInterfacePrinting.cpp

@@ -145,12 +145,13 @@ getUnderlyingClangModuleForImport(ImportDecl *Import) {
   return nullptr;
 }
 
-void swift::ide::printModuleInterface(Module *M,
+void swift::ide::printModuleInterface(Module *M, Optional<StringRef> Group,
                                       ModuleTraversalOptions TraversalOptions,
                                       ASTPrinter &Printer,
                                       const PrintOptions &Options,
                                       const bool PrintSynthesizedExtensions) {
-  printSubmoduleInterface(M, M->getName().str(), ArrayRef<StringRef>(),
+  printSubmoduleInterface(M, M->getName().str(),
+                          Group.hasValue() ? Group.getValue() : ArrayRef<StringRef>(),
                           TraversalOptions, Printer, Options,
                           PrintSynthesizedExtensions);
 }

test/IDE/print_swift_module.swift

@@ -0,0 +1,25 @@
+// RUN: rm -rf %t && mkdir %t
+// RUN: %target-swift-frontend -emit-module-path %t/print_swift_module.swiftmodule -emit-module-doc -emit-module-doc-path %t/print_swift_module.swiftdoc %s
+// RUN: %target-swift-ide-test -print-module -print-interface -no-empty-line-between-members -module-to-print=print_swift_module -I %t -source-filename=%s > %t.syn.txt
+// RUN: FileCheck %s -check-prefix=CHECK1 < %t.syn.txt
+
+public protocol P1 {
+	/// foo1 comment from P1
+	func foo1()
+	/// foo2 comment from P1
+	func foo2()
+}
+public class C1 : P1 {
+	public func foo1() {
+	}
+	/// foo2 comment from C1
+	public func foo2() {
+	}
+}
+
+// CHECK1: 			public class C1 : P1 {
+// CHECK1-NEXT:		/// foo1 comment from P1
+// CHECK1-NEXT:  	public func foo1()
+// CHECK1-NEXT:  	/// foo2 comment from C1
+// CHECK1-NEXT:  	public func foo2()
+// CHECK1-NEXT: }

tools/SourceKit/lib/SwiftLang/SwiftDocSupport.cpp

@@ -676,7 +676,7 @@ static bool getModuleInterfaceInfo(ASTContext &Ctx, StringRef ModuleName,
   SmallString<128> Text;
   llvm::raw_svector_ostream OS(Text);
   AnnotatingPrinter Printer(OS);
-  printModuleInterface(M, TraversalOptions, Printer, Options, false);
+  printModuleInterface(M, None, TraversalOptions, Printer, Options, false);
 
   Info.Text = OS.str();
   Info.TopEntities = std::move(Printer.TopEntities);