Rename getBriefComment -> getSemanticBriefComment

Make it clear that we will walk the comment providing
decls if needed.

Author: hamishknight

include/swift/AST/Decl.h

@@ -1024,8 +1024,9 @@ class alignas(1 << DeclAlignInBits) Decl : public ASTAllocated<Decl> {
 
   Optional<unsigned> getSourceOrder() const;
 
-  /// \returns the brief comment attached to this declaration.
-  StringRef getBriefComment() const;
+  /// \returns The brief comment attached to this declaration, or the brief
+  /// comment attached to the comment providing decl.
+  StringRef getSemanticBriefComment() const;
 
   /// Returns true if there is a Clang AST node associated
   /// with self.

include/swift/AST/FileUnit.h

@@ -161,7 +161,7 @@ class FileUnit : public DeclContext, public ASTAllocated<FileUnit> {
   ///
   /// This function is an implementation detail for comment serialization.
   /// If you just want to get a comment attached to a decl, use
-  /// \c Decl::getRawComment() or \c Decl::getBriefComment().
+  /// \c Decl::getRawComment() or \c Decl::getSemanticBriefComment().
   virtual Optional<CommentInfo>
   getCommentForDecl(const Decl *D) const {
     return None;

include/swift/AST/TypeCheckRequests.h

@@ -4207,9 +4207,10 @@ class RawCommentRequest
   bool isCached() const { return true; }
 };
 
-/// Retrieve the brief portion of a declaration's document comment.
-class BriefCommentRequest
-    : public SimpleRequest<BriefCommentRequest,
+/// Retrieve the brief portion of a declaration's document comment, potentially
+/// walking to find the comment providing decl if needed.
+class SemanticBriefCommentRequest
+    : public SimpleRequest<SemanticBriefCommentRequest,
                            StringRef(const Decl *),
                            RequestFlags::Cached> {
 public:

include/swift/AST/TypeCheckerTypeIDZone.def

@@ -472,7 +472,7 @@ SWIFT_REQUEST(TypeChecker, LocalDiscriminatorsRequest,
 SWIFT_REQUEST(TypeChecker, RawCommentRequest,
               RawComment(const Decl *),
               Cached, NoLocationInfo)
-SWIFT_REQUEST(TypeChecker, BriefCommentRequest,
+SWIFT_REQUEST(TypeChecker, SemanticBriefCommentRequest,
               StringRef(const Decl *),
               Cached, NoLocationInfo)
 SWIFT_REQUEST(TypeChecker, IsNonUserModuleRequest,

lib/AST/DocComment.cpp

@@ -573,19 +573,20 @@ static Optional<StringRef> getDirectBriefComment(const Decl *D) {
   return Ctx.AllocateCopy(BriefStr.str());
 }
 
-StringRef BriefCommentRequest::evaluate(Evaluator &evaluator,
-                                        const Decl *D) const {
+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 finder(getDirectBriefComment);
   auto result = finder.findCommentProvider(D);
   return result ? result->first : StringRef();
 }
 
-StringRef Decl::getBriefComment() const {
+StringRef Decl::getSemanticBriefComment() const {
   if (!this->canHaveComment())
     return StringRef();
 
   auto &eval = getASTContext().evaluator;
-  return evaluateOrDefault(eval, BriefCommentRequest{this}, StringRef());
+  return evaluateOrDefault(eval, SemanticBriefCommentRequest{this},
+                           StringRef());
 }

lib/IDE/CodeCompletionResultBuilder.cpp

@@ -227,7 +227,7 @@ void CodeCompletionResultBuilder::setAssociatedDecl(const Decl *D) {
       }
     }
   } else {
-    setBriefDocComment(AssociatedDecl->getBriefComment());
+    setBriefDocComment(AssociatedDecl->getSemanticBriefComment());
   }
 }
 

lib/Serialization/SerializeDoc.cpp

@@ -357,7 +357,9 @@ static void writeDeclCommentTable(
       if (!D->canHaveComment())
         return false;
 
-      // Skip the decl if it does not have a comment.
+      // Skip the decl if it does not have a comment. Note this means
+      // we'll only serialize "direct" brief comments, but that's okay
+      // because clients can compute the semantic brief comment themselves.
       if (D->getRawComment().Comments.empty())
         return false;
       return true;
@@ -372,9 +374,8 @@ static void writeDeclCommentTable(
           return;
       }
       generator.insert(copyString(USRBuffer.str()),
-                       { ED->getBriefComment(), ED->getRawComment(),
-                         GroupContext.getGroupSequence(ED),
-                         SourceOrder++ });
+                       {ED->getSemanticBriefComment(), ED->getRawComment(),
+                        GroupContext.getGroupSequence(ED), SourceOrder++});
     }
 
     MacroWalking getMacroWalkingBehavior() const override {
@@ -407,9 +408,8 @@ static void writeDeclCommentTable(
       }
 
       generator.insert(copyString(USRBuffer.str()),
-                       { VD->getBriefComment(), D->getRawComment(),
-                         GroupContext.getGroupSequence(VD),
-                         SourceOrder++ });
+                       {VD->getSemanticBriefComment(), D->getRawComment(),
+                        GroupContext.getGroupSequence(VD), SourceOrder++});
       return Action::Continue();
     }
 

tools/SourceKit/lib/SwiftLang/SwiftConformingMethodList.cpp

@@ -119,7 +119,7 @@ deliverResults(SourceKit::ConformingMethodListConsumer &SKConsumer,
             memberElem.BriefComment = RC->getBriefText(ClangContext);
         }
       } else {
-        memberElem.BriefComment = member->getBriefComment();
+        memberElem.BriefComment = member->getSemanticBriefComment();
       }
     }
 

