Drop SerializedOK parameter from getRawComment

It doesn't seem like there's any client that's
actually taking advantage of setting it to `false`,
and its default value of `false` is more likely
than not going to cause clients to accidentally
miss comments that they may want. In fact, this
was exactly the case for code completion's brief
field. Finally, the parameter wasn't even
consistently applied, as we would attempt to
deserialize swiftdoc comments even if it were
`false`.

Author: hamishknight

include/swift/AST/Comment.h

@@ -93,27 +93,16 @@ class DocComment {
 };
 
 /// Get a parsed documentation comment for the declaration, if there is one.
-///
-/// \param AllowSerialized Allow loading serialized doc comment data, including
-/// comment ranges.
 DocComment *getSingleDocComment(swift::markup::MarkupContext &Context,
-                                const Decl *D, bool AllowSerialized = false);
+                                const Decl *D);
 
 /// Get the declaration that actually provides a doc comment for another.
-///
-/// \param AllowSerialized Allow loading serialized doc comment data, including
-/// comment ranges.
-const Decl *getDocCommentProvidingDecl(const Decl *D,
-                                       bool AllowSerialized = false);
+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.
-///
-/// \param AllowSerialized Allow loading serialized doc comment data, including
-/// comment ranges.
 DocComment *getCascadingDocComment(swift::markup::MarkupContext &MC,
-                                   const Decl *D,
-                                   bool AllowSerialized = false);
+                                   const Decl *D);
 
 /// Extract comments parts from the given Markup node.
 swift::markup::CommentParts

include/swift/AST/Decl.h

@@ -1015,7 +1015,7 @@ class alignas(1 << DeclAlignInBits) Decl : public ASTAllocated<Decl> {
   }
 
   /// \returns the unparsed comment attached to this declaration.
-  RawComment getRawComment(bool SerializedOK = false) const;
+  RawComment getRawComment() const;
 
   Optional<StringRef> getGroupName() const;
 

lib/AST/DocComment.cpp

