diff --git a/mozilla/layout/generic/nsAbsoluteContainingBlock.cpp b/mozilla/layout/generic/nsAbsoluteContainingBlock.cpp
index 51bf2179849..56607493344 100644
--- a/mozilla/layout/generic/nsAbsoluteContainingBlock.cpp
+++ b/mozilla/layout/generic/nsAbsoluteContainingBlock.cpp
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * code for managing absolutely positioned children of a rendering
+ * object that is a containing block for them
+ */
+
 #include "nsCOMPtr.h"
 #include "nsAbsoluteContainingBlock.h"
 #include "nsContainerFrame.h"
diff --git a/mozilla/layout/generic/nsAbsoluteContainingBlock.h b/mozilla/layout/generic/nsAbsoluteContainingBlock.h
index 4456601d1f6..47d6d721545 100644
--- a/mozilla/layout/generic/nsAbsoluteContainingBlock.h
+++ b/mozilla/layout/generic/nsAbsoluteContainingBlock.h
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * code for managing absolutely positioned children of a rendering
+ * object that is a containing block for them
+ */
+
 #ifndef nsAbsoluteContainingBlock_h___
 #define nsAbsoluteContainingBlock_h___
 
diff --git a/mozilla/layout/generic/nsAreaFrame.cpp b/mozilla/layout/generic/nsAreaFrame.cpp
index 302f7f3493c..4bf18df860d 100644
--- a/mozilla/layout/generic/nsAreaFrame.cpp
+++ b/mozilla/layout/generic/nsAreaFrame.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* derived class of nsBlockFrame; distinction barely relevant anymore */
+
 #include "nsAreaFrame.h"
 #include "nsBlockBandData.h"
 #include "nsStyleContext.h"
diff --git a/mozilla/layout/generic/nsAreaFrame.h b/mozilla/layout/generic/nsAreaFrame.h
index 2d46f253ac8..40b0020fbbf 100644
--- a/mozilla/layout/generic/nsAreaFrame.h
+++ b/mozilla/layout/generic/nsAreaFrame.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* derived class of nsBlockFrame; distinction barely relevant anymore */
+
 #ifndef nsAreaFrame_h___
 #define nsAreaFrame_h___
 
diff --git a/mozilla/layout/generic/nsBRFrame.cpp b/mozilla/layout/generic/nsBRFrame.cpp
index 1a67f3b3278..882baa4eed5 100644
--- a/mozilla/layout/generic/nsBRFrame.cpp
+++ b/mozilla/layout/generic/nsBRFrame.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object for HTML <br> elements */
+
 #include "nsCOMPtr.h"
 #include "nsFrame.h"
 #include "nsHTMLParts.h"
diff --git a/mozilla/layout/generic/nsBlockBandData.cpp b/mozilla/layout/generic/nsBlockBandData.cpp
index 5bde4b873bd..81270b7f155 100644
--- a/mozilla/layout/generic/nsBlockBandData.cpp
+++ b/mozilla/layout/generic/nsBlockBandData.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* code for management of floats that implements space manager interfaces */
+
 #include "nsCOMPtr.h"
 #include "nsBlockBandData.h"
 #include "nsIFrame.h"
diff --git a/mozilla/layout/generic/nsBlockBandData.h b/mozilla/layout/generic/nsBlockBandData.h
index 8b571c9aec8..5303b735ad2 100644
--- a/mozilla/layout/generic/nsBlockBandData.h
+++ b/mozilla/layout/generic/nsBlockBandData.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* code for management of floats that implements space manager interfaces */
+
 #ifndef nsBlockBandData_h___
 #define nsBlockBandData_h___
 
diff --git a/mozilla/layout/generic/nsBlockFrame.cpp b/mozilla/layout/generic/nsBlockFrame.cpp
index 0a233cfe713..2b53b0a8f52 100644
--- a/mozilla/layout/generic/nsBlockFrame.cpp
+++ b/mozilla/layout/generic/nsBlockFrame.cpp
@@ -40,6 +40,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * rendering object for CSS display:block and display:list-item objects,
+ * also used inside table cells
+ */
+
 #include "nsCOMPtr.h"
 #include "nsBlockFrame.h"
 #include "nsBlockReflowContext.h"
diff --git a/mozilla/layout/generic/nsBlockFrame.h b/mozilla/layout/generic/nsBlockFrame.h
index db488fd8d09..3947dcc9e68 100644
--- a/mozilla/layout/generic/nsBlockFrame.h
+++ b/mozilla/layout/generic/nsBlockFrame.h
@@ -35,6 +35,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * rendering object for CSS display:block and display:list-item objects,
+ * also used inside table cells
+ */
+
 #ifndef nsBlockFrame_h___
 #define nsBlockFrame_h___
 
