--- a/dom/base/nsIDocument.h
+++ b/dom/base/nsIDocument.h
@@ -1850,29 +1850,64 @@ public:
   }
   bool LoadsFullXULStyleSheetUpFront()
   {
     return IsXULDocument() || AllowXULXBL();
   }
 
   virtual bool IsScriptEnabled() = 0;
 
-  bool IsTopLevelContentDocument() const { return mIsTopLevelContentDocument; }
+  /**
+   * Returns whether this document is loaded in a content docshell that does not
+   * have another content docshell as a parent.
+   */
+  bool IsTopLevelContentDocument() const
+  {
+    // We use this flag rather than inspecting the current docshell to avoid a
+    // bunch of virtual function calls, since we need to look this up every time
+    // we use some Web platform feature that has a use counter.
+    return mIsTopLevelContentDocument;
+  }
+
+  /**
+   * Updates the flag that records whether this document is loaded in a content
+   * docshell that does not have another content docshell as a parent.
+   *
+   * XXX This is only called from nsIDocument::SetContainer, and ideally
+   * wouldn't be public.
+   */
   void SetIsTopLevelContentDocument(bool aIsTopLevelContentDocument)
   {
     mIsTopLevelContentDocument = aIsTopLevelContentDocument;
     // When a document is set as TopLevelContentDocument, it must be
     // allowpaymentrequest. We handle the false case while a document is appended
     // in SetSubDocumentFor
     if (aIsTopLevelContentDocument) {
       SetAllowPaymentRequest(true);
     }
   }
 
-  bool IsContentDocument() const { return mIsContentDocument; }
+  /**
+   * Returns whether this document is loaded in a content docshell.
+   */
+  bool IsContentDocument() const
+  {
+    // We use this flag rather than inspecting the current docshell to avoid a
+    // bunch of virtual function calls, since we need to look this up every time
+    // we use some Web platform feature that has a use counter.
+    return mIsContentDocument;
+  }
+
+  /**
+   * Updates the flag that records whether this document is loaded in a content
+   * docshell.
+   *
+   * XXX This is only called from nsIDocument::SetContainer, and ideally
+   * wouldn't be public.
+   */
   void SetIsContentDocument(bool aIsContentDocument)
   {
     mIsContentDocument = aIsContentDocument;
   }
 
   /**
    * Create an element with the specified name, prefix and namespace ID.
    * Returns null if element name parsing failed.
@@ -3577,18 +3612,23 @@ protected:
   // True if ReportHasScrollLinkedEffect() has been called.
   bool mHasScrollLinkedEffect : 1;
 
   // True if we have frame request callbacks scheduled with the refresh driver.
   // This should generally be updated only via
   // UpdateFrameRequestCallbackSchedulingState.
   bool mFrameRequestCallbacksScheduled : 1;
 
+  // True if this document is loaded in a content docshell, and that docshell
+  // does not have a parent content docshell.  This flag is updated by
+  // nsIDocument::SetContainer.
   bool mIsTopLevelContentDocument : 1;
 
+  // True if this document is loaded in a content docshell.  This flag is
+  // updated by nsIDocument::SetContainer.
   bool mIsContentDocument : 1;
 
   // True if we have called BeginLoad and are expecting a paired EndLoad call.
   bool mDidCallBeginLoad : 1;
 
   // True if any CSP violation reports for this doucment will be buffered in
   // mBufferedCSPViolations instead of being sent immediately.
   bool mBufferingCSPViolations : 1;