[AST] Rename some Redeclarable functions to reduce confusion

[rsmith]

include/clang/AST/Redeclarable.h

106

I think this is still a confusing name, because it points either to the previous declaration or to the latest one. How about just calling this Link? Or if you want to be more explicit, PrevOrLatest. (But that name is still slightly inaccurate due to the UninitializedLatest case.)

117–120

This would be simpler and more obvious as:

return Prev.is<KnownLatest>() ||
       // FIXME: 'template' is required on the next line due to an
       // apparent clang bug.
       Prev.get<NotKnownLatest>().template is<UninitializedLatest>());

[MaskRay]

Rename Next to Link as per rsmith

include/clang/AST/Redeclarable.h

 // Some notes on redeclarables:
 //
 //  - Every redeclarable is on a circular linked list.
 //
 //  - Every decl has a pointer to the first element of the chain _and_ a
 //    DeclLink that may point to one of 3 possible states:
 //      - the "previous" (temporal) element in the chain
 //      - the "latest" (temporal) element in the chain
-//      - the an "uninitialized-latest" value (when newly-constructed)
+//      - the "uninitialized-latest" value (when newly-constructed)
 //
 //  - The first element is also often called the canonical element. Every
 //    element has a pointer to it so that "getCanonical" can be fast.
 //
 //  - Most links in the chain point to previous, except the link out of
 //    the first; it points to latest.
 //
 //  - Elements are called "first", "previous", "latest" or
 //    "most-recent" when referring to temporal order: order of addition
 //    to the chain.
 //
-//  - To make matters confusing, the DeclLink type uses the term "next"
-//    for its pointer-storage internally (thus functions like
-//    NextIsPrevious). It's easiest to just ignore the implementation of
-//    DeclLink when making sense of the redeclaration chain.
+//  - It's easiest to just ignore the implementation of DeclLink when making
+//    sense of the redeclaration chain.
 //
 //  - There's also a "definition" link for several types of
 //    redeclarable, where only one definition should exist at any given
 //    time (and the defn pointer is stored in the decl's "data" which
 //    is copied to every element on the chain when it's changed).
 //
 //    Here is some ASCII art:
 //
class DeclLink {
 
     using Previous = Decl *;
 
     /// A pointer to either an uninitialized latest declaration (where either
     /// we've not yet set the previous decl or there isn't one), or to a known
     /// previous declaration.
     using NotKnownLatest = llvm::PointerUnion<Previous, UninitializedLatest>;
 
-    mutable llvm::PointerUnion<NotKnownLatest, KnownLatest> Next;
+    mutable llvm::PointerUnion<NotKnownLatest, KnownLatest> Prev;
 
   public:
     enum PreviousTag { PreviousLink };
     enum LatestTag { LatestLink };
 