diff --git a/mozilla/layout/generic/nsBlockReflowContext.cpp b/mozilla/layout/generic/nsBlockReflowContext.cpp
index f6a3c48bd63..0a384c303a9 100644
--- a/mozilla/layout/generic/nsBlockReflowContext.cpp
+++ b/mozilla/layout/generic/nsBlockReflowContext.cpp
@@ -36,6 +36,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* class that a parent frame uses to reflow a block frame */
+
 #include "nsBlockReflowContext.h"
 #include "nsLineLayout.h"
 #include "nsSpaceManager.h"
diff --git a/mozilla/layout/generic/nsBlockReflowContext.h b/mozilla/layout/generic/nsBlockReflowContext.h
index 05d9d6e946f..edd528b4619 100644
--- a/mozilla/layout/generic/nsBlockReflowContext.h
+++ b/mozilla/layout/generic/nsBlockReflowContext.h
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* class that a parent frame uses to reflow a block frame */
+
 #ifndef nsBlockReflowContext_h___
 #define nsBlockReflowContext_h___
 
diff --git a/mozilla/layout/generic/nsBlockReflowState.cpp b/mozilla/layout/generic/nsBlockReflowState.cpp
index c0a35bf6472..fdfbabecf78 100644
--- a/mozilla/layout/generic/nsBlockReflowState.cpp
+++ b/mozilla/layout/generic/nsBlockReflowState.cpp
@@ -39,6 +39,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* state used in reflow of block frames */
+
 #include "nsBlockReflowContext.h"
 #include "nsBlockReflowState.h"
 #include "nsBlockFrame.h"
diff --git a/mozilla/layout/generic/nsBlockReflowState.h b/mozilla/layout/generic/nsBlockReflowState.h
index 7c793be371b..5353b622848 100644
--- a/mozilla/layout/generic/nsBlockReflowState.h
+++ b/mozilla/layout/generic/nsBlockReflowState.h
@@ -38,6 +38,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* state used in reflow of block frames */
+
 #ifndef nsBlockReflowState_h__
 #define nsBlockReflowState_h__
 
diff --git a/mozilla/layout/generic/nsBulletFrame.cpp b/mozilla/layout/generic/nsBulletFrame.cpp
index fcf6f32e60c..4a835cfc438 100644
--- a/mozilla/layout/generic/nsBulletFrame.cpp
+++ b/mozilla/layout/generic/nsBulletFrame.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object for list-item bullets */
+
 #include "nsCOMPtr.h"
 #include "nsBulletFrame.h"
 #include "nsHTMLAtoms.h"
diff --git a/mozilla/layout/generic/nsBulletFrame.h b/mozilla/layout/generic/nsBulletFrame.h
index e73d4e03c3d..93b6c58626e 100644
--- a/mozilla/layout/generic/nsBulletFrame.h
+++ b/mozilla/layout/generic/nsBulletFrame.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object for list-item bullets */
+
 #ifndef nsBulletFrame_h___
 #define nsBulletFrame_h___
 
diff --git a/mozilla/layout/generic/nsColumnSetFrame.cpp b/mozilla/layout/generic/nsColumnSetFrame.cpp
index 5e075a0a966..791c00f6915 100644
--- a/mozilla/layout/generic/nsColumnSetFrame.cpp
+++ b/mozilla/layout/generic/nsColumnSetFrame.cpp
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* rendering object for css3 multi-column layout */
+
 #include "nsHTMLContainerFrame.h"
 #include "nsIContent.h"
 #include "nsIFrame.h"
diff --git a/mozilla/layout/generic/nsContainerFrame.cpp b/mozilla/layout/generic/nsContainerFrame.cpp
index bdc7bf0a9cc..5a0a8e5b288 100644
--- a/mozilla/layout/generic/nsContainerFrame.cpp
+++ b/mozilla/layout/generic/nsContainerFrame.cpp
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* base class #1 for rendering objects that have child lists */
+
 #include "nsContainerFrame.h"
 #include "nsIContent.h"
 #include "nsIDocument.h"
diff --git a/mozilla/layout/generic/nsContainerFrame.h b/mozilla/layout/generic/nsContainerFrame.h
index 63c91b13db7..ccb9eef313b 100644
--- a/mozilla/layout/generic/nsContainerFrame.h
+++ b/mozilla/layout/generic/nsContainerFrame.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* base class #1 for rendering objects that have child lists */
+
 #ifndef nsContainerFrame_h___
 #define nsContainerFrame_h___
 
diff --git a/mozilla/layout/generic/nsFirstLetterFrame.cpp b/mozilla/layout/generic/nsFirstLetterFrame.cpp
index 46d21622c21..7f25a55d47d 100644
--- a/mozilla/layout/generic/nsFirstLetterFrame.cpp
+++ b/mozilla/layout/generic/nsFirstLetterFrame.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object for CSS :first-letter pseudo-element */
+
 #include "nsCOMPtr.h"
 #include "nsHTMLContainerFrame.h"
 #include "nsPresContext.h"
