diff --git a/mozilla/layout/base/nsCSSColorUtils.cpp b/mozilla/layout/base/nsCSSColorUtils.cpp
index 632ea3d6bad..3baca90cc0f 100644
--- a/mozilla/layout/base/nsCSSColorUtils.cpp
+++ b/mozilla/layout/base/nsCSSColorUtils.cpp
@@ -35,6 +35,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* functions that manipulate colors */
+
 #include "nsCSSColorUtils.h"
 #include <math.h>
 
diff --git a/mozilla/layout/base/nsCSSColorUtils.h b/mozilla/layout/base/nsCSSColorUtils.h
index f3f6419baba..49b4c8857b7 100644
--- a/mozilla/layout/base/nsCSSColorUtils.h
+++ b/mozilla/layout/base/nsCSSColorUtils.h
@@ -35,6 +35,7 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* functions that manipulate colors */
 
 #ifndef __nsCSSColorUtils_h
 #define __nsCSSColorUtils_h
diff --git a/mozilla/layout/base/nsCSSFrameConstructor.cpp b/mozilla/layout/base/nsCSSFrameConstructor.cpp
index 4b5b3f544a7..d81ead44bcc 100644
--- a/mozilla/layout/base/nsCSSFrameConstructor.cpp
+++ b/mozilla/layout/base/nsCSSFrameConstructor.cpp
@@ -38,6 +38,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * construction of a frame tree that is nearly isomorphic to the content
+ * tree and updating of that tree in response to dynamic changes
+ */
+
 #include "nsCSSFrameConstructor.h"
 #include "nsCRT.h"
 #include "nsIAtom.h"
diff --git a/mozilla/layout/base/nsCSSFrameConstructor.h b/mozilla/layout/base/nsCSSFrameConstructor.h
index 3a6ebf2482d..8aabefe3875 100644
--- a/mozilla/layout/base/nsCSSFrameConstructor.h
+++ b/mozilla/layout/base/nsCSSFrameConstructor.h
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * construction of a frame tree that is nearly isomorphic to the content
+ * tree and updating of that tree in response to dynamic changes
+ */
+
 #ifndef nsCSSFrameConstructor_h___
 #define nsCSSFrameConstructor_h___
 
diff --git a/mozilla/layout/base/nsCSSRendering.cpp b/mozilla/layout/base/nsCSSRendering.cpp
index 6bb5be5894b..9d4ece821be 100644
--- a/mozilla/layout/base/nsCSSRendering.cpp
+++ b/mozilla/layout/base/nsCSSRendering.cpp
@@ -38,6 +38,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* utility functions for drawing borders and backgrounds */
+
 #include "nsStyleConsts.h"
 #include "nsPresContext.h"
 #include "nsIImage.h"
diff --git a/mozilla/layout/base/nsCSSRendering.h b/mozilla/layout/base/nsCSSRendering.h
index 28b38cdf737..7432a9289c0 100644
--- a/mozilla/layout/base/nsCSSRendering.h
+++ b/mozilla/layout/base/nsCSSRendering.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* utility functions for drawing borders and backgrounds */
+
 #ifndef nsCSSRendering_h___
 #define nsCSSRendering_h___
 
diff --git a/mozilla/layout/base/nsCaret.cpp b/mozilla/layout/base/nsCaret.cpp
index 0385d7e60a8..a589f06c4cf 100644
--- a/mozilla/layout/base/nsCaret.cpp
+++ b/mozilla/layout/base/nsCaret.cpp
@@ -37,6 +37,7 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* the caret is the text cursor used, e.g., when editing */
 
 #include "nsCOMPtr.h"
 
diff --git a/mozilla/layout/base/nsCaret.h b/mozilla/layout/base/nsCaret.h
index ecb57432328..b432f1e98a9 100644
--- a/mozilla/layout/base/nsCaret.h
+++ b/mozilla/layout/base/nsCaret.h
@@ -36,6 +36,7 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* the caret is the text cursor used, e.g., when editing */
 
 #include "nsCoord.h"
 #include "nsISelectionListener.h"