tools/SourceKit/lib/SwiftLang/SwiftTypeContextInfo.cpp

@@ -91,7 +91,7 @@ static void deliverResults(SourceKit::TypeContextInfoConsumer &SKConsumer,
               memberElem.BriefComment = RC->getBriefText(ClangContext);
           }
         } else {
-          memberElem.BriefComment = member->getBriefComment();
+          memberElem.BriefComment = member->getSemanticBriefComment();
         }
       }
 

tools/swift-ide-test/swift-ide-test.cpp

@@ -1178,10 +1178,10 @@ static int printTypeContextInfo(
             VD->getName().print(llvm::outs());
             llvm::outs() << "\n";
 
-            StringRef BriefDoc = VD->getBriefComment();
+            StringRef BriefDoc = VD->getSemanticBriefComment();
             if (!BriefDoc.empty()) {
               llvm::outs() << "     DocBrief: \"";
-              llvm::outs() << VD->getBriefComment();
+              llvm::outs() << VD->getSemanticBriefComment();
               llvm::outs() << "\"\n";
             }
           }
@@ -1246,10 +1246,10 @@ static int printConformingMethodList(
           resultTy.print(llvm::outs());
           llvm::outs() << "\n";
 
-          StringRef BriefDoc = VD->getBriefComment();
+          StringRef BriefDoc = VD->getSemanticBriefComment();
           if (!BriefDoc.empty()) {
             llvm::outs() << "     DocBrief: \"";
-            llvm::outs() << VD->getBriefComment();
+            llvm::outs() << VD->getSemanticBriefComment();
             llvm::outs() << "\"\n";
           }
         }
@@ -3523,7 +3523,7 @@ class ASTCommentPrinter : public ASTWalker {
       OS << " ";
       printRawComment(D->getRawComment());
       OS << " ";
-      printBriefComment(D->getBriefComment());
+      printBriefComment(D->getSemanticBriefComment());
       OS << " ";
       printDocComment(D);
       OS << "\n";
@@ -3538,7 +3538,7 @@ class ASTCommentPrinter : public ASTWalker {
       OS << " ";
       printRawComment(D->getRawComment());
       OS << " ";
-      printBriefComment(D->getBriefComment());
+      printBriefComment(D->getSemanticBriefComment());
       OS << " ";
       printDocComment(D);
       OS << "\n";