diff --git a/mozilla/layout/generic/nsFrame.cpp b/mozilla/layout/generic/nsFrame.cpp
index eb56afa6464..74b087cb599 100644
--- a/mozilla/layout/generic/nsFrame.cpp
+++ b/mozilla/layout/generic/nsFrame.cpp
@@ -38,6 +38,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* base class of all rendering objects */
+
 #include "nsCOMPtr.h"
 #include "nsFrame.h"
 #include "nsFrameList.h"
diff --git a/mozilla/layout/generic/nsFrame.h b/mozilla/layout/generic/nsFrame.h
index 2c0e9600dd3..06906369716 100644
--- a/mozilla/layout/generic/nsFrame.h
+++ b/mozilla/layout/generic/nsFrame.h
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* base class of all rendering objects */
+
 #ifndef nsFrame_h___
 #define nsFrame_h___
 
diff --git a/mozilla/layout/generic/nsFrameFrame.cpp b/mozilla/layout/generic/nsFrameFrame.cpp
index bec3ee6cbb0..919a5ee737b 100644
--- a/mozilla/layout/generic/nsFrameFrame.cpp
+++ b/mozilla/layout/generic/nsFrameFrame.cpp
@@ -36,6 +36,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * rendering object for replaced elements that contain a document, such
+ * as <frame>, <iframe>, and some <object>s
+ */
+
 #include "nsCOMPtr.h"
 #include "nsLeafFrame.h"
 #include "nsGenericHTMLElement.h"
diff --git a/mozilla/layout/generic/nsFrameList.cpp b/mozilla/layout/generic/nsFrameList.cpp
index 56ed0d50516..ac3583e823f 100644
--- a/mozilla/layout/generic/nsFrameList.cpp
+++ b/mozilla/layout/generic/nsFrameList.cpp
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* class for maintaining a linked list of child frames */
+
 #include "nsFrameList.h"
 #ifdef NS_DEBUG
 #include "nsIFrameDebug.h"
diff --git a/mozilla/layout/generic/nsFrameList.h b/mozilla/layout/generic/nsFrameList.h
index fef3bb2836e..9f409b180c0 100644
--- a/mozilla/layout/generic/nsFrameList.h
+++ b/mozilla/layout/generic/nsFrameList.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* class for maintaining a linked list of child frames */
+
 #ifndef nsFrameList_h___
 #define nsFrameList_h___
 
diff --git a/mozilla/layout/generic/nsFrameSetFrame.cpp b/mozilla/layout/generic/nsFrameSetFrame.cpp
index 35ab7d3567c..2defca30671 100644
--- a/mozilla/layout/generic/nsFrameSetFrame.cpp
+++ b/mozilla/layout/generic/nsFrameSetFrame.cpp
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object for HTML <frameset> elements */
+
 #include "nsCOMPtr.h"
 #include "nsFrameSetFrame.h"
 #include "nsContentUtils.h"
diff --git a/mozilla/layout/generic/nsFrameSetFrame.h b/mozilla/layout/generic/nsFrameSetFrame.h
index 5e1059e2384..f082e7fc588 100644
--- a/mozilla/layout/generic/nsFrameSetFrame.h
+++ b/mozilla/layout/generic/nsFrameSetFrame.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object for HTML <frameset> elements */
+
 #ifndef nsHTMLFrameset_h___
 #define nsHTMLFrameset_h___
 
diff --git a/mozilla/layout/generic/nsFrameUtil.cpp b/mozilla/layout/generic/nsFrameUtil.cpp
index a91147ee402..dafbc03df80 100644
--- a/mozilla/layout/generic/nsFrameUtil.cpp
+++ b/mozilla/layout/generic/nsFrameUtil.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* utilities for regression tests based on frame tree comparison */
+ 
 #include "nsIFrameUtil.h"
 #include "nsFrame.h"
 #include "nsString.h"
diff --git a/mozilla/layout/generic/nsGfxScrollFrame.cpp b/mozilla/layout/generic/nsGfxScrollFrame.cpp
index 9e567e88594..17ba35b1de2 100644
--- a/mozilla/layout/generic/nsGfxScrollFrame.cpp
+++ b/mozilla/layout/generic/nsGfxScrollFrame.cpp
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object to wrap rendering objects that should be scrollable */
+
 #include "nsCOMPtr.h"
 #include "nsHTMLParts.h"
 #include "nsPresContext.h"
diff --git a/mozilla/layout/generic/nsGfxScrollFrame.h b/mozilla/layout/generic/nsGfxScrollFrame.h
index c633d49d300..986cd8b9f88 100644
--- a/mozilla/layout/generic/nsGfxScrollFrame.h
+++ b/mozilla/layout/generic/nsGfxScrollFrame.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object to wrap rendering objects that should be scrollable */
+
 #ifndef nsGfxScrollFrame_h___
 #define nsGfxScrollFrame_h___
 