diff --git a/mozilla/layout/base/nsChangeHint.h b/mozilla/layout/base/nsChangeHint.h
index 1503a8f0c1f..c8cdebfc935 100644
--- a/mozilla/layout/base/nsChangeHint.h
+++ b/mozilla/layout/base/nsChangeHint.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* constants for what needs to be recomputed in response to style changes */
+
 #ifndef nsChangeHint_h___
 #define nsChangeHint_h___
 
diff --git a/mozilla/layout/base/nsChildIterator.cpp b/mozilla/layout/base/nsChildIterator.cpp
index 6d64db97306..c7c5eab75cc 100644
--- a/mozilla/layout/base/nsChildIterator.cpp
+++ b/mozilla/layout/base/nsChildIterator.cpp
@@ -36,6 +36,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * used by nsCSSFrameConstructor to determine and iterate the child list
+ * used to construct frames (normal children or something from XBL)
+ */
+
 #include "nsChildIterator.h"
 #include "nsIDocument.h"
 #include "nsIBindingManager.h"
diff --git a/mozilla/layout/base/nsChildIterator.h b/mozilla/layout/base/nsChildIterator.h
index fc1e2c7cd23..2974ab4c054 100644
--- a/mozilla/layout/base/nsChildIterator.h
+++ b/mozilla/layout/base/nsChildIterator.h
@@ -36,6 +36,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * used by nsCSSFrameConstructor to determine and iterate the child list
+ * used to construct frames (normal children or something from XBL)
+ */
+
 #include "nsCOMPtr.h"
 #include "nsIContent.h"
 #include "nsIDOMNodeList.h"
diff --git a/mozilla/layout/base/nsCompatibility.h b/mozilla/layout/base/nsCompatibility.h
index 61a3d022201..21cea745fce 100644
--- a/mozilla/layout/base/nsCompatibility.h
+++ b/mozilla/layout/base/nsCompatibility.h
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* constants for quirks mode, standards mode, and almost standards mode */
+
 #ifndef nsCompatibility_h___
 #define nsCompatibility_h___
 
diff --git a/mozilla/layout/base/nsCounterManager.cpp b/mozilla/layout/base/nsCounterManager.cpp
index 949b266f95b..fbc31c1866d 100644
--- a/mozilla/layout/base/nsCounterManager.cpp
+++ b/mozilla/layout/base/nsCounterManager.cpp
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* implementation of CSS counters (for numbering things) */
+
 #include "nsCounterManager.h"
 #include "nsBulletFrame.h" // legacy location for list style type to text code
 #include "nsContentUtils.h"
diff --git a/mozilla/layout/base/nsCounterManager.h b/mozilla/layout/base/nsCounterManager.h
index a62bf3571b8..0c341ed36dd 100644
--- a/mozilla/layout/base/nsCounterManager.h
+++ b/mozilla/layout/base/nsCounterManager.h
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* implementation of CSS counters (for numbering things) */
+
 #ifndef nsCounterManager_h_
 #define nsCounterManager_h_
 
diff --git a/mozilla/layout/base/nsDisplayList.cpp b/mozilla/layout/base/nsDisplayList.cpp
index f1ab0431ff7..d16c3c61b52 100644
--- a/mozilla/layout/base/nsDisplayList.cpp
+++ b/mozilla/layout/base/nsDisplayList.cpp
@@ -35,6 +35,11 @@
  * ***** END LICENSE BLOCK *****
  */
 
+/*
+ * structures that represent things to be painted (ordered in z-order),
+ * used during painting and hit testing
+ */
+
 #include "nsDisplayList.h"
 
 #include "nsCSSRendering.h"