@@ -381,33 +381,31 @@ void DocComment::addInheritanceNote(swift::markup::MarkupContext &MC,
 }
 
 DocComment *swift::getSingleDocComment(swift::markup::MarkupContext &MC,
-                                       const Decl *D, bool AllowSerialized) {
+                                       const Decl *D) {
   PrettyStackTraceDecl StackTrace("parsing comment for", D);
 
-  auto RC = D->getRawComment(AllowSerialized);
+  auto RC = D->getRawComment();
   if (RC.isEmpty())
     return nullptr;
   return DocComment::create(D, MC, RC);
 }
 
 namespace {
-const ValueDecl *findOverriddenDeclWithDocComment(const ValueDecl *VD,
-                                                  bool AllowSerialized = true) {
+const ValueDecl *findOverriddenDeclWithDocComment(const ValueDecl *VD) {
   // Only applies to class member.
   if (!VD->getDeclContext()->getSelfClassDecl())
     return nullptr;
 
   while (auto *baseDecl = VD->getOverriddenDecl()) {
-    if (!baseDecl->getRawComment(AllowSerialized).isEmpty())
+    if (!baseDecl->getRawComment().isEmpty())
       return baseDecl;
     VD = baseDecl;
   }
 
   return nullptr;
 }
 
-const ValueDecl *findDefaultProvidedDeclWithDocComment(const ValueDecl *VD,
-                                                       bool AllowSerialized = false) {
+const ValueDecl *findDefaultProvidedDeclWithDocComment(const ValueDecl *VD) {
   auto protocol = VD->getDeclContext()->getExtendedProtocolDecl();
   // Only applies to protocol extension member.
   if (!protocol)
@@ -423,8 +421,7 @@ const ValueDecl *findDefaultProvidedDeclWithDocComment(const ValueDecl *VD,
 
   for (auto *member : members) {
     if (!isa<ProtocolDecl>(member->getDeclContext()) ||
-        !member->isProtocolRequirement() ||
-        member->getRawComment(AllowSerialized).isEmpty())
+        !member->isProtocolRequirement() || member->getRawComment().isEmpty())
       continue;
     if (requirement)
       // Found two or more decls with doc-comment.
@@ -435,12 +432,11 @@ const ValueDecl *findDefaultProvidedDeclWithDocComment(const ValueDecl *VD,
   return requirement;
 }
 
-const ValueDecl *findRequirementDeclWithDocComment(const ValueDecl *VD,
-                                                   bool AllowSerialized = false) {
+const ValueDecl *findRequirementDeclWithDocComment(const ValueDecl *VD) {
   std::queue<const ValueDecl *> requirements;
   while (true) {
     for (auto *req : VD->getSatisfiedProtocolRequirements()) {
-      if (!req->getRawComment(AllowSerialized).isEmpty())
+      if (!req->getRawComment().isEmpty())
         return req;
       else
         requirements.push(req);
@@ -453,38 +449,36 @@ const ValueDecl *findRequirementDeclWithDocComment(const ValueDecl *VD,
 }
 } // namespace
 
-const Decl *swift::getDocCommentProvidingDecl(const Decl *D,
-                                              bool AllowSerialized) {
+const Decl *swift::getDocCommentProvidingDecl(const Decl *D) {
   if (!D->canHaveComment())
     return nullptr;
 
-  if (!D->getRawComment(AllowSerialized).isEmpty())
+  if (!D->getRawComment().isEmpty())
     return D;
 
   auto *VD = dyn_cast<ValueDecl>(D);
   if (!VD)
     return nullptr;
 
-  if (auto *overridden = findOverriddenDeclWithDocComment(VD, AllowSerialized))
+  if (auto *overridden = findOverriddenDeclWithDocComment(VD))
     return overridden;
 
-  if (auto *requirement = findDefaultProvidedDeclWithDocComment(VD, AllowSerialized))
+  if (auto *requirement = findDefaultProvidedDeclWithDocComment(VD))
     return requirement;
 
-  if (auto *requirement = findRequirementDeclWithDocComment(VD, AllowSerialized))
+  if (auto *requirement = findRequirementDeclWithDocComment(VD))
     return requirement;
 
   return nullptr;
 }
 
-DocComment *
-swift::getCascadingDocComment(swift::markup::MarkupContext &MC, const Decl *D,
-                              bool AllowSerialized) {
-  auto *docD = getDocCommentProvidingDecl(D, AllowSerialized);
+DocComment *swift::getCascadingDocComment(swift::markup::MarkupContext &MC,
+                                          const Decl *D) {
+  auto *docD = getDocCommentProvidingDecl(D);
   if (!docD)
     return nullptr;
 
-  auto *doc = getSingleDocComment(MC, docD, AllowSerialized);
+  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.

lib/AST/Module.cpp

@@ -1440,7 +1440,7 @@ SourceFile::getExternalRawLocsForDecl(const Decl *D) const {
   Result.SourceFilePath = SM.getIdentifierForBuffer(BufferID);
   setLoc(Result.Loc, MainLoc);
   if (!InGeneratedBuffer) {
-    for (const auto &SRC : D->getRawComment(/*SerializedOK=*/false).Comments) {
+    for (const auto &SRC : D->getRawComment().Comments) {
       Result.DocRanges.emplace_back(ExternalSourceLocs::RawLoc(),
                                     SRC.Range.getByteLength());
       setLoc(Result.DocRanges.back().first, SRC.Range.getStart());

lib/AST/RawComment.cpp

@@ -130,16 +130,14 @@ static RawComment toRawComment(ASTContext &Context, CharSourceRange Range) {
   return Result;
 }
 
-RawComment Decl::getRawComment(bool SerializedOK) const {
+RawComment Decl::getRawComment() const {
   if (!this->canHaveComment())
     return RawComment();
 
   // Check the cache in ASTContext.
   auto &Context = getASTContext();
   if (Optional<std::pair<RawComment, bool>> RC = Context.getRawComment(this)) {
-    auto P = RC.value();
-    if (!SerializedOK || P.second)
-      return P.first;
+    return RC.value().first;
   }
 
   // Check the declaration itself.
@@ -157,26 +155,24 @@ RawComment Decl::getRawComment(bool SerializedOK) const {
 
   switch (Unit->getKind()) {
   case FileUnitKind::SerializedAST: {
-    if (SerializedOK) {
-      auto *CachedLocs = getSerializedLocs();
-      if (!CachedLocs->DocRanges.empty()) {
-        SmallVector<SingleRawComment, 4> SRCs;
-        for (const auto &Range : CachedLocs->DocRanges) {
-          if (Range.isValid()) {
-            SRCs.push_back({Range, Context.SourceMgr});
-          } else {
-            // if we've run into an invalid range, don't bother trying to load
-            // any of the other comments
-            SRCs.clear();
-            break;
-          }
+    auto *CachedLocs = getSerializedLocs();
+    if (!CachedLocs->DocRanges.empty()) {
+      SmallVector<SingleRawComment, 4> SRCs;
+      for (const auto &Range : CachedLocs->DocRanges) {
+        if (Range.isValid()) {
+          SRCs.push_back({Range, Context.SourceMgr});
+        } else {
+          // if we've run into an invalid range, don't bother trying to load
+          // any of the other comments
+          SRCs.clear();
+          break;
         }
+      }
 
-        if (!SRCs.empty()) {
-          auto RC = RawComment(Context.AllocateCopy(llvm::makeArrayRef(SRCs)));
-          Context.setRawComment(this, RC, true);
-          return RC;
-        }
+      if (!SRCs.empty()) {
+        auto RC = RawComment(Context.AllocateCopy(llvm::makeArrayRef(SRCs)));
+        Context.setRawComment(this, RC, true);
+        return RC;
       }
     }
 

lib/IDE/IDETypeChecking.cpp

@@ -294,8 +294,9 @@ struct SynthesizedExtensionAnalyzer::Implementation {
                ExtensionDecl *EnablingExt, NormalProtocolConformance *Conf) {
     SynthesizedExtensionInfo Result(IsSynthesized, EnablingExt);
     ExtensionMergeInfo MergeInfo;
-    MergeInfo.Unmergable = !Ext->getRawComment(/*SerializedOK=*/false).isEmpty() || // With comments
-                           Ext->getAttrs().hasAttribute<AvailableAttr>(); // With @available
+    MergeInfo.Unmergable =
+        !Ext->getRawComment().isEmpty() ||             // With comments
+        Ext->getAttrs().hasAttribute<AvailableAttr>(); // With @available
     MergeInfo.InheritsCount = countInherits(Ext);
 
     // There's (up to) two extensions here: the extension with the items that we

lib/IDE/ModuleInterfacePrinting.cpp

@@ -829,7 +829,7 @@ static SourceLoc getDeclStartPosition(SourceFile &File) {
   for (auto D : File.getTopLevelDecls()) {
     if (tryUpdateStart(D->getStartLoc())) {
       tryUpdateStart(D->getAttrs().getStartLoc());
-      auto RawComment = D->getRawComment(/*SerializedOK=*/false);
+      auto RawComment = D->getRawComment();
       if (!RawComment.isEmpty())
         tryUpdateStart(RawComment.Comments.front().Range.getStart());
     }

lib/IDE/SwiftSourceDocInfo.cpp

@@ -198,7 +198,7 @@ bool NameMatcher::handleCustomAttrs(Decl *D) {
 
 ASTWalker::PreWalkAction NameMatcher::walkToDeclPre(Decl *D) {
   // Handle occurrences in any preceding doc comments
-  RawComment R = D->getRawComment(/*SerializedOK=*/false);
+  RawComment R = D->getRawComment();
   if (!R.isEmpty()) {
     for(SingleRawComment C: R.Comments) {
       while(!shouldSkip(C.Range))

lib/IDE/SyntaxModel.cpp

@@ -514,7 +514,7 @@ CharSourceRange innerCharSourceRangeFromSourceRange(const SourceManager &SM,
 static void setDecl(SyntaxStructureNode &N, Decl *D) {
   N.Dcl = D;
   N.Attrs = D->getOriginalAttrs();
-  N.DocRange = D->getRawComment(/*SerializedOK=*/false).getCharSourceRange();
+  N.DocRange = D->getRawComment().getCharSourceRange();
 }
 
 } // anonymous namespace

lib/SymbolGraphGen/Symbol.cpp

@@ -210,8 +210,8 @@ void Symbol::serializeRange(size_t InitialIndentation,
 
 const ValueDecl *Symbol::getDeclInheritingDocs() const {
   // get the decl that would provide docs for this symbol
-  const auto *DocCommentProvidingDecl = dyn_cast_or_null<ValueDecl>(
-      getDocCommentProvidingDecl(D, /*AllowSerialized=*/true));
+  const auto *DocCommentProvidingDecl =
+      dyn_cast_or_null<ValueDecl>(getDocCommentProvidingDecl(D));
 
   // if the decl is the same as the one for this symbol, we're not
   // inheriting docs, so return null. however, if this symbol is
@@ -356,13 +356,13 @@ void Symbol::serializeDocComment(llvm::json::OStream &OS) const {
 
   const auto *DocCommentProvidingDecl = D;
   if (!Graph->Walker.Options.SkipInheritedDocs) {
-    DocCommentProvidingDecl = dyn_cast_or_null<ValueDecl>(
-        getDocCommentProvidingDecl(D, /*AllowSerialized=*/true));
+    DocCommentProvidingDecl =
+        dyn_cast_or_null<ValueDecl>(getDocCommentProvidingDecl(D));
     if (!DocCommentProvidingDecl) {
       DocCommentProvidingDecl = D;
     }
   }
-  auto RC = DocCommentProvidingDecl->getRawComment(/*SerializedOK=*/true);
+  auto RC = DocCommentProvidingDecl->getRawComment();
   if (RC.isEmpty()) {
     return;
   }

lib/SymbolGraphGen/SymbolGraph.cpp

@@ -705,8 +705,7 @@ bool SymbolGraph::isImplicitlyPrivate(const Decl *D,
     // If we've been asked to skip protocol implementations, filter them out here.
     if (Walker.Options.SkipProtocolImplementations && getProtocolRequirement(VD)) {
       // Allow them to stay if they have their own doc comment
-      const auto *DocCommentProvidingDecl =
-        getDocCommentProvidingDecl(VD, /*AllowSerialized=*/true);
+      const auto *DocCommentProvidingDecl = getDocCommentProvidingDecl(VD);
       if (DocCommentProvidingDecl != VD)
         return true;
     }