diff --git a/mozilla/layout/generic/nsHTMLCanvasFrame.cpp b/mozilla/layout/generic/nsHTMLCanvasFrame.cpp
index 2ae74fc52c3..c92a20cc724 100644
--- a/mozilla/layout/generic/nsHTMLCanvasFrame.cpp
+++ b/mozilla/layout/generic/nsHTMLCanvasFrame.cpp
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* rendering object for the HTML <canvas> element */
+
 #include "nsHTMLParts.h"
 #include "nsCOMPtr.h"
 #include "nsIServiceManager.h"
diff --git a/mozilla/layout/generic/nsHTMLCanvasFrame.h b/mozilla/layout/generic/nsHTMLCanvasFrame.h
index 32d41413ff8..aca658c4de6 100644
--- a/mozilla/layout/generic/nsHTMLCanvasFrame.h
+++ b/mozilla/layout/generic/nsHTMLCanvasFrame.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object for the HTML <canvas> element */
+
 #ifndef nsHTMLCanvasFrame_h___
 #define nsHTMLCanvasFrame_h___
 
diff --git a/mozilla/layout/generic/nsHTMLContainerFrame.cpp b/mozilla/layout/generic/nsHTMLContainerFrame.cpp
index 6ff0df1091a..6def62e424c 100644
--- a/mozilla/layout/generic/nsHTMLContainerFrame.cpp
+++ b/mozilla/layout/generic/nsHTMLContainerFrame.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* base class #2 for rendering objects that have child lists */
+
 #include "nsHTMLContainerFrame.h"
 #include "nsIRenderingContext.h"
 #include "nsPresContext.h"
diff --git a/mozilla/layout/generic/nsHTMLContainerFrame.h b/mozilla/layout/generic/nsHTMLContainerFrame.h
index b023c84ecee..2d841cf14d5 100644
--- a/mozilla/layout/generic/nsHTMLContainerFrame.h
+++ b/mozilla/layout/generic/nsHTMLContainerFrame.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* base class #2 for rendering objects that have child lists */
+
 #ifndef nsHTMLContainerFrame_h___
 #define nsHTMLContainerFrame_h___
 
diff --git a/mozilla/layout/generic/nsHTMLFrame.cpp b/mozilla/layout/generic/nsHTMLFrame.cpp
index cb890f1b6a2..90cb417fc47 100644
--- a/mozilla/layout/generic/nsHTMLFrame.cpp
+++ b/mozilla/layout/generic/nsHTMLFrame.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object that goes directly inside the document's scrollbars */
+
 #include "nsIServiceManager.h"
 #include "nsHTMLParts.h"
 #include "nsHTMLContainerFrame.h"
diff --git a/mozilla/layout/generic/nsHTMLParts.h b/mozilla/layout/generic/nsHTMLParts.h
index 6f9a3f1433d..30d5420bbc2 100644
--- a/mozilla/layout/generic/nsHTMLParts.h
+++ b/mozilla/layout/generic/nsHTMLParts.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* factory functions for rendering object classes */
+
 #ifndef nsHTMLParts_h___
 #define nsHTMLParts_h___
 
diff --git a/mozilla/layout/generic/nsHTMLReflowMetrics.h b/mozilla/layout/generic/nsHTMLReflowMetrics.h
index ab65a8895f9..03a0cbd6b48 100644
--- a/mozilla/layout/generic/nsHTMLReflowMetrics.h
+++ b/mozilla/layout/generic/nsHTMLReflowMetrics.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* struct containing the output from nsIFrame::Reflow */
+
 #ifndef nsHTMLReflowMetrics_h___
 #define nsHTMLReflowMetrics_h___
 
diff --git a/mozilla/layout/generic/nsHTMLReflowState.cpp b/mozilla/layout/generic/nsHTMLReflowState.cpp
index ecf332e308b..f82a5752f5c 100644
--- a/mozilla/layout/generic/nsHTMLReflowState.cpp
+++ b/mozilla/layout/generic/nsHTMLReflowState.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* struct containing the input to nsIFrame::Reflow */
+
 #include "nsCOMPtr.h"
 #include "nsStyleConsts.h"
 #include "nsCSSAnonBoxes.h"
diff --git a/mozilla/layout/generic/nsHTMLReflowState.h b/mozilla/layout/generic/nsHTMLReflowState.h
index f12395000df..f62e93c0049 100644
--- a/mozilla/layout/generic/nsHTMLReflowState.h
+++ b/mozilla/layout/generic/nsHTMLReflowState.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* struct containing the input to nsIFrame::Reflow */
+
 #ifndef nsHTMLReflowState_h___
 #define nsHTMLReflowState_h___
 