diff --git a/mozilla/layout/base/nsDisplayList.h b/mozilla/layout/base/nsDisplayList.h
index 612549ce517..26731e43d6b 100644
--- a/mozilla/layout/base/nsDisplayList.h
+++ b/mozilla/layout/base/nsDisplayList.h
@@ -35,6 +35,11 @@
  * ***** END LICENSE BLOCK *****
  */
 
+/*
+ * structures that represent things to be painted (ordered in z-order),
+ * used during painting and hit testing
+ */
+
 #ifndef NSDISPLAYLIST_H_
 #define NSDISPLAYLIST_H_
 
diff --git a/mozilla/layout/base/nsDocumentViewer.cpp b/mozilla/layout/base/nsDocumentViewer.cpp
index e52dbf6f9e9..6b68d88679e 100644
--- a/mozilla/layout/base/nsDocumentViewer.cpp
+++ b/mozilla/layout/base/nsDocumentViewer.cpp
@@ -38,6 +38,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* container for a document and its presentation */
+
 #include "nscore.h"
 #include "nsCOMPtr.h"
 #include "nsCRT.h"
diff --git a/mozilla/layout/base/nsFrameManager.cpp b/mozilla/layout/base/nsFrameManager.cpp
index 9ad9176263f..fa8a8431cda 100644
--- a/mozilla/layout/base/nsFrameManager.cpp
+++ b/mozilla/layout/base/nsFrameManager.cpp
@@ -44,6 +44,9 @@
  * Date             Modified by     Description of modification
  * 04/20/2000       IBM Corp.      OS/2 VisualAge build.
  */
+
+/* storage of the frame tree and information about it */
+
 #include "nscore.h"
 #include "nsPresContext.h"
 #include "nsIPresShell.h"
diff --git a/mozilla/layout/base/nsFrameManager.h b/mozilla/layout/base/nsFrameManager.h
index df62efd3e01..2aad97af040 100644
--- a/mozilla/layout/base/nsFrameManager.h
+++ b/mozilla/layout/base/nsFrameManager.h
@@ -47,6 +47,8 @@
  * 04/20/2000       IBM Corp.      OS/2 VisualAge build.
  */
 
+/* storage of the frame tree and information about it */
+
 #ifndef _nsFrameManager_h_
 #define _nsFrameManager_h_
 
diff --git a/mozilla/layout/base/nsFrameManagerBase.h b/mozilla/layout/base/nsFrameManagerBase.h
index 8806b61b8ac..193b967f587 100644
--- a/mozilla/layout/base/nsFrameManagerBase.h
+++ b/mozilla/layout/base/nsFrameManagerBase.h
@@ -48,6 +48,8 @@
  * 04/20/2000       IBM Corp.      OS/2 VisualAge build.
  */
 
+/* part of nsFrameManager, to work around header inclusionordering */
+
 #ifndef _nsFrameManagerBase_h_
 #define _nsFrameManagerBase_h_
 
diff --git a/mozilla/layout/base/nsGenConList.cpp b/mozilla/layout/base/nsGenConList.cpp
index 5a7c6f46011..455b956cfa3 100644
--- a/mozilla/layout/base/nsGenConList.cpp
+++ b/mozilla/layout/base/nsGenConList.cpp
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* base class for nsCounterList and nsQuoteList */
+
 #include "nsGenConList.h"
 #include "nsLayoutUtils.h"
 
diff --git a/mozilla/layout/base/nsGenConList.h b/mozilla/layout/base/nsGenConList.h
index 81ebf6347d8..30ea8768051 100644
--- a/mozilla/layout/base/nsGenConList.h
+++ b/mozilla/layout/base/nsGenConList.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* base class for nsCounterList and nsQuoteList */
+
 #ifndef nsGenConList_h___
 #define nsGenConList_h___
 
