Added some comments :-)

layout/html/base/src/nsFrameList.h

@@ -48,14 +48,24 @@ public:
 
   void AppendFrames(nsIFrame* aParent, nsFrameList& aFrameList) {
     AppendFrames(aParent, aFrameList.mFirstChild);
+    aFrameList.mFirstChild = nsnull;
   }
 
   void AppendFrame(nsIFrame* aParent, nsIFrame* aFrame);
 
+  // Take aFrame out of the frame list. This also disconnects aFrame
+  // from the sibling list. This will return PR_FALSE if aFrame is
+  // nsnull or if aFrame is not in the list.
   PRBool RemoveFrame(nsIFrame* aFrame);
 
+  // Remove the first child from the list. The caller is assumed to be
+  // holding a reference to the first child. This call is equivalent
+  // in behavior to calling RemoveFrame(FirstChild()).
   PRBool RemoveFirstChild();
 
+  // Take aFrame out of the frame list and then delete it. This also
+  // disconnects aFrame from the sibling list. This will return
+  // PR_FALSE if aFrame is nsnull or if aFrame is not in the list.
   PRBool DeleteFrame(nsIPresContext& aPresContext, nsIFrame* aFrame);
 
   void InsertFrame(nsIFrame* aParent,
@@ -66,6 +76,12 @@ public:
                     nsIFrame* aPrevSibling,
                     nsIFrame* aFrameList);
 
+  void InsertFrames(nsIFrame* aParent, nsIFrame* aPrevSibling,
+                    nsFrameList& aFrameList) {
+    InsertFrames(aParent, aPrevSibling, aFrameList.FirstChild());
+    aFrameList.mFirstChild = nsnull;
+  }
+
   PRBool ReplaceFrame(nsIFrame* aParent,
                       nsIFrame* aOldFrame,
                       nsIFrame* aNewFrame);
@@ -77,9 +93,9 @@ public:
 
   PRBool Split(nsIFrame* aAfterFrame, nsIFrame** aNextFrameResult);
 
-  PRBool PullFrame(nsIFrame* aParent,
-                   nsFrameList& aFromList,
-                   nsIFrame** aResult);
+  nsIFrame* PullFrame(nsIFrame* aParent,
+                      nsIFrame* aLastChild,
+                      nsFrameList& aFromList);
 
   void Join(nsIFrame* aParent, nsFrameList& aList) {
     AppendFrames(aParent, aList.mFirstChild);
@@ -108,6 +124,8 @@ public:
 
   nsIFrame* GetPrevSiblingFor(nsIFrame* aFrame) const;
 
+  void VerifyParent(nsIFrame* aParent) const;
+
 protected:
   nsIFrame* mFirstChild;
 };