diff --git a/mozilla/layout/generic/nsIAnonymousContentCreator.h b/mozilla/layout/generic/nsIAnonymousContentCreator.h
index 4e94b90f4ea..f1620145dee 100644
--- a/mozilla/layout/generic/nsIAnonymousContentCreator.h
+++ b/mozilla/layout/generic/nsIAnonymousContentCreator.h
@@ -35,6 +35,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * interface for rendering objects that manually create subtrees of
+ * anonymous content
+ */
 
 #ifndef nsIAnonymousContentCreator_h___
 #define nsIAnonymousContentCreator_h___
diff --git a/mozilla/layout/generic/nsICanvasFrame.h b/mozilla/layout/generic/nsICanvasFrame.h
index 7d1365281e4..0beb4142687 100644
--- a/mozilla/layout/generic/nsICanvasFrame.h
+++ b/mozilla/layout/generic/nsICanvasFrame.h
@@ -35,6 +35,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* interface to rendering object that lives inside the document scrollbars */
+
 #ifndef nsICanvasFrame_h__
 #define nsICanvasFrame_h__
 
diff --git a/mozilla/layout/generic/nsIFrame.h b/mozilla/layout/generic/nsIFrame.h
index f7cc337f9d0..7f3b0d552c0 100644
--- a/mozilla/layout/generic/nsIFrame.h
+++ b/mozilla/layout/generic/nsIFrame.h
@@ -35,6 +35,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* interface for all rendering objects */
+
 #ifndef nsIFrame_h___
 #define nsIFrame_h___
 
diff --git a/mozilla/layout/generic/nsIFrameDebug.h b/mozilla/layout/generic/nsIFrameDebug.h
index 248d2084c58..544aea7b99f 100644
--- a/mozilla/layout/generic/nsIFrameDebug.h
+++ b/mozilla/layout/generic/nsIFrameDebug.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* debugging interface for all rendering objects */
+
 #ifndef nsIFrameDebug_h___
 #define nsIFrameDebug_h___
 
diff --git a/mozilla/layout/generic/nsIFrameFrame.h b/mozilla/layout/generic/nsIFrameFrame.h
index c16238db22b..6c88ee0d698 100644
--- a/mozilla/layout/generic/nsIFrameFrame.h
+++ b/mozilla/layout/generic/nsIFrameFrame.h
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * interface for rendering objects for replaced elements containing a
+ * document, such as <frame>, <iframe>, and some <object>s
+ */
+
 #ifndef nsIFrameFrame_h___
 #define nsIFrameFrame_h___
 
diff --git a/mozilla/layout/generic/nsIFrameUtil.h b/mozilla/layout/generic/nsIFrameUtil.h
index c37d0b87b07..df411cc135a 100644
--- a/mozilla/layout/generic/nsIFrameUtil.h
+++ b/mozilla/layout/generic/nsIFrameUtil.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* utilities for regression tests based on frame tree comparison */
+
 #ifndef nsIFrameUtil_h___
 #define nsIFrameUtil_h___
 
diff --git a/mozilla/layout/generic/nsIImageFrame.h b/mozilla/layout/generic/nsIImageFrame.h
index e0c3ae25172..8637bfc3121 100644
--- a/mozilla/layout/generic/nsIImageFrame.h
+++ b/mozilla/layout/generic/nsIImageFrame.h
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * interface for rendering objects for replaced elements with bitmap
+ * image data
+ */
+
 #ifndef nsIImageFrame_h___
 #define nsIImageFrame_h___
 
diff --git a/mozilla/layout/generic/nsIObjectFrame.h b/mozilla/layout/generic/nsIObjectFrame.h
index 3e4df289c8a..2792ab8406d 100644
--- a/mozilla/layout/generic/nsIObjectFrame.h
+++ b/mozilla/layout/generic/nsIObjectFrame.h
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * interface for rendering objects for replaced elements implemented by
+ * a plugin
+ */
+
 #ifndef nsIObjectFrame_h___
 #define nsIObjectFrame_h___
 
diff --git a/mozilla/layout/generic/nsIScrollableFrame.h b/mozilla/layout/generic/nsIScrollableFrame.h
index 56c73a6ab88..115bbc4bd9c 100644
--- a/mozilla/layout/generic/nsIScrollableFrame.h
+++ b/mozilla/layout/generic/nsIScrollableFrame.h
@@ -35,6 +35,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * interface for rendering objects that wrap rendering objects that should
+ * be scrollable
+ */
+
 #ifndef nsIScrollFrame_h___
 #define nsIScrollFrame_h___
 