diff --git a/mozilla/layout/base/nsICaret.h b/mozilla/layout/base/nsICaret.h
index 44174c72478..af7d90dcaae 100644
--- a/mozilla/layout/base/nsICaret.h
+++ b/mozilla/layout/base/nsICaret.h
@@ -35,6 +35,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* the caret is the text cursor used, e.g., when editing */
+
 #ifndef nsICaret_h__
 #define nsICaret_h__
 
diff --git a/mozilla/layout/base/nsIDocumentViewer.h b/mozilla/layout/base/nsIDocumentViewer.h
index 9c65cd81c10..a6080b37f55 100644
--- a/mozilla/layout/base/nsIDocumentViewer.h
+++ b/mozilla/layout/base/nsIDocumentViewer.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* container for a document and its presentation */
+
 #ifndef nsIDocumentViewer_h___
 #define nsIDocumentViewer_h___
 
diff --git a/mozilla/layout/base/nsIImageMap.h b/mozilla/layout/base/nsIImageMap.h
index fa2f1b40610..abac389b125 100644
--- a/mozilla/layout/base/nsIImageMap.h
+++ b/mozilla/layout/base/nsIImageMap.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* interface for HTML client-side image maps */
+
 #ifndef nsIImageMap_h___
 #define nsIImageMap_h___
 
diff --git a/mozilla/layout/base/nsILayoutDebugger.h b/mozilla/layout/base/nsILayoutDebugger.h
index 916eb521452..4da04bceae1 100644
--- a/mozilla/layout/base/nsILayoutDebugger.h
+++ b/mozilla/layout/base/nsILayoutDebugger.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* XPCOM interface for layout-debug extension to reach layout internals */
+
 #ifndef nsILayoutDebugger_h___
 #define nsILayoutDebugger_h___
 
diff --git a/mozilla/layout/base/nsILayoutHistoryState.h b/mozilla/layout/base/nsILayoutHistoryState.h
index 37aae4bb7fb..1df07a1da45 100644
--- a/mozilla/layout/base/nsILayoutHistoryState.h
+++ b/mozilla/layout/base/nsILayoutHistoryState.h
@@ -36,6 +36,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * interface for container for information saved in session history when
+ * the document is not
+ */
+
 #ifndef _nsILayoutHistoryState_h
 #define _nsILayoutHistoryState_h
 
diff --git a/mozilla/layout/base/nsIPresShell.h b/mozilla/layout/base/nsIPresShell.h
index bb1abfc6c71..a4b7ad59ace 100644
--- a/mozilla/layout/base/nsIPresShell.h
+++ b/mozilla/layout/base/nsIPresShell.h
@@ -48,6 +48,9 @@
  * Date         Modified by     Description of modification
  * 05/03/2000   IBM Corp.       Observer related defines for reflow
  */
+
+/* a presentation of a document, part 2 */
+
 #ifndef nsIPresShell_h___
 #define nsIPresShell_h___
 
diff --git a/mozilla/layout/base/nsIStyleSheetService.idl b/mozilla/layout/base/nsIStyleSheetService.idl
index 92c39d30f15..375ec5f0e2b 100644
--- a/mozilla/layout/base/nsIStyleSheetService.idl
+++ b/mozilla/layout/base/nsIStyleSheetService.idl
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* interface for managing user and user-agent style sheets */
+
 #include "nsISupports.idl"
 
 interface nsIURI;
diff --git a/mozilla/layout/base/nsImageLoader.cpp b/mozilla/layout/base/nsImageLoader.cpp
index c58eca1e81e..91da982d2b4 100644
--- a/mozilla/layout/base/nsImageLoader.cpp
+++ b/mozilla/layout/base/nsImageLoader.cpp
@@ -37,6 +37,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* class to notify frames of background image loads */
+
 #include "nsImageLoader.h"
 
 #include "imgILoader.h"
