[AST] Enhance comment accessing interface. (NFC)

[dlj]

Summary

Previously, these methods were available for looking up comments:

1. getCommentForDecl: returns a FullComment attached to a decl, or any of its redecls, or any of its bases.
2. getRawCommentForAnyRedecl: returns a RawComment attached to a decl, or any of its redecls.
3. getLocalCommentForDeclUncached: returns a FullComment attached to a decl, but also doesn't update the internal cache.

This change reorganizes into these methods:

1. getRawCommentForDecl: returns a RawComment attached to a decl (and nowhere else).
2. getRawCommentForAnyRedecl: as before.
3. getParsedCommentForAnyRedecl: previously called getCommentForDecl.
4. getParsedCommentForDeclUncached: previously getLocalCommentFor....

include/clang/AST/ASTContext.h

public:
   }
 
   void addComment(const RawComment &RC) {
     assert(LangOpts.RetainCommentsFromSystemHeaders ||
            !SourceMgr.isInSystemHeader(RC.getSourceRange().getBegin()));
     Comments.addComment(RC, LangOpts.CommentOpts, BumpAlloc);
   }
 
+  /// \brief Return the RawComment attached to a given declaration, if present.
+  /// Does not check redeclarations or bases.
+  /// Returns nullptr if no comment is attached.
+  const RawComment *getRawCommentForDecl(const Decl *D) const;
+
   /// \brief Return the documentation comment attached to a given declaration.
   /// Returns nullptr if no comment is attached.
   ///
   /// \param OriginalDecl if not nullptr, is set to declaration AST node that
   /// had the comment, if the comment we found comes from a redeclaration.
   const RawComment *
   getRawCommentForAnyRedecl(const Decl *D,
                             const Decl **OriginalDecl = nullptr) const;
 
   /// Return parsed documentation comment attached to a given declaration, its
   /// redeclarations, or its bases.
   /// Returns nullptr if no comment is attached.
   ///
   /// \param PP the Preprocessor used with this TU.  Could be nullptr if
   /// preprocessor is not available.
-  comments::FullComment *getCommentForDecl(const Decl *D,
-                                           const Preprocessor *PP) const;
+  comments::FullComment *
+  getParsedCommentForAnyRedecl(const Decl *D, const Preprocessor *PP) const;
 
-  /// Return parsed documentation comment attached to a given declaration.
-  /// Returns nullptr if no comment is attached. Does not look at any
-  /// redeclarations of the declaration.
-  comments::FullComment *getLocalCommentForDeclUncached(const Decl *D) const;
+  /// \brief Return parsed documentation comment attached to a given
+  /// declaration, and not update the cache. Returns nullptr if no comment
+  /// is attached. Does not look at any redeclarations of the declaration.
+  comments::FullComment *getParsedCommentForDeclUncached(const Decl *D) const;
 
   comments::FullComment *cloneFullComment(comments::FullComment *FC,
                                          const Decl *D) const;
 
 private:
   mutable comments::CommandTraits CommentCommandTraits;
 
   /// \brief Iterator that visits import declarations.

lib/AST/ASTContext.cpp

ASTContext::getRawCommentForDeclCached(const Decl *D) const {
   // Call order swapped to work around ICE in VS2015 RTM (Release Win32)
   // https://connect.microsoft.com/VisualStudio/feedback/details/1741530
   Raw.setKind(RawCommentAndCacheFlags::FromDecl);
   Raw.setRaw(RC);
   return Raw;
 }
 
 const RawComment *