diff --git a/mozilla/layout/generic/nsIStatefulFrame.h b/mozilla/layout/generic/nsIStatefulFrame.h
index 0a54a265fd6..f8475beefb0 100644
--- a/mozilla/layout/generic/nsIStatefulFrame.h
+++ b/mozilla/layout/generic/nsIStatefulFrame.h
@@ -1,3 +1,8 @@
+/*
+ * interface for rendering objects whose state is saved in
+ * session-history (back-forward navigation)
+ */
+
 #ifndef _nsIStatefulFrame_h
 #define _nsIStatefulFrame_h
 
diff --git a/mozilla/layout/generic/nsImageFrame.cpp b/mozilla/layout/generic/nsImageFrame.cpp
index eb97758b10c..360e94ff973 100644
--- a/mozilla/layout/generic/nsImageFrame.cpp
+++ b/mozilla/layout/generic/nsImageFrame.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object for replaced elements with bitmap image data */
+
 #include "nsHTMLParts.h"
 #include "nsCOMPtr.h"
 #include "nsImageFrame.h"
diff --git a/mozilla/layout/generic/nsImageFrame.h b/mozilla/layout/generic/nsImageFrame.h
index ebf257f4567..5e2a5ef546b 100644
--- a/mozilla/layout/generic/nsImageFrame.h
+++ b/mozilla/layout/generic/nsImageFrame.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object for replaced elements with bitmap image data */
+
 #ifndef nsImageFrame_h___
 #define nsImageFrame_h___
 
diff --git a/mozilla/layout/generic/nsImageMap.cpp b/mozilla/layout/generic/nsImageMap.cpp
index ace5a108816..d4c1cf3a6e9 100644
--- a/mozilla/layout/generic/nsImageMap.cpp
+++ b/mozilla/layout/generic/nsImageMap.cpp
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* code for HTML client-side image maps */
+
 #include "nsImageMap.h"
 #include "nsString.h"
 #include "nsReadableUtils.h"
diff --git a/mozilla/layout/generic/nsImageMap.h b/mozilla/layout/generic/nsImageMap.h
index badff7d7c26..081d6359ae4 100644
--- a/mozilla/layout/generic/nsImageMap.h
+++ b/mozilla/layout/generic/nsImageMap.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* code for HTML client-side image maps */
+
 #ifndef nsImageMap_h___
 #define nsImageMap_h___
 
diff --git a/mozilla/layout/generic/nsInlineFrame.cpp b/mozilla/layout/generic/nsInlineFrame.cpp
index 97bc3536a6c..e10386db807 100644
--- a/mozilla/layout/generic/nsInlineFrame.cpp
+++ b/mozilla/layout/generic/nsInlineFrame.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object for CSS display:inline objects */
+
 #include "nsCOMPtr.h"
 #include "nsInlineFrame.h"
 #include "nsBlockFrame.h"
diff --git a/mozilla/layout/generic/nsInlineFrame.h b/mozilla/layout/generic/nsInlineFrame.h
index 0c9b8b1c561..4bbd2e41582 100644
--- a/mozilla/layout/generic/nsInlineFrame.h
+++ b/mozilla/layout/generic/nsInlineFrame.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object for CSS display:inline objects */
+
 #ifndef nsInlineFrame_h___
 #define nsInlineFrame_h___
 
diff --git a/mozilla/layout/generic/nsIntervalSet.cpp b/mozilla/layout/generic/nsIntervalSet.cpp
index 7927900cc4a..0a9ed4e2747 100644
--- a/mozilla/layout/generic/nsIntervalSet.cpp
+++ b/mozilla/layout/generic/nsIntervalSet.cpp
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* a set of ranges on a number-line */
+
 #include "nsIntervalSet.h"
 #include NEW_H
 
diff --git a/mozilla/layout/generic/nsIntervalSet.h b/mozilla/layout/generic/nsIntervalSet.h
index 4b467c2b0be..97c4807dede 100644
--- a/mozilla/layout/generic/nsIntervalSet.h
+++ b/mozilla/layout/generic/nsIntervalSet.h
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* a set of ranges on a number-line */
+
 #ifndef nsIntervalSet_h___
 #define nsIntervalSet_h___
 
diff --git a/mozilla/layout/generic/nsLeafFrame.cpp b/mozilla/layout/generic/nsLeafFrame.cpp
index 22da531aaef..efb160f703d 100644
--- a/mozilla/layout/generic/nsLeafFrame.cpp
+++ b/mozilla/layout/generic/nsLeafFrame.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* base class for rendering objects that do not have child lists */
+
 #include "nsCOMPtr.h"
 #include "nsLeafFrame.h"
 #include "nsHTMLContainerFrame.h"
diff --git a/mozilla/layout/generic/nsLeafFrame.h b/mozilla/layout/generic/nsLeafFrame.h
index e2cca702964..7e1762cd6f8 100644
--- a/mozilla/layout/generic/nsLeafFrame.h
+++ b/mozilla/layout/generic/nsLeafFrame.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* base class for rendering objects that do not have child lists */
+
 #ifndef nsLeafFrame_h___
 #define nsLeafFrame_h___
 