diff --git a/mozilla/layout/base/nsImageLoader.h b/mozilla/layout/base/nsImageLoader.h
index 90616c9588a..5e33e739a39 100644
--- a/mozilla/layout/base/nsImageLoader.h
+++ b/mozilla/layout/base/nsImageLoader.h
@@ -37,6 +37,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* class to notify frames of background image loads */
+
 #include "imgIDecoderObserver.h"
 
 class nsPresContext;
diff --git a/mozilla/layout/base/nsLayoutAtoms.h b/mozilla/layout/base/nsLayoutAtoms.h
index b50881b5b9a..b0a50a3986a 100644
--- a/mozilla/layout/base/nsLayoutAtoms.h
+++ b/mozilla/layout/base/nsLayoutAtoms.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* atom list */
+
 #ifndef nsLayoutAtoms_h___
 #define nsLayoutAtoms_h___
 
diff --git a/mozilla/layout/base/nsLayoutDebugger.cpp b/mozilla/layout/base/nsLayoutDebugger.cpp
index 4389b0995bd..884a81ed315 100644
--- a/mozilla/layout/base/nsLayoutDebugger.cpp
+++ b/mozilla/layout/base/nsLayoutDebugger.cpp
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * implementation of interface that allows layout-debug extension access
+ * to some internals of layout
+ */
+
 #include "nsILayoutDebugger.h"
 #include "nsIFrame.h"
 #include "nsIFrameDebug.h"
diff --git a/mozilla/layout/base/nsLayoutHistoryState.cpp b/mozilla/layout/base/nsLayoutHistoryState.cpp
index dad8867e659..2d879ca89a7 100644
--- a/mozilla/layout/base/nsLayoutHistoryState.cpp
+++ b/mozilla/layout/base/nsLayoutHistoryState.cpp
@@ -41,6 +41,11 @@
 #include "nsClassHashtable.h"
 #include "nsPresState.h"
 