     DeclLink(LatestTag, const ASTContext &Ctx)
-        : Next(NotKnownLatest(reinterpret_cast<UninitializedLatest>(&Ctx))) {}
-    DeclLink(PreviousTag, decl_type *D) : Next(NotKnownLatest(Previous(D))) {}
+        : Prev(NotKnownLatest(reinterpret_cast<UninitializedLatest>(&Ctx))) {}
+    DeclLink(PreviousTag, decl_type *D) : Prev(NotKnownLatest(Previous(D))) {}
 
-    bool NextIsPrevious() const {
-      return Next.is<NotKnownLatest>() &&
+    bool isFirst() const {
+      return !(Prev.is<NotKnownLatest>() &&
                // FIXME: 'template' is required on the next line due to an
                // apparent clang bug.
-             Next.get<NotKnownLatest>().template is<Previous>();
+               Prev.get<NotKnownLatest>().template is<Previous>());
     }
 
-    bool NextIsLatest() const { return !NextIsPrevious(); }
-
-    decl_type *getNext(const decl_type *D) const {
-      if (Next.is<NotKnownLatest>()) {
-        NotKnownLatest NKL = Next.get<NotKnownLatest>();
+    decl_type *getPrevious(const decl_type *D) const {
+      if (Prev.is<NotKnownLatest>()) {
+        NotKnownLatest NKL = Prev.get<NotKnownLatest>();
         if (NKL.is<Previous>())
           return static_cast<decl_type*>(NKL.get<Previous>());
 
         // Allocate the generational 'most recent' cache now, if needed.
-        Next = KnownLatest(*reinterpret_cast<const ASTContext *>(
+        Prev = KnownLatest(*reinterpret_cast<const ASTContext *>(
                                NKL.get<UninitializedLatest>()),
                            const_cast<decl_type *>(D));
       }
 
-      return static_cast<decl_type*>(Next.get<KnownLatest>().get(D));
+      return static_cast<decl_type*>(Prev.get<KnownLatest>().get(D));
     }
 
     void setPrevious(decl_type *D) {
-      assert(NextIsPrevious() && "decl became non-canonical unexpectedly");
-      Next = Previous(D);
+      assert(!isFirst() && "decl became non-canonical unexpectedly");
+      Prev = Previous(D);
     }
 
     void setLatest(decl_type *D) {
-      assert(NextIsLatest() && "decl became canonical unexpectedly");
-      if (Next.is<NotKnownLatest>()) {
-        NotKnownLatest NKL = Next.get<NotKnownLatest>();
-        Next = KnownLatest(*reinterpret_cast<const ASTContext *>(
+      assert(isFirst() && "decl became canonical unexpectedly");
+      if (Prev.is<NotKnownLatest>()) {
+        NotKnownLatest NKL = Prev.get<NotKnownLatest>();
+        Prev = KnownLatest(*reinterpret_cast<const ASTContext *>(
                                NKL.get<UninitializedLatest>()),
                            D);
       } else {
-        auto Latest = Next.get<KnownLatest>();
+        auto Latest = Prev.get<KnownLatest>();
         Latest.set(D);
-        Next = Latest;
+        Prev = Latest;
       }
     }
 
-    void markIncomplete() { Next.get<KnownLatest>().markIncomplete(); }
+    void markIncomplete() { Prev.get<KnownLatest>().markIncomplete(); }
 
     Decl *getLatestNotUpdated() const {
-      assert(NextIsLatest() && "expected a canonical decl");
-      if (Next.is<NotKnownLatest>())
+      assert(isFirst() && "expected a canonical decl");
+      if (Prev.is<NotKnownLatest>())
         return nullptr;
-      return Next.get<KnownLatest>().getNotUpdated();
+      return Prev.get<KnownLatest>().getNotUpdated();
     }
   };
 
   static DeclLink PreviousDeclLink(decl_type *D) {
     return DeclLink(DeclLink::PreviousLink, D);
   }
 
   static DeclLink LatestDeclLink(const ASTContext &Ctx) {
     return DeclLink(DeclLink::LatestLink, Ctx);
   }
 
   /// Points to the next redeclaration in the chain.
   ///
-  /// If NextIsPrevious() is true, this is a link to the previous declaration
-  /// of this same Decl. If NextIsLatest() is true, this is the first
+  /// If isFirst() is false, this is a link to the previous declaration
+  /// of this same Decl. If isFirst() is true, this is the first
   /// declaration and Link points to the latest declaration. For example:
   ///
   ///  #1 int f(int x, int y = 1); // <pointer to #3, true>
   ///  #2 int f(int x = 0, int y); // <pointer to #1, false>
   ///  #3 int f(int x, int y) { return x + y; } // <pointer to #2, false>
   ///
   /// If there is only one declaration, it is <pointer to self, true>
   DeclLink RedeclLink;
 
   decl_type *First;
 
   decl_type *getNextRedeclaration() const {
-    return RedeclLink.getNext(static_cast<const decl_type *>(this));
+    return RedeclLink.getPrevious(static_cast<const decl_type *>(this));
   }
 
 public:
   friend class ASTDeclReader;
   friend class ASTDeclWriter;
 
   Redeclarable(const ASTContext &Ctx)
       : RedeclLink(LatestDeclLink(Ctx)),
         First(static_cast<decl_type *>(this)) {}
 
   /// Return the previous declaration of this declaration or NULL if this
   /// is the first declaration.
   decl_type *getPreviousDecl() {
-    if (RedeclLink.NextIsPrevious())
+    if (!RedeclLink.isFirst())
       return getNextRedeclaration();
     return nullptr;
   }
   const decl_type *getPreviousDecl() const {
     return const_cast<decl_type *>(
                  static_cast<const decl_type*>(this))->getPreviousDecl();
   }
 
   /// Return the first declaration of this declaration or itself if this
   /// is the only declaration.
   decl_type *getFirstDecl() { return First; }
 
   /// Return the first declaration of this declaration or itself if this
   /// is the only declaration.
   const decl_type *getFirstDecl() const { return First; }
 
   /// True if this is the first declaration in its redeclaration chain.
-  bool isFirstDecl() const { return RedeclLink.NextIsLatest(); }
+  bool isFirstDecl() const { return RedeclLink.isFirst(); }
 
   /// Returns the most recent (re)declaration of this declaration.
   decl_type *getMostRecentDecl() {
     return getFirstDecl()->getNextRedeclaration();
   }
 
   /// Returns the most recent (re)declaration of this declaration.
   const decl_type *getMostRecentDecl() const {