+ASTContext::getRawCommentForDecl(const Decl *D) const {
+  const RawCommentAndCacheFlags &Raw = getRawCommentForDeclCached(D);
+  const RawComment *RC = Raw.getRaw();
+  if (RC) {
+    // Make sure this cache entry wasn't updated by getRawCommentForAnyRedecl.
+    if (Raw.getOriginalDecl() != D)
+      return nullptr;
+    return RC;
+  }
+  assert(Raw.getKind() == RawCommentAndCacheFlags::NoCommentInDecl);
+  return nullptr;
+}
+
+const RawComment *
 ASTContext::getRawCommentForAnyRedecl(const Decl *D,
                                       const Decl **OriginalDecl) const {
   RawCommentAndCacheFlags &OrigRaw = getRawCommentForDeclCached(D);
   if (OrigRaw.getKind() != RawCommentAndCacheFlags::NoCommentInDecl) {
     if (OriginalDecl)
       *OriginalDecl = OrigRaw.getOriginalDecl();
     return OrigRaw.getRaw();
   }
comments::FullComment *ASTContext::cloneFullComment(comments::FullComment *FC,
   if (!ThisDeclInfo->TemplateParameters)
     ThisDeclInfo->TemplateParameters = FC->getDeclInfo()->TemplateParameters;
   comments::FullComment *CFC =
     new (*this) comments::FullComment(FC->getBlocks(),
                                       ThisDeclInfo);
   return CFC;
 }
 
-comments::FullComment *ASTContext::getLocalCommentForDeclUncached(const Decl *D) const {
+comments::FullComment *
+ASTContext::getParsedCommentForDeclUncached(const Decl *D) const {
   const RawComment *RC = getRawCommentForDeclNoCache(D);
   return RC ? RC->parse(*this, nullptr, D) : nullptr;
 }
 
 comments::FullComment *
-ASTContext::getCommentForDecl(const Decl *D,
+ASTContext::getParsedCommentForAnyRedecl(const Decl *D,
                                          const Preprocessor *PP) const {
   if (D->isInvalidDecl())
     return nullptr;
   D = adjustDeclToTemplate(D);
   
   const Decl *Canonical = D->getCanonicalDecl();
   llvm::DenseMap<const Decl *, comments::FullComment *>::iterator Pos =
       ParsedComments.find(Canonical);
   
ASTContext::getParsedCommentForAnyRedecl(const Decl *D,
   
   const RawComment *RC = getRawCommentForAnyRedecl(D, &OriginalDecl);
   if (!RC) {
     if (isa<ObjCMethodDecl>(D) || isa<FunctionDecl>(D)) {
       SmallVector<const NamedDecl*, 8> Overridden;
       const ObjCMethodDecl *OMD = dyn_cast<ObjCMethodDecl>(D);
       if (OMD && OMD->isPropertyAccessor())
         if (const ObjCPropertyDecl *PDecl = OMD->findPropertyDecl())
-          if (comments::FullComment *FC = getCommentForDecl(PDecl, PP))
+          if (comments::FullComment *FC =
+                  getParsedCommentForAnyRedecl(PDecl, PP))
             return cloneFullComment(FC, D);
       if (OMD)
         addRedeclaredMethods(OMD, Overridden);
       getOverriddenMethods(dyn_cast<NamedDecl>(D), Overridden);
       for (unsigned i = 0, e = Overridden.size(); i < e; i++)
-        if (comments::FullComment *FC = getCommentForDecl(Overridden[i], PP))
+        if (comments::FullComment *FC =
+                getParsedCommentForAnyRedecl(Overridden[i], PP))
           return cloneFullComment(FC, D);
     }
     else if (const TypedefNameDecl *TD = dyn_cast<TypedefNameDecl>(D)) {
       // Attach any tag type's documentation to its typedef if latter
       // does not have one of its own.
       QualType QT = TD->getUnderlyingType();
       if (const TagType *TT = QT->getAs<TagType>())
         if (const Decl *TD = TT->getDecl())
-          if (comments::FullComment *FC = getCommentForDecl(TD, PP))
+          if (comments::FullComment *FC = getParsedCommentForAnyRedecl(TD, PP))
             return cloneFullComment(FC, D);
     }
     else if (const ObjCInterfaceDecl *IC = dyn_cast<ObjCInterfaceDecl>(D)) {
       while (IC->getSuperClass()) {
         IC = IC->getSuperClass();
-        if (comments::FullComment *FC = getCommentForDecl(IC, PP))
+        if (comments::FullComment *FC = getParsedCommentForAnyRedecl(IC, PP))
           return cloneFullComment(FC, D);
       }
     }
     else if (const ObjCCategoryDecl *CD = dyn_cast<ObjCCategoryDecl>(D)) {
       if (const ObjCInterfaceDecl *IC = CD->getClassInterface())
-        if (comments::FullComment *FC = getCommentForDecl(IC, PP))
+        if (comments::FullComment *FC = getParsedCommentForAnyRedecl(IC, PP))
           return cloneFullComment(FC, D);
     }
     else if (const CXXRecordDecl *RD = dyn_cast<CXXRecordDecl>(D)) {
       if (!(RD = RD->getDefinition()))
         return nullptr;
       // Check non-virtual bases.
       for (const auto &I : RD->bases()) {
         if (I.isVirtual() || (I.getAccessSpecifier() != AS_public))
           continue;
         QualType Ty = I.getType();
         if (Ty.isNull())
           continue;
         if (const CXXRecordDecl *NonVirtualBase = Ty->getAsCXXRecordDecl()) {
           if (!(NonVirtualBase= NonVirtualBase->getDefinition()))
             continue;
-        
-          if (comments::FullComment *FC = getCommentForDecl((NonVirtualBase), PP))
+          if (comments::FullComment *FC =
+                  getParsedCommentForAnyRedecl((NonVirtualBase), PP))
             return cloneFullComment(FC, D);
         }
       }
       // Check virtual bases.
       for (const auto &I : RD->vbases()) {
         if (I.getAccessSpecifier() != AS_public)
           continue;
         QualType Ty = I.getType();
         if (Ty.isNull())
           continue;
         if (const CXXRecordDecl *VirtualBase = Ty->getAsCXXRecordDecl()) {
           if (!(VirtualBase= VirtualBase->getDefinition()))
             continue;
-          if (comments::FullComment *FC = getCommentForDecl((VirtualBase), PP))
+          if (comments::FullComment *FC =
+                  getParsedCommentForAnyRedecl((VirtualBase), PP))
             return cloneFullComment(FC, D);
         }
       }
     }
     return nullptr;
   }
   
   // If the RawComment was attached to other redeclaration of this Decl, we
   // should parse the comment in context of that other Decl.  This is important
   // because comments can contain references to parameter names which can be
   // different across redeclarations.
   if (D != OriginalDecl)
-    return getCommentForDecl(OriginalDecl, PP);
+    return getParsedCommentForAnyRedecl(OriginalDecl, PP);
 
   comments::FullComment *FC = RC->parse(*this, PP, D);
   ParsedComments[Canonical] = FC;
   return FC;
 }
 
 void 
 ASTContext::CanonicalTemplateTemplateParm::Profile(llvm::FoldingSetNodeID &ID, 

lib/AST/ASTDumper.cpp

dumpChild([=] {
 
     ConstDeclVisitor<ASTDumper>::Visit(D);
 
     for (Decl::attr_iterator I = D->attr_begin(), E = D->attr_end(); I != E;
          ++I)
       dumpAttr(*I);
 
     if (const FullComment *Comment =
-            D->getASTContext().getLocalCommentForDeclUncached(D))
+            D->getASTContext().getParsedCommentForDeclUncached(D))
       dumpFullComment(Comment);
 
     // Decls within functions are visited by the body.
     if (!isa<FunctionDecl>(*D) && !isa<ObjCMethodDecl>(*D) &&
         hasNodes(dyn_cast<DeclContext>(D)))
       dumpDeclContext(cast<DeclContext>(D));
   });
 }

lib/Sema/SemaDecl.cpp

if (!Comments.empty() &&
     // There is at least one comment that not attached to a decl.
     // Maybe it should be attached to one of these decls?
     //
     // Note that this way we pick up not only comments that precede the
     // declaration, but also comments that *follow* the declaration -- thanks to
     // the lookahead in the lexer: we've consumed the semicolon and looked
     // ahead through comments.
     for (unsigned i = 0, e = Group.size(); i != e; ++i)
-      Context.getCommentForDecl(Group[i], &PP);
+      Context.getParsedCommentForAnyRedecl(Group[i], &PP);
   }
 }
 
 /// ActOnParamDeclarator - Called from Parser::ParseFunctionDeclarator()
 /// to introduce parameters into function prototype scope.
 Decl *Sema::ActOnParamDeclarator(Scope *S, Declarator &D) {
   const DeclSpec &DS = D.getDeclSpec();
 

tools/libclang/CXComment.cpp

 CXComment clang_Cursor_getParsedComment(CXCursor C) {
   using namespace clang::cxcursor;
 
   if (!clang_isDeclaration(C.kind))
     return createCXComment(nullptr, nullptr);
 
   const Decl *D = getCursorDecl(C);
   const ASTContext &Context = getCursorContext(C);
-  const FullComment *FC = Context.getCommentForDecl(D, /*PP=*/nullptr);
+  const FullComment *FC =
+      Context.getParsedCommentForAnyRedecl(D, /*PP=*/nullptr);
 
   return createCXComment(FC, getCursorTU(C));
 }
 
 enum CXCommentKind clang_Comment_getKind(CXComment CXC) {
   const Comment *C = getASTNode(CXC);
   if (!C)
     return CXComment_Null;
CXString clang_FullComment_getAsXML(CXComment CXC) {
   if (!TU->CommentToXML)
     TU->CommentToXML = new clang::index::CommentToXMLConverter();
 
   SmallString<1024> XML;
   TU->CommentToXML
       ->convertCommentToXML(FC, XML, cxtu::getASTUnit(TU)->getASTContext());
   return cxstring::createDup(XML.str());
 }
-