+/*
+ * container for information saved in session history when the document
+ * is not
+ */
+
 class nsLayoutHistoryState : public nsILayoutHistoryState,
                              public nsSupportsWeakReference
 {
diff --git a/mozilla/layout/base/nsPresContext.cpp b/mozilla/layout/base/nsPresContext.cpp
index 9d3ee70af15..3e57b115ec6 100644
--- a/mozilla/layout/base/nsPresContext.cpp
+++ b/mozilla/layout/base/nsPresContext.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* a presentation of a document, part 1 */
+
 #include "nsCOMPtr.h"
 #include "nsPresContext.h"
 #include "nsIPresShell.h"
diff --git a/mozilla/layout/base/nsPresContext.h b/mozilla/layout/base/nsPresContext.h
index 9929cfabac1..c16901712cc 100644
--- a/mozilla/layout/base/nsPresContext.h
+++ b/mozilla/layout/base/nsPresContext.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* a presentation of a document, part 1 */
+
 #ifndef nsPresContext_h___
 #define nsPresContext_h___
 
diff --git a/mozilla/layout/base/nsPresShell.cpp b/mozilla/layout/base/nsPresShell.cpp
index 8fa4c39c01e..f3a01efe43c 100644
--- a/mozilla/layout/base/nsPresShell.cpp
+++ b/mozilla/layout/base/nsPresShell.cpp
@@ -52,6 +52,8 @@
  * 05/03/2000   IBM Corp.       Observer events for reflow states
  */ 
 
+/* a presentation of a document, part 2 */
+
 #define PL_ARENA_CONST_ALIGN_MASK 3
 
 #include "nsIPresShell.h"
diff --git a/mozilla/layout/base/nsPresState.cpp b/mozilla/layout/base/nsPresState.cpp
index bae38c3e5c4..a2563b1a772 100644
--- a/mozilla/layout/base/nsPresState.cpp
+++ b/mozilla/layout/base/nsPresState.cpp
@@ -35,6 +35,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * a piece of state that is stored in session history when the document
+ * is not
+ */
+
 #include "nsCOMPtr.h"
 #include "nsXPCOM.h"
 #include "nsISupportsPrimitives.h"
diff --git a/mozilla/layout/base/nsPresState.h b/mozilla/layout/base/nsPresState.h
index 115770d8006..0c026436435 100755
--- a/mozilla/layout/base/nsPresState.h
+++ b/mozilla/layout/base/nsPresState.h
@@ -35,6 +35,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * a piece of state that is stored in session history when the document
+ * is not
+ */
+
 #ifndef nsPresState_h_
 #define nsPresState_h_
 
diff --git a/mozilla/layout/base/nsQuoteList.cpp b/mozilla/layout/base/nsQuoteList.cpp
index 887fdeaea76..4395593aed8 100644
--- a/mozilla/layout/base/nsQuoteList.cpp
+++ b/mozilla/layout/base/nsQuoteList.cpp
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* implementation of quotes for the CSS 'content' property */
+
 #include "nsQuoteList.h"
 #include "nsReadableUtils.h"
 
diff --git a/mozilla/layout/base/nsQuoteList.h b/mozilla/layout/base/nsQuoteList.h
index db3c4939063..1e6b062d0ba 100644
--- a/mozilla/layout/base/nsQuoteList.h
+++ b/mozilla/layout/base/nsQuoteList.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* implementation of quotes for the CSS 'content' property */
+
 #ifndef nsQuoteList_h___
 #define nsQuoteList_h___
 
diff --git a/mozilla/layout/base/nsStyleChangeList.cpp b/mozilla/layout/base/nsStyleChangeList.cpp
index c178752794b..13195783f0a 100644
--- a/mozilla/layout/base/nsStyleChangeList.cpp
+++ b/mozilla/layout/base/nsStyleChangeList.cpp
@@ -35,6 +35,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * a list of the recomputation that needs to be done in response to a
+ * style change
+ */
+
 #include "nsStyleChangeList.h"
 #include "nsStyleConsts.h"
 #include "nsIFrame.h"
diff --git a/mozilla/layout/base/nsStyleChangeList.h b/mozilla/layout/base/nsStyleChangeList.h
index 68c4a13051d..b2a158ff958 100644
--- a/mozilla/layout/base/nsStyleChangeList.h
+++ b/mozilla/layout/base/nsStyleChangeList.h
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * a list of the recomputation that needs to be done in response to a
+ * style change
+ */
+
 #ifndef nsStyleChangeList_h___
 #define nsStyleChangeList_h___
 
diff --git a/mozilla/layout/base/nsStyleConsts.h b/mozilla/layout/base/nsStyleConsts.h
index 69ec36db6ac..3b24a9a4a75 100644
--- a/mozilla/layout/base/nsStyleConsts.h
+++ b/mozilla/layout/base/nsStyleConsts.h
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* constants used in the nsStyleStruct data provided by nsStyleContext */
+
 #ifndef nsStyleConsts_h___
 #define nsStyleConsts_h___
 
diff --git a/mozilla/layout/base/nsStyleSheetService.cpp b/mozilla/layout/base/nsStyleSheetService.cpp
index d6c3e6e88a8..27ebe39a07e 100644
--- a/mozilla/layout/base/nsStyleSheetService.cpp
+++ b/mozilla/layout/base/nsStyleSheetService.cpp
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* implementation of interface for managing user and user-agent style sheets */
+
 #include "nsStyleSheetService.h"
 #include "nsIStyleSheet.h"
 #include "nsICSSLoader.h"
diff --git a/mozilla/layout/base/nsStyleSheetService.h b/mozilla/layout/base/nsStyleSheetService.h
index 16b896c592f..fe63ef71a63 100644
--- a/mozilla/layout/base/nsStyleSheetService.h
+++ b/mozilla/layout/base/nsStyleSheetService.h
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* implementation of interface for managing user and user-agent style sheets */
+
 #ifndef nsStyleSheetService_h_
 #define nsStyleSheetService_h_