diff --git a/mozilla/layout/generic/nsLineBox.cpp b/mozilla/layout/generic/nsLineBox.cpp
index eb28a4cdd8b..46595e66970 100644
--- a/mozilla/layout/generic/nsLineBox.cpp
+++ b/mozilla/layout/generic/nsLineBox.cpp
@@ -37,6 +37,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* representation of one line within a block frame, a CSS line box */
+
 #include "nsLineBox.h"
 #include "nsSpaceManager.h"
 #include "nsLineLayout.h"
diff --git a/mozilla/layout/generic/nsLineBox.h b/mozilla/layout/generic/nsLineBox.h
index 64a5acc3e95..a0cdee73194 100644
--- a/mozilla/layout/generic/nsLineBox.h
+++ b/mozilla/layout/generic/nsLineBox.h
@@ -36,6 +36,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* representation of one line within a block frame, a CSS line box */
+
 #ifndef nsLineBox_h___
 #define nsLineBox_h___
 
diff --git a/mozilla/layout/generic/nsLineLayout.cpp b/mozilla/layout/generic/nsLineLayout.cpp
index 20adaa6a3aa..e3254ba4da1 100644
--- a/mozilla/layout/generic/nsLineLayout.cpp
+++ b/mozilla/layout/generic/nsLineLayout.cpp
@@ -40,6 +40,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* state and methods used while laying out a single line of a block frame */
+
 #define PL_ARENA_CONST_ALIGN_MASK (sizeof(void*)-1)
 #include "plarena.h"
 
diff --git a/mozilla/layout/generic/nsLineLayout.h b/mozilla/layout/generic/nsLineLayout.h
index 04945a49992..f6e80e08d1d 100644
--- a/mozilla/layout/generic/nsLineLayout.h
+++ b/mozilla/layout/generic/nsLineLayout.h
@@ -44,6 +44,9 @@
  * Date             Modified by     Description of modification
  * 04/20/2000       IBM Corp.      OS/2 VisualAge build.
  */
+
+/* state and methods used while laying out a single line of a block frame */
+
 #ifndef nsLineLayout_h___
 #define nsLineLayout_h___
 
diff --git a/mozilla/layout/generic/nsObjectFrame.cpp b/mozilla/layout/generic/nsObjectFrame.cpp
index f183f5f7781..23172b185d3 100644
--- a/mozilla/layout/generic/nsObjectFrame.cpp
+++ b/mozilla/layout/generic/nsObjectFrame.cpp
@@ -41,6 +41,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering objects for replaced elements implemented by a plugin */
+
 #include "nscore.h"
 #include "nsCOMPtr.h"
 #include "nsPresContext.h"
diff --git a/mozilla/layout/generic/nsObjectFrame.h b/mozilla/layout/generic/nsObjectFrame.h
index 8cd320589ae..aad3c64cd51 100644
--- a/mozilla/layout/generic/nsObjectFrame.h
+++ b/mozilla/layout/generic/nsObjectFrame.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering objects for replaced elements implemented by a plugin */
+
 #ifndef nsObjectFrame_h___
 #define nsObjectFrame_h___
 
diff --git a/mozilla/layout/generic/nsPlaceholderFrame.cpp b/mozilla/layout/generic/nsPlaceholderFrame.cpp
index 459c9af691b..f9d546a0f26 100644
--- a/mozilla/layout/generic/nsPlaceholderFrame.cpp
+++ b/mozilla/layout/generic/nsPlaceholderFrame.cpp
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * rendering object for the point that anchors out-of-flow rendering
+ * objects such as floats and absolutely positioned elements
+ */
+
 #include "nsPlaceholderFrame.h"
 #include "nsLineLayout.h"
 #include "nsIContent.h"
diff --git a/mozilla/layout/generic/nsPlaceholderFrame.h b/mozilla/layout/generic/nsPlaceholderFrame.h
index 1513d5e854e..55b11e57d3b 100644
--- a/mozilla/layout/generic/nsPlaceholderFrame.h
+++ b/mozilla/layout/generic/nsPlaceholderFrame.h
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * rendering object for the point that anchors out-of-flow rendering
+ * objects such as floats and absolutely positioned elements
+ */
+
 #ifndef nsPlaceholderFrame_h___
 #define nsPlaceholderFrame_h___
 
diff --git a/mozilla/layout/generic/nsSpaceManager.cpp b/mozilla/layout/generic/nsSpaceManager.cpp
index 5c4af2e8b73..d3e0dccebb3 100644
--- a/mozilla/layout/generic/nsSpaceManager.cpp
+++ b/mozilla/layout/generic/nsSpaceManager.cpp
@@ -35,6 +35,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * class that manages regions of 2-D space, originally designed
+ * generally but actually specific to space occupied by floats
+ */
+
 #include "nsSpaceManager.h"
 #include "nsPoint.h"
 #include "nsRect.h"
diff --git a/mozilla/layout/generic/nsSpaceManager.h b/mozilla/layout/generic/nsSpaceManager.h
index 4cbcb155875..d77d6af2262 100644
--- a/mozilla/layout/generic/nsSpaceManager.h
+++ b/mozilla/layout/generic/nsSpaceManager.h
@@ -35,6 +35,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * class that manages regions of 2-D space, originally designed
+ * generally but actually specific to space occupied by floats
+ */
+
 #ifndef nsSpaceManager_h___
 #define nsSpaceManager_h___
 
diff --git a/mozilla/layout/generic/nsSpacerFrame.cpp b/mozilla/layout/generic/nsSpacerFrame.cpp
index 18ea96992a3..47c05c1df6e 100644
--- a/mozilla/layout/generic/nsSpacerFrame.cpp
+++ b/mozilla/layout/generic/nsSpacerFrame.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object for HTML <spacer> element */
+
 #include "nsHTMLParts.h"
 #include "nsFrame.h"
 #include "nsLineLayout.h"
diff --git a/mozilla/layout/generic/nsSplittableFrame.cpp b/mozilla/layout/generic/nsSplittableFrame.cpp
index c00c2bae8b5..a368ed44a28 100644
--- a/mozilla/layout/generic/nsSplittableFrame.cpp
+++ b/mozilla/layout/generic/nsSplittableFrame.cpp
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * base class for rendering objects that can be split across lines,
+ * columns, or pages
+ */
+
 #include "nsSplittableFrame.h"
 #include "nsIContent.h"
 #include "nsPresContext.h"
diff --git a/mozilla/layout/generic/nsSplittableFrame.h b/mozilla/layout/generic/nsSplittableFrame.h
index 142b83c16a7..3e12cf3476c 100644
--- a/mozilla/layout/generic/nsSplittableFrame.h
+++ b/mozilla/layout/generic/nsSplittableFrame.h
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * base class for rendering objects that can be split across lines,
+ * columns, or pages
+ */
+
 #ifndef nsSplittableFrame_h___
 #define nsSplittableFrame_h___
 
diff --git a/mozilla/layout/generic/nsTextFrame.cpp b/mozilla/layout/generic/nsTextFrame.cpp
index fa475cc04a2..ef950ab91b0 100644
--- a/mozilla/layout/generic/nsTextFrame.cpp
+++ b/mozilla/layout/generic/nsTextFrame.cpp
@@ -45,6 +45,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rendering object for textual content of elements */
+
 #include "nsCOMPtr.h"
 #include "nsHTMLParts.h"
 #include "nsCRT.h"
diff --git a/mozilla/layout/generic/nsTextTransformer.cpp b/mozilla/layout/generic/nsTextTransformer.cpp
index 6be4bfbcc9a..bdef7854328 100644
--- a/mozilla/layout/generic/nsTextTransformer.cpp
+++ b/mozilla/layout/generic/nsTextTransformer.cpp
@@ -35,6 +35,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * class for transformation of text before rendering, including CSS
+ * text-transform
+ */
+
 #include <ctype.h>
 #include "nsCOMPtr.h"
 #include "nsTextTransformer.h"
diff --git a/mozilla/layout/generic/nsTextTransformer.h b/mozilla/layout/generic/nsTextTransformer.h
index 1b63b30e537..ab437ddc28a 100644
--- a/mozilla/layout/generic/nsTextTransformer.h
+++ b/mozilla/layout/generic/nsTextTransformer.h
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * class for transformation of text before rendering, including CSS
+ * text-transform
+ */
+
 #ifndef nsTextTransformer_h___
 #define nsTextTransformer_h___
 
diff --git a/mozilla/layout/generic/nsViewportFrame.cpp b/mozilla/layout/generic/nsViewportFrame.cpp
index 663586bd695..0a8828c20d5 100644
--- a/mozilla/layout/generic/nsViewportFrame.cpp
+++ b/mozilla/layout/generic/nsViewportFrame.cpp
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * rendering object that is the root of the frame tree, which contains
+ * the document's scrollbars and contains fixed-positioned elements
+ */
+
 #include "nsCOMPtr.h"
 #include "nsViewportFrame.h"
 #include "nsHTMLParts.h"
diff --git a/mozilla/layout/generic/nsViewportFrame.h b/mozilla/layout/generic/nsViewportFrame.h
index f808967c750..972613706d6 100644
--- a/mozilla/layout/generic/nsViewportFrame.h
+++ b/mozilla/layout/generic/nsViewportFrame.h
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * rendering object that is the root of the frame tree, which contains
+ * the document's scrollbars and contains fixed-positioned elements
+ */
+
 #ifndef nsViewportFrame_h___
 #define nsViewportFrame_h___