From a02fd2d2f8221cd6968590073d8556e18cd23fb4 Mon Sep 17 00:00:00 2001
From: "dbaron%dbaron.org"
 <dbaron%dbaron.org@18797224-902f-48f8-a5cc-f745e15eee43>
Date: Sat, 25 Mar 2006 05:47:31 +0000
Subject: [PATCH] File comments that show up in LXR and provide a quick summary
 of what's in each file.

git-svn-id: svn://10.0.0.236/trunk@192979 18797224-902f-48f8-a5cc-f745e15eee43
---
 mozilla/layout/style/nsCSSAnonBoxList.h          | 2 ++
 mozilla/layout/style/nsCSSAnonBoxes.cpp          | 3 +++
 mozilla/layout/style/nsCSSAnonBoxes.h            | 3 +++
 mozilla/layout/style/nsCSSDataBlock.cpp          | 5 +++++
 mozilla/layout/style/nsCSSDataBlock.h            | 6 ++++++
 mozilla/layout/style/nsCSSDeclaration.cpp        | 6 ++++++
 mozilla/layout/style/nsCSSDeclaration.h          | 6 ++++++
 mozilla/layout/style/nsCSSKeywordList.h          | 2 ++
 mozilla/layout/style/nsCSSKeywords.cpp           | 2 ++
 mozilla/layout/style/nsCSSKeywords.h             | 3 +++
 mozilla/layout/style/nsCSSLoader.cpp             | 3 +++
 mozilla/layout/style/nsCSSLoader.h               | 2 ++
 mozilla/layout/style/nsCSSOMFactory.cpp          | 2 ++
 mozilla/layout/style/nsCSSOMFactory.h            | 2 ++
 mozilla/layout/style/nsCSSParser.cpp             | 3 +++
 mozilla/layout/style/nsCSSPropList.h             | 5 +++++
 mozilla/layout/style/nsCSSProps.cpp              | 5 +++++
 mozilla/layout/style/nsCSSProps.h                | 6 ++++++
 mozilla/layout/style/nsCSSPseudoClassList.h      | 2 ++
 mozilla/layout/style/nsCSSPseudoClasses.cpp      | 3 +++
 mozilla/layout/style/nsCSSPseudoClasses.h        | 3 +++
 mozilla/layout/style/nsCSSPseudoElementList.h    | 2 ++
 mozilla/layout/style/nsCSSPseudoElements.cpp     | 3 +++
 mozilla/layout/style/nsCSSPseudoElements.h       | 3 +++
 mozilla/layout/style/nsCSSRule.cpp               | 3 +++
 mozilla/layout/style/nsCSSRule.h                 | 3 +++
 mozilla/layout/style/nsCSSRuleProcessor.h        | 5 +++++
 mozilla/layout/style/nsCSSRules.cpp              | 3 +++
 mozilla/layout/style/nsCSSRules.h                | 3 +++
 mozilla/layout/style/nsCSSScanner.cpp            | 3 +++
 mozilla/layout/style/nsCSSScanner.h              | 3 +++
 mozilla/layout/style/nsCSSStruct.cpp             | 7 +++++++
 mozilla/layout/style/nsCSSStruct.h               | 7 +++++++
 mozilla/layout/style/nsCSSStyleRule.cpp          | 7 +++++++
 mozilla/layout/style/nsCSSStyleSheet.cpp         | 2 ++
 mozilla/layout/style/nsCSSStyleSheet.h           | 2 ++
 mozilla/layout/style/nsCSSValue.cpp              | 3 +++
 mozilla/layout/style/nsCSSValue.h                | 3 +++
 mozilla/layout/style/nsComputedDOMStyle.cpp      | 2 ++
 mozilla/layout/style/nsComputedDOMStyle.h        | 2 ++
 mozilla/layout/style/nsDOMCSSAttrDeclaration.cpp | 2 ++
 mozilla/layout/style/nsDOMCSSAttrDeclaration.h   | 2 ++
 mozilla/layout/style/nsDOMCSSDeclaration.cpp     | 2 ++
 mozilla/layout/style/nsDOMCSSDeclaration.h       | 3 +++
 mozilla/layout/style/nsDOMCSSRGBColor.cpp        | 2 ++
 mozilla/layout/style/nsDOMCSSRGBColor.h          | 2 ++
 mozilla/layout/style/nsDOMCSSRect.cpp            | 2 ++
 mozilla/layout/style/nsDOMCSSRect.h              | 8 +++++---
 mozilla/layout/style/nsDOMCSSValueList.cpp       | 2 ++
 mozilla/layout/style/nsDOMCSSValueList.h         | 2 ++
 mozilla/layout/style/nsHTMLCSSStyleSheet.cpp     | 5 +++++
 mozilla/layout/style/nsHTMLStyleSheet.cpp        | 5 +++++
 mozilla/layout/style/nsHTMLStyleSheet.h          | 6 ++++++
 mozilla/layout/style/nsICSSDeclaration.h         | 5 +++++
 mozilla/layout/style/nsICSSGroupRule.h           | 6 ++++++
 mozilla/layout/style/nsICSSImportRule.h          | 3 +++
 mozilla/layout/style/nsICSSLoader.h              | 3 +++
 mozilla/layout/style/nsICSSLoaderObserver.h      | 3 +++
 mozilla/layout/style/nsICSSNameSpaceRule.h       | 2 ++
 mozilla/layout/style/nsICSSOMFactory.h           | 2 ++
 mozilla/layout/style/nsICSSParser.h              | 9 ++++++---
 mozilla/layout/style/nsICSSPseudoComparator.h    | 3 +++
 mozilla/layout/style/nsICSSRule.h                | 5 ++++-
 mozilla/layout/style/nsICSSStyleRule.h           | 6 ++++++
 mozilla/layout/style/nsICSSStyleRuleDOMWrapper.h | 5 +++++
 mozilla/layout/style/nsICSSStyleSheet.h          | 3 +++
 mozilla/layout/style/nsIComputedDOMStyle.h       | 3 +++
 mozilla/layout/style/nsIHTMLCSSStyleSheet.h      | 6 ++++++
 mozilla/layout/style/nsIInspectorCSSUtils.h      | 2 ++
 mozilla/layout/style/nsIMediaList.h              | 6 ++++++
 mozilla/layout/style/nsIStyleRule.h              | 6 ++++++
 mozilla/layout/style/nsIStyleRuleProcessor.h     | 7 +++++++
 mozilla/layout/style/nsIStyleRuleSupplier.h      | 6 ++++++
 mozilla/layout/style/nsIStyleSheet.h             | 6 ++++++
 mozilla/layout/style/nsInspectorCSSUtils.cpp     | 2 ++
 mozilla/layout/style/nsInspectorCSSUtils.h       | 2 ++
 mozilla/layout/style/nsROCSSPrimitiveValue.cpp   | 2 ++
 mozilla/layout/style/nsROCSSPrimitiveValue.h     | 2 ++
 mozilla/layout/style/nsRuleData.h                | 5 +++++
 mozilla/layout/style/nsRuleNode.cpp              | 5 +++++
 mozilla/layout/style/nsRuleNode.h                | 5 +++++
 mozilla/layout/style/nsRuleWalker.h              | 5 +++++
 mozilla/layout/style/nsStyleContext.cpp          | 2 ++
 mozilla/layout/style/nsStyleContext.h            | 2 ++
 mozilla/layout/style/nsStyleCoord.cpp            | 2 ++
 mozilla/layout/style/nsStyleCoord.h              | 3 +++
 mozilla/layout/style/nsStyleSet.cpp              | 7 +++++++
 mozilla/layout/style/nsStyleSet.h                | 6 ++++++
 mozilla/layout/style/nsStyleStruct.cpp           | 5 +++++
 mozilla/layout/style/nsStyleStruct.h             | 6 ++++++
 mozilla/layout/style/nsStyleStructList.h         | 5 +++++
 91 files changed, 339 insertions(+), 7 deletions(-)

diff --git a/mozilla/layout/style/nsCSSAnonBoxList.h b/mozilla/layout/style/nsCSSAnonBoxList.h
index 7699e74f46e..52802381bc5 100644
--- a/mozilla/layout/style/nsCSSAnonBoxList.h
+++ b/mozilla/layout/style/nsCSSAnonBoxList.h
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* atom list for CSS anonymous boxes */
+
 /*
  * This file contains the list of nsIAtoms and their values for CSS
  * pseudo-element-ish things used internally for anonymous boxes.  It is
diff --git a/mozilla/layout/style/nsCSSAnonBoxes.cpp b/mozilla/layout/style/nsCSSAnonBoxes.cpp
index e2f858bad3a..d9b127696bb 100644
--- a/mozilla/layout/style/nsCSSAnonBoxes.cpp
+++ b/mozilla/layout/style/nsCSSAnonBoxes.cpp
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* atom list for CSS anonymous boxes */
+
 #include "nsCSSAnonBoxes.h"
 #include "nsAtomListUtils.h"
 #include "nsStaticAtom.h"
diff --git a/mozilla/layout/style/nsCSSAnonBoxes.h b/mozilla/layout/style/nsCSSAnonBoxes.h
index 120e1bdae78..92a98689214 100644
--- a/mozilla/layout/style/nsCSSAnonBoxes.h
+++ b/mozilla/layout/style/nsCSSAnonBoxes.h
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* atom list for CSS anonymous boxes */
+
 #ifndef nsCSSAnonBoxes_h___
 #define nsCSSAnonBoxes_h___
 
diff --git a/mozilla/layout/style/nsCSSDataBlock.cpp b/mozilla/layout/style/nsCSSDataBlock.cpp
index 46af2cab058..97b8778b3c7 100644
--- a/mozilla/layout/style/nsCSSDataBlock.cpp
+++ b/mozilla/layout/style/nsCSSDataBlock.cpp
@@ -35,6 +35,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * compact representation of the property-value pairs within a CSS
+ * declaration, and the code for expanding and compacting it
+ */
+
 #include "nsCSSDataBlock.h"
 #include "nsCSSProps.h"
 #include "nsRuleData.h"
diff --git a/mozilla/layout/style/nsCSSDataBlock.h b/mozilla/layout/style/nsCSSDataBlock.h
index 11161d41272..e36263ec6a6 100644
--- a/mozilla/layout/style/nsCSSDataBlock.h
+++ b/mozilla/layout/style/nsCSSDataBlock.h
@@ -33,6 +33,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * compact representation of the property-value pairs within a CSS
+ * declaration, and the code for expanding and compacting it
+ */
+
 #ifndef nsCSSDataBlock_h__
 #define nsCSSDataBlock_h__
 
diff --git a/mozilla/layout/style/nsCSSDeclaration.cpp b/mozilla/layout/style/nsCSSDeclaration.cpp
index ab39d4f4852..5b3d3ba88f6 100644
--- a/mozilla/layout/style/nsCSSDeclaration.cpp
+++ b/mozilla/layout/style/nsCSSDeclaration.cpp
@@ -36,6 +36,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * representation of a declaration block (or style attribute) in a CSS
+ * stylesheet
+ */
+
 #include "nscore.h"
 #include "nsCSSDeclaration.h"
 #include "nsString.h"
diff --git a/mozilla/layout/style/nsCSSDeclaration.h b/mozilla/layout/style/nsCSSDeclaration.h
index 00605501c8c..fefb78dd225 100644
--- a/mozilla/layout/style/nsCSSDeclaration.h
+++ b/mozilla/layout/style/nsCSSDeclaration.h
@@ -35,6 +35,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * representation of a declaration block (or style attribute) in a CSS
+ * stylesheet
+ */
+
 #ifndef nsCSSDeclaration_h___
 #define nsCSSDeclaration_h___
 
diff --git a/mozilla/layout/style/nsCSSKeywordList.h b/mozilla/layout/style/nsCSSKeywordList.h
index c302ec07546..db4ee858593 100644
--- a/mozilla/layout/style/nsCSSKeywordList.h
+++ b/mozilla/layout/style/nsCSSKeywordList.h
@@ -35,6 +35,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* keywords used within CSS property values */
+
 /******
 
   This file contains the list of all parsed CSS keywords
diff --git a/mozilla/layout/style/nsCSSKeywords.cpp b/mozilla/layout/style/nsCSSKeywords.cpp
index 188298dc042..e1f335a164c 100644
--- a/mozilla/layout/style/nsCSSKeywords.cpp
+++ b/mozilla/layout/style/nsCSSKeywords.cpp
@@ -35,6 +35,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* keywords used within CSS property values */
+
 #include "nsCSSKeywords.h"
 #include "nsString.h"
 #include "nsStaticNameTable.h"
diff --git a/mozilla/layout/style/nsCSSKeywords.h b/mozilla/layout/style/nsCSSKeywords.h
index 20ad818ff57..b83d64e62cd 100644
--- a/mozilla/layout/style/nsCSSKeywords.h
+++ b/mozilla/layout/style/nsCSSKeywords.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* keywords used within CSS property values */
+
 #ifndef nsCSSKeywords_h___
 #define nsCSSKeywords_h___
 
diff --git a/mozilla/layout/style/nsCSSLoader.cpp b/mozilla/layout/style/nsCSSLoader.cpp
index f3a0f8dabeb..650609c69a4 100644
--- a/mozilla/layout/style/nsCSSLoader.cpp
+++ b/mozilla/layout/style/nsCSSLoader.cpp
@@ -44,6 +44,9 @@
  * Date             Modified by     Description of modification
  * 04/20/2000       IBM Corp.      OS/2 VisualAge build.
  */
+
+/* loading of CSS style sheets using the network APIs */
+
 #include "nsCSSLoader.h"
 #include "nsIContent.h"
 #include "nsIDOMNode.h"
diff --git a/mozilla/layout/style/nsCSSLoader.h b/mozilla/layout/style/nsCSSLoader.h
index 93673484009..75b95932b25 100644
--- a/mozilla/layout/style/nsCSSLoader.h
+++ b/mozilla/layout/style/nsCSSLoader.h
@@ -46,6 +46,8 @@
  * 04/20/2000       IBM Corp.      OS/2 VisualAge build.
  */
 
+/* loading of CSS style sheets using the network APIs */
+
 #ifndef nsCSSLoader_h__
 #define nsCSSLoader_h__
 
diff --git a/mozilla/layout/style/nsCSSOMFactory.cpp b/mozilla/layout/style/nsCSSOMFactory.cpp
index ec7fa10506e..77a735f1195 100644
--- a/mozilla/layout/style/nsCSSOMFactory.cpp
+++ b/mozilla/layout/style/nsCSSOMFactory.cpp
@@ -37,6 +37,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* an XPCOM service for cross-module creation of DOM .style objects */
+
 #include "nsCSSOMFactory.h"
 #include "nsDOMCSSAttrDeclaration.h"
 
diff --git a/mozilla/layout/style/nsCSSOMFactory.h b/mozilla/layout/style/nsCSSOMFactory.h
index 2a339cf9264..0c4e1cde547 100644
--- a/mozilla/layout/style/nsCSSOMFactory.h
+++ b/mozilla/layout/style/nsCSSOMFactory.h
@@ -37,6 +37,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* an XPCOM service for cross-module creation of DOM .style objects */
+
 #ifndef nsCSSOMFactory_h___
 #define nsCSSOMFactory_h___
 
diff --git a/mozilla/layout/style/nsCSSParser.cpp b/mozilla/layout/style/nsCSSParser.cpp
index 377f7cbd0f1..4e9804bf59a 100644
--- a/mozilla/layout/style/nsCSSParser.cpp
+++ b/mozilla/layout/style/nsCSSParser.cpp
@@ -40,6 +40,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* parsing of CSS stylesheets, based on a token stream from the CSS scanner */
+ 
 #include "nsICSSParser.h"
 #include "nsCSSProps.h"
 #include "nsCSSKeywords.h"
diff --git a/mozilla/layout/style/nsCSSPropList.h b/mozilla/layout/style/nsCSSPropList.h
index 6704d533e8b..3d3a0a67c3d 100644
--- a/mozilla/layout/style/nsCSSPropList.h
+++ b/mozilla/layout/style/nsCSSPropList.h
@@ -36,6 +36,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * a list of all CSS properties with considerable data about them, for
+ * preprocessing
+ */
+
 /******
 
   This file contains the list of all parsed CSS properties.  It is
diff --git a/mozilla/layout/style/nsCSSProps.cpp b/mozilla/layout/style/nsCSSProps.cpp
index 71a88887b81..338a968b71a 100644
--- a/mozilla/layout/style/nsCSSProps.cpp
+++ b/mozilla/layout/style/nsCSSProps.cpp
@@ -36,6 +36,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * methods for dealing with CSS properties and tables of the keyword
+ * values they accept
+ */
+
 #include "nsCSSProps.h"
 #include "nsCSSKeywords.h"
 #include "nsStyleConsts.h"
diff --git a/mozilla/layout/style/nsCSSProps.h b/mozilla/layout/style/nsCSSProps.h
index 5285abc28c0..7e1b916fc8a 100644
--- a/mozilla/layout/style/nsCSSProps.h
+++ b/mozilla/layout/style/nsCSSProps.h
@@ -35,6 +35,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * methods for dealing with CSS properties and tables of the keyword
+ * values they accept
+ */
+
 #ifndef nsCSSProps_h___
 #define nsCSSProps_h___
 
diff --git a/mozilla/layout/style/nsCSSPseudoClassList.h b/mozilla/layout/style/nsCSSPseudoClassList.h
index 0501cbf63c2..5a15bf01a8d 100644
--- a/mozilla/layout/style/nsCSSPseudoClassList.h
+++ b/mozilla/layout/style/nsCSSPseudoClassList.h
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* atom list for CSS pseudo-classes */
+
 /*
  * This file contains the list of nsIAtoms and their values for CSS
  * pseudo-classes.  It is designed to be used as inline input to
diff --git a/mozilla/layout/style/nsCSSPseudoClasses.cpp b/mozilla/layout/style/nsCSSPseudoClasses.cpp
index daf5c873582..8259b0192cb 100644
--- a/mozilla/layout/style/nsCSSPseudoClasses.cpp
+++ b/mozilla/layout/style/nsCSSPseudoClasses.cpp
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* atom list for CSS pseudo-classes */
+
 #include "nsCSSPseudoClasses.h"
 #include "nsAtomListUtils.h"
 #include "nsStaticAtom.h"
diff --git a/mozilla/layout/style/nsCSSPseudoClasses.h b/mozilla/layout/style/nsCSSPseudoClasses.h
index 6c4617ac95d..bb7257d9d80 100644
--- a/mozilla/layout/style/nsCSSPseudoClasses.h
+++ b/mozilla/layout/style/nsCSSPseudoClasses.h
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* atom list for CSS pseudo-classes */
+
 #ifndef nsCSSPseudoClasses_h___
 #define nsCSSPseudoClasses_h___
 
diff --git a/mozilla/layout/style/nsCSSPseudoElementList.h b/mozilla/layout/style/nsCSSPseudoElementList.h
index 24a90a69e93..40e35c512d1 100644
--- a/mozilla/layout/style/nsCSSPseudoElementList.h
+++ b/mozilla/layout/style/nsCSSPseudoElementList.h
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* atom list for CSS pseudo-elements */
+
 /*
  * This file contains the list of nsIAtoms and their values for CSS
  * pseudo-elements.  It is designed to be used as inline input to
diff --git a/mozilla/layout/style/nsCSSPseudoElements.cpp b/mozilla/layout/style/nsCSSPseudoElements.cpp
index 9747240a73d..4b2fc04f2d0 100644
--- a/mozilla/layout/style/nsCSSPseudoElements.cpp
+++ b/mozilla/layout/style/nsCSSPseudoElements.cpp
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* atom list for CSS pseudo-elements */
+
 #include "nsCSSPseudoElements.h"
 #include "nsAtomListUtils.h"
 #include "nsStaticAtom.h"
diff --git a/mozilla/layout/style/nsCSSPseudoElements.h b/mozilla/layout/style/nsCSSPseudoElements.h
index d2754b753eb..582e3071e0f 100644
--- a/mozilla/layout/style/nsCSSPseudoElements.h
+++ b/mozilla/layout/style/nsCSSPseudoElements.h
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* atom list for CSS pseudo-elements */
+
 #ifndef nsCSSPseudoElements_h___
 #define nsCSSPseudoElements_h___
 
diff --git a/mozilla/layout/style/nsCSSRule.cpp b/mozilla/layout/style/nsCSSRule.cpp
index 4e5eaadb807..96fda85ce68 100644
--- a/mozilla/layout/style/nsCSSRule.cpp
+++ b/mozilla/layout/style/nsCSSRule.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* base class for all rule types in a CSS style sheet */
+
 #include "nsCSSRule.h"
 #include "nsCRT.h"
 #include "nsICSSStyleSheet.h"
diff --git a/mozilla/layout/style/nsCSSRule.h b/mozilla/layout/style/nsCSSRule.h
index 2e74f55d854..f77cab9e6f0 100644
--- a/mozilla/layout/style/nsCSSRule.h
+++ b/mozilla/layout/style/nsCSSRule.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* base class for all rule types in a CSS style sheet */
+
 #ifndef nsCSSRule_h___
 #define nsCSSRule_h___
 
diff --git a/mozilla/layout/style/nsCSSRuleProcessor.h b/mozilla/layout/style/nsCSSRuleProcessor.h
index c8cddf61e75..b423dcdb465 100644
--- a/mozilla/layout/style/nsCSSRuleProcessor.h
+++ b/mozilla/layout/style/nsCSSRuleProcessor.h
@@ -37,6 +37,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * style rule processor for CSS style sheets, responsible for selector
+ * matching and cascading
+ */
+
 #ifndef nsCSSRuleProcessor_h_
 #define nsCSSRuleProcessor_h_
 
diff --git a/mozilla/layout/style/nsCSSRules.cpp b/mozilla/layout/style/nsCSSRules.cpp
index 77b4bbfaccb..e5b6e4f5979 100644
--- a/mozilla/layout/style/nsCSSRules.cpp
+++ b/mozilla/layout/style/nsCSSRules.cpp
@@ -35,6 +35,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rules in a CSS stylesheet other than style rules (e.g., @import rules) */
+
 #include "nsCSSRules.h"
 #include "nsICSSImportRule.h"
 #include "nsICSSNameSpaceRule.h"
diff --git a/mozilla/layout/style/nsCSSRules.h b/mozilla/layout/style/nsCSSRules.h
index 85d33de26b9..73131883b44 100644
--- a/mozilla/layout/style/nsCSSRules.h
+++ b/mozilla/layout/style/nsCSSRules.h
@@ -37,6 +37,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* rules in a CSS stylesheet other than style rules (e.g., @import rules) */
+
 #ifndef nsCSSRules_h_
 #define nsCSSRules_h_
 
diff --git a/mozilla/layout/style/nsCSSScanner.cpp b/mozilla/layout/style/nsCSSScanner.cpp
index 4a62c7a9bf5..7fc56cb0d03 100644
--- a/mozilla/layout/style/nsCSSScanner.cpp
+++ b/mozilla/layout/style/nsCSSScanner.cpp
@@ -36,6 +36,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* tokenization of CSS style sheets */
+
 #include "nsCSSScanner.h"
 #include "nsIFactory.h"
 #include "nsIInputStream.h"
diff --git a/mozilla/layout/style/nsCSSScanner.h b/mozilla/layout/style/nsCSSScanner.h
index c7a9031a80f..1efe2b79a41 100644
--- a/mozilla/layout/style/nsCSSScanner.h
+++ b/mozilla/layout/style/nsCSSScanner.h
@@ -36,6 +36,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* tokenization of CSS style sheets */
+
 #ifndef nsCSSScanner_h___
 #define nsCSSScanner_h___
 
diff --git a/mozilla/layout/style/nsCSSStruct.cpp b/mozilla/layout/style/nsCSSStruct.cpp
index c2539547ae7..d3ea22da21a 100644
--- a/mozilla/layout/style/nsCSSStruct.cpp
+++ b/mozilla/layout/style/nsCSSStruct.cpp
@@ -36,6 +36,13 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * temporary (expanded) representation of the property-value pairs
+ * within a CSS declaration using during parsing and mutation, and
+ * representation of complex values for CSS properties
+ */
+
 #include "nscore.h"
 #include "nsCSSStruct.h"
 #include "nsString.h"
diff --git a/mozilla/layout/style/nsCSSStruct.h b/mozilla/layout/style/nsCSSStruct.h
index cecdde91327..68ee972c339 100644
--- a/mozilla/layout/style/nsCSSStruct.h
+++ b/mozilla/layout/style/nsCSSStruct.h
@@ -35,6 +35,13 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * temporary (expanded) representation of the property-value pairs
+ * within a CSS declaration using during parsing and mutation, and
+ * representation of complex values for CSS properties
+ */
+
 #ifndef nsCSSStruct_h___
 #define nsCSSStruct_h___
 
diff --git a/mozilla/layout/style/nsCSSStyleRule.cpp b/mozilla/layout/style/nsCSSStyleRule.cpp
index f1131dc582a..b6fab624124 100644
--- a/mozilla/layout/style/nsCSSStyleRule.cpp
+++ b/mozilla/layout/style/nsCSSStyleRule.cpp
@@ -36,6 +36,13 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * representation of CSS style rules (selectors+declaration), CSS
+ * selectors, and DOM objects for style rules, selectors, and
+ * declarations
+ */
+
 #include "nsCOMPtr.h"
 #include "nsCSSRule.h"
 #include "nsICSSStyleRule.h"
diff --git a/mozilla/layout/style/nsCSSStyleSheet.cpp b/mozilla/layout/style/nsCSSStyleSheet.cpp
index a9425d1e6e6..73bd93deb22 100644
--- a/mozilla/layout/style/nsCSSStyleSheet.cpp
+++ b/mozilla/layout/style/nsCSSStyleSheet.cpp
@@ -38,6 +38,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* implementation of nsCSSStyleSheet and nsCSSRuleProcessor */
+
 #include "nsCSSStyleSheet.h"
 
 #define PL_ARENA_CONST_ALIGN_MASK 7
diff --git a/mozilla/layout/style/nsCSSStyleSheet.h b/mozilla/layout/style/nsCSSStyleSheet.h
index 78826ebf7de..6cfcc9eaa06 100644
--- a/mozilla/layout/style/nsCSSStyleSheet.h
+++ b/mozilla/layout/style/nsCSSStyleSheet.h
@@ -39,6 +39,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* representation of a CSS style sheet */
+
 #ifndef nsCSSStyleSheet_h_
 #define nsCSSStyleSheet_h_
 
diff --git a/mozilla/layout/style/nsCSSValue.cpp b/mozilla/layout/style/nsCSSValue.cpp
index c5cd5a5dba2..c1a60b8e46c 100644
--- a/mozilla/layout/style/nsCSSValue.cpp
+++ b/mozilla/layout/style/nsCSSValue.cpp
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* representation of simple property values within CSS declarations */
+
 #include "nsCSSValue.h"
 #include "nsString.h"
 #include "nsCSSProps.h"
diff --git a/mozilla/layout/style/nsCSSValue.h b/mozilla/layout/style/nsCSSValue.h
index 930991d9357..98a1094e338 100644
--- a/mozilla/layout/style/nsCSSValue.h
+++ b/mozilla/layout/style/nsCSSValue.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* representation of simple property values within CSS declarations */
+
 #ifndef nsCSSValue_h___
 #define nsCSSValue_h___
 
diff --git a/mozilla/layout/style/nsComputedDOMStyle.cpp b/mozilla/layout/style/nsComputedDOMStyle.cpp
index 0952bd1a7bb..df99fef7c86 100644
--- a/mozilla/layout/style/nsComputedDOMStyle.cpp
+++ b/mozilla/layout/style/nsComputedDOMStyle.cpp
@@ -40,6 +40,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* DOM object returned from element.getComputedStyle() */
+
 #include "nsComputedDOMStyle.h"
 
 #include "nsDOMError.h"
diff --git a/mozilla/layout/style/nsComputedDOMStyle.h b/mozilla/layout/style/nsComputedDOMStyle.h
index 449ca5b06d8..d04d774fda9 100644
--- a/mozilla/layout/style/nsComputedDOMStyle.h
+++ b/mozilla/layout/style/nsComputedDOMStyle.h
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* DOM object returned from element.getComputedStyle() */
+
 #ifndef nsComputedDOMStyle_h__
 #define nsComputedDOMStyle_h__
 
diff --git a/mozilla/layout/style/nsDOMCSSAttrDeclaration.cpp b/mozilla/layout/style/nsDOMCSSAttrDeclaration.cpp
index 2601728e77e..27d086c5a56 100644
--- a/mozilla/layout/style/nsDOMCSSAttrDeclaration.cpp
+++ b/mozilla/layout/style/nsDOMCSSAttrDeclaration.cpp
@@ -35,6 +35,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* DOM object for element.style */
+
 #include "nsDOMCSSAttrDeclaration.h"
 #include "nsCSSDeclaration.h"
 #include "nsIDocument.h"
diff --git a/mozilla/layout/style/nsDOMCSSAttrDeclaration.h b/mozilla/layout/style/nsDOMCSSAttrDeclaration.h
index 7be4cc9a8ce..8c666253dab 100644
--- a/mozilla/layout/style/nsDOMCSSAttrDeclaration.h
+++ b/mozilla/layout/style/nsDOMCSSAttrDeclaration.h
@@ -35,6 +35,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* DOM object for element.style */
+
 #ifndef nsDOMCSSAttributeDeclaration_h___
 #define nsDOMCSSAttributeDeclaration_h___
 
diff --git a/mozilla/layout/style/nsDOMCSSDeclaration.cpp b/mozilla/layout/style/nsDOMCSSDeclaration.cpp
index 3e483c9a065..e5f80fb7c8a 100644
--- a/mozilla/layout/style/nsDOMCSSDeclaration.cpp
+++ b/mozilla/layout/style/nsDOMCSSDeclaration.cpp
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* base class for DOM objects for element.style and cssStyleRule.style */
+
 #include "nsDOMCSSDeclaration.h"
 #include "nsIDOMCSSRule.h"
 #include "nsICSSParser.h"
diff --git a/mozilla/layout/style/nsDOMCSSDeclaration.h b/mozilla/layout/style/nsDOMCSSDeclaration.h
index 0081995e796..269221d3bfa 100644
--- a/mozilla/layout/style/nsDOMCSSDeclaration.h
+++ b/mozilla/layout/style/nsDOMCSSDeclaration.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* base class for DOM objects for element.style and cssStyleRule.style */
+
 #ifndef nsDOMCSSDeclaration_h___
 #define nsDOMCSSDeclaration_h___
 
diff --git a/mozilla/layout/style/nsDOMCSSRGBColor.cpp b/mozilla/layout/style/nsDOMCSSRGBColor.cpp
index 51662118bae..3ba6283cd29 100644
--- a/mozilla/layout/style/nsDOMCSSRGBColor.cpp
+++ b/mozilla/layout/style/nsDOMCSSRGBColor.cpp
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* DOM object representing color values in DOM computed style */
+
 #include "nsISupports.h"
 #include "nsCOMPtr.h"
 #include "nsIDOMCSSPrimitiveValue.h"
diff --git a/mozilla/layout/style/nsDOMCSSRGBColor.h b/mozilla/layout/style/nsDOMCSSRGBColor.h
index 98066e96ac8..cf82c2bcd1e 100644
--- a/mozilla/layout/style/nsDOMCSSRGBColor.h
+++ b/mozilla/layout/style/nsDOMCSSRGBColor.h
@@ -36,6 +36,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* DOM object representing color values in DOM computed style */
+
 #ifndef nsDOMCSSRGBColor_h__
 #define nsDOMCSSRGBColor_h__
 
diff --git a/mozilla/layout/style/nsDOMCSSRect.cpp b/mozilla/layout/style/nsDOMCSSRect.cpp
index 8aec0c2d408..c1f36c2b0c3 100644
--- a/mozilla/layout/style/nsDOMCSSRect.cpp
+++ b/mozilla/layout/style/nsDOMCSSRect.cpp
@@ -35,6 +35,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* DOM object representing rectangle values in DOM computed style */
+
 #include "nsISupports.h"
 #include "nsCOMPtr.h"
 #include "nsIDOMCSSPrimitiveValue.h"
diff --git a/mozilla/layout/style/nsDOMCSSRect.h b/mozilla/layout/style/nsDOMCSSRect.h
index b03452341a2..90e66b3a03e 100644
--- a/mozilla/layout/style/nsDOMCSSRect.h
+++ b/mozilla/layout/style/nsDOMCSSRect.h
@@ -35,8 +35,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
-#ifndef nsCSSRect_h___
-#define nsCSSRect_h___
+/* DOM object representing rectangle values in DOM computed style */
+
+#ifndef nsDOMCSSRect_h_
+#define nsDOMCSSRect_h_
 
 #include "nsISupports.h"
 #include "nsIDOMRect.h"
@@ -61,4 +63,4 @@ private:
   nsCOMPtr<nsIDOMCSSPrimitiveValue> mLeft;
 };
 
-#endif /* nsCSSRect_h___ */
+#endif /* nsDOMCSSRect_h_ */
diff --git a/mozilla/layout/style/nsDOMCSSValueList.cpp b/mozilla/layout/style/nsDOMCSSValueList.cpp
index 3f8b4591099..cec738357d6 100644
--- a/mozilla/layout/style/nsDOMCSSValueList.cpp
+++ b/mozilla/layout/style/nsDOMCSSValueList.cpp
@@ -35,6 +35,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* DOM object representing lists of values in DOM computed style */
+
 #include "nsDOMCSSValueList.h"
 #include "nsCOMPtr.h"
 #include "nsDOMError.h"
diff --git a/mozilla/layout/style/nsDOMCSSValueList.h b/mozilla/layout/style/nsDOMCSSValueList.h
index 1e7315b5eee..a1935768ec3 100644
--- a/mozilla/layout/style/nsDOMCSSValueList.h
+++ b/mozilla/layout/style/nsDOMCSSValueList.h
@@ -35,6 +35,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* DOM object representing lists of values in DOM computed style */
+
 #ifndef nsDOMCSSValueList_h___
 #define nsDOMCSSValueList_h___
 
diff --git a/mozilla/layout/style/nsHTMLCSSStyleSheet.cpp b/mozilla/layout/style/nsHTMLCSSStyleSheet.cpp
index 575ec95f185..0319cee97ff 100644
--- a/mozilla/layout/style/nsHTMLCSSStyleSheet.cpp
+++ b/mozilla/layout/style/nsHTMLCSSStyleSheet.cpp
@@ -36,6 +36,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * style sheet and style rule processor representing style attributes
+ * and some additional overrides
+ */
+
 #include "nsIHTMLCSSStyleSheet.h"
 #include "nsCRT.h"
 #include "nsIAtom.h"
diff --git a/mozilla/layout/style/nsHTMLStyleSheet.cpp b/mozilla/layout/style/nsHTMLStyleSheet.cpp
index 17b21b9d24a..3b51e07e578 100644
--- a/mozilla/layout/style/nsHTMLStyleSheet.cpp
+++ b/mozilla/layout/style/nsHTMLStyleSheet.cpp
@@ -44,6 +44,11 @@
  * 04/20/2000       IBM Corp.      OS/2 VisualAge build.
  */
 
+/*
+ * style sheet and style rule processor representing data from presentational
+ * HTML attributes
+ */
+
 #include "nsHTMLStyleSheet.h"
 #include "nsINameSpaceManager.h"
 #include "nsIAtom.h"
diff --git a/mozilla/layout/style/nsHTMLStyleSheet.h b/mozilla/layout/style/nsHTMLStyleSheet.h
index a80fa39290c..ac1e6b2dcb8 100644
--- a/mozilla/layout/style/nsHTMLStyleSheet.h
+++ b/mozilla/layout/style/nsHTMLStyleSheet.h
@@ -36,6 +36,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * style sheet and style rule processor representing data from presentational
+ * HTML attributes
+ */
+
 #ifndef nsHTMLStyleSheet_h_
 #define nsHTMLStyleSheet_h_
 
diff --git a/mozilla/layout/style/nsICSSDeclaration.h b/mozilla/layout/style/nsICSSDeclaration.h
index eb76950a327..e000be39a1a 100644
--- a/mozilla/layout/style/nsICSSDeclaration.h
+++ b/mozilla/layout/style/nsICSSDeclaration.h
@@ -35,6 +35,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * faster version of nsIDOMCSSStyleDeclaration using enums instead of
+ * strings, for internal use
+ */
+
 #ifndef nsICSSDeclaration_h__
 #define nsICSSDeclaration_h__
 
diff --git a/mozilla/layout/style/nsICSSGroupRule.h b/mozilla/layout/style/nsICSSGroupRule.h
index 42e80f8c15f..69a44abb4e5 100644
--- a/mozilla/layout/style/nsICSSGroupRule.h
+++ b/mozilla/layout/style/nsICSSGroupRule.h
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * internal interface representing CSS style rules that contain other
+ * rules, such as @media rules
+ */
+
 #ifndef nsICSSGroupRule_h___
 #define nsICSSGroupRule_h___
 
diff --git a/mozilla/layout/style/nsICSSImportRule.h b/mozilla/layout/style/nsICSSImportRule.h
index 413438064c9..75be298b437 100644
--- a/mozilla/layout/style/nsICSSImportRule.h
+++ b/mozilla/layout/style/nsICSSImportRule.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* internal interface for CSS @import rules */
+
 #ifndef nsICSSImportRule_h___
 #define nsICSSImportRule_h___
 
diff --git a/mozilla/layout/style/nsICSSLoader.h b/mozilla/layout/style/nsICSSLoader.h
index f1611a2e8e7..1587d627e54 100644
--- a/mozilla/layout/style/nsICSSLoader.h
+++ b/mozilla/layout/style/nsICSSLoader.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* loading of CSS style sheets using the network APIs */
+
 #ifndef nsICSSLoader_h___
 #define nsICSSLoader_h___
 
diff --git a/mozilla/layout/style/nsICSSLoaderObserver.h b/mozilla/layout/style/nsICSSLoaderObserver.h
index 5a8cdbff4d0..61c1d49756f 100644
--- a/mozilla/layout/style/nsICSSLoaderObserver.h
+++ b/mozilla/layout/style/nsICSSLoaderObserver.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* internal interface for observing CSS style sheet loads */
+
 #ifndef nsICSSLoaderObserver_h___
 #define nsICSSLoaderObserver_h___
 
diff --git a/mozilla/layout/style/nsICSSNameSpaceRule.h b/mozilla/layout/style/nsICSSNameSpaceRule.h
index 73adb9a0649..cd6b0d4dc3f 100644
--- a/mozilla/layout/style/nsICSSNameSpaceRule.h
+++ b/mozilla/layout/style/nsICSSNameSpaceRule.h
@@ -37,6 +37,8 @@
 #ifndef nsICSSNameSpaceRule_h___
 #define nsICSSNameSpaceRule_h___
 
+/* internal interface for CSS @namespace rules */
+
 #include "nsICSSRule.h"
 //#include "nsString.h"
 
diff --git a/mozilla/layout/style/nsICSSOMFactory.h b/mozilla/layout/style/nsICSSOMFactory.h
index 0631950aaf9..541a9e0d174 100644
--- a/mozilla/layout/style/nsICSSOMFactory.h
+++ b/mozilla/layout/style/nsICSSOMFactory.h
@@ -37,6 +37,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* an XPCOM service for cross-module creation of DOM .style objects */
+
 #ifndef nsICSSOMFactory_h___
 #define nsICSSOMFactory_h___
 
diff --git a/mozilla/layout/style/nsICSSParser.h b/mozilla/layout/style/nsICSSParser.h
index 6d1339cf53d..cc7a83b5684 100644
--- a/mozilla/layout/style/nsICSSParser.h
+++ b/mozilla/layout/style/nsICSSParser.h
@@ -34,8 +34,11 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
-#ifndef nsCSS1Parser_h___
-#define nsCSS1Parser_h___
+
+/* parsing of CSS stylesheets, based on a token stream from the CSS scanner */
+
+#ifndef nsICSSParser_h___
+#define nsICSSParser_h___
 
 #include "nsISupports.h"
 #include "nsAString.h"
@@ -150,4 +153,4 @@ NS_DEFINE_STATIC_IID_ACCESSOR(nsICSSParser, NS_ICSS_PARSER_IID)
 nsresult
 NS_NewCSSParser(nsICSSParser** aInstancePtrResult);
 
-#endif /* nsCSS1Parser_h___ */
+#endif /* nsICSSParser_h___ */
diff --git a/mozilla/layout/style/nsICSSPseudoComparator.h b/mozilla/layout/style/nsICSSPseudoComparator.h
index e0f11ecf730..49d0e2f4741 100644
--- a/mozilla/layout/style/nsICSSPseudoComparator.h
+++ b/mozilla/layout/style/nsICSSPseudoComparator.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* internal interface for implementing complex pseudo-classes */
+
 #ifndef nsICSSPseudoComparator_h___
 #define nsICSSPseudoComparator_h___
 
diff --git a/mozilla/layout/style/nsICSSRule.h b/mozilla/layout/style/nsICSSRule.h
index dc838feeb31..ad4b84bc9bf 100644
--- a/mozilla/layout/style/nsICSSRule.h
+++ b/mozilla/layout/style/nsICSSRule.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* internal interface for all rule types in a CSS style sheet */
+
 #ifndef nsICSSRule_h___
 #define nsICSSRule_h___
 
@@ -48,7 +51,7 @@ class nsAString;
 #define NS_ICSS_RULE_IID     \
 {0xb9791e20, 0x1a04, 0x11d3, {0x80, 0x5a, 0x00, 0x60, 0x08, 0x15, 0x9b, 0x5a}}
 
-
+// inheriting from nsIStyleRule is only for style rules, not other rule types
 class nsICSSRule : public nsIStyleRule {
 public:
   NS_DECLARE_STATIC_IID_ACCESSOR(NS_ICSS_RULE_IID)
diff --git a/mozilla/layout/style/nsICSSStyleRule.h b/mozilla/layout/style/nsICSSStyleRule.h
index b51b2dea3e4..3202be64832 100644
--- a/mozilla/layout/style/nsICSSStyleRule.h
+++ b/mozilla/layout/style/nsICSSStyleRule.h
@@ -35,6 +35,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * representation of CSS style rules (selectors+declaration) and CSS
+ * selectors
+ */
+
 #ifndef nsICSSStyleRule_h___
 #define nsICSSStyleRule_h___
 
diff --git a/mozilla/layout/style/nsICSSStyleRuleDOMWrapper.h b/mozilla/layout/style/nsICSSStyleRuleDOMWrapper.h
index 7307b3ed264..d15db5f9009 100644
--- a/mozilla/layout/style/nsICSSStyleRuleDOMWrapper.h
+++ b/mozilla/layout/style/nsICSSStyleRuleDOMWrapper.h
@@ -35,6 +35,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * interface to provide DOM inspector with access to internal interfaces
+ * via DOM interface
+ */
+
 #ifndef nsICSSStyleRuleDOMWrapper_h_
 #define nsICSSStyleRuleDOMWrapper_h_
 
diff --git a/mozilla/layout/style/nsICSSStyleSheet.h b/mozilla/layout/style/nsICSSStyleSheet.h
index 9f04a488594..0c68cbbf143 100644
--- a/mozilla/layout/style/nsICSSStyleSheet.h
+++ b/mozilla/layout/style/nsICSSStyleSheet.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* representation of a CSS style sheet */
+
 #ifndef nsICSSStyleSheet_h___
 #define nsICSSStyleSheet_h___
 
diff --git a/mozilla/layout/style/nsIComputedDOMStyle.h b/mozilla/layout/style/nsIComputedDOMStyle.h
index ff5715febfc..c7b000e07f9 100644
--- a/mozilla/layout/style/nsIComputedDOMStyle.h
+++ b/mozilla/layout/style/nsIComputedDOMStyle.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* DOM object returned from element.getComputedStyle() */
+
 #ifndef nsIComputedDOMStyle_h___
 #define nsIComputedDOMStyle_h___
 
diff --git a/mozilla/layout/style/nsIHTMLCSSStyleSheet.h b/mozilla/layout/style/nsIHTMLCSSStyleSheet.h
index c17eb511fe8..810166d221d 100644
--- a/mozilla/layout/style/nsIHTMLCSSStyleSheet.h
+++ b/mozilla/layout/style/nsIHTMLCSSStyleSheet.h
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * style sheet and style rule processor representing style attributes
+ * and some additional overrides
+ */
+
 #ifndef nsIHTMLCSSStyleSheet_h___
 #define nsIHTMLCSSStyleSheet_h___
 
diff --git a/mozilla/layout/style/nsIInspectorCSSUtils.h b/mozilla/layout/style/nsIInspectorCSSUtils.h
index 9786f9cdb27..3663ca153e2 100644
--- a/mozilla/layout/style/nsIInspectorCSSUtils.h
+++ b/mozilla/layout/style/nsIInspectorCSSUtils.h
@@ -37,6 +37,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* XPCOM interface to provide some internal information to DOM inspector */
+
 #ifndef nsIInspectorCSSUtils_h___
 #define nsIInspectorCSSUtils_h___
 
diff --git a/mozilla/layout/style/nsIMediaList.h b/mozilla/layout/style/nsIMediaList.h
index 3b16cc87493..6867f352758 100644
--- a/mozilla/layout/style/nsIMediaList.h
+++ b/mozilla/layout/style/nsIMediaList.h
@@ -35,6 +35,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * representation of media lists used when linking to style sheets or by
+ * @media rules
+ */
+
 #ifndef nsIMediaList_h_
 #define nsIMediaList_h_
 
diff --git a/mozilla/layout/style/nsIStyleRule.h b/mozilla/layout/style/nsIStyleRule.h
index f826da1a784..b0e3b1129a7 100644
--- a/mozilla/layout/style/nsIStyleRule.h
+++ b/mozilla/layout/style/nsIStyleRule.h
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * internal abstract interface for objects providing immutable style
+ * information
+ */
+
 #ifndef nsIStyleRule_h___
 #define nsIStyleRule_h___
 
diff --git a/mozilla/layout/style/nsIStyleRuleProcessor.h b/mozilla/layout/style/nsIStyleRuleProcessor.h
index f4a023b95b0..a67990b6d8b 100644
--- a/mozilla/layout/style/nsIStyleRuleProcessor.h
+++ b/mozilla/layout/style/nsIStyleRuleProcessor.h
@@ -34,6 +34,13 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * internal abstract interface for containers (roughly origins within
+ * the CSS cascade) that provide style rules matching an element or
+ * pseudo-element
+ */
+
 #ifndef nsIStyleRuleProcessor_h___
 #define nsIStyleRuleProcessor_h___
 
diff --git a/mozilla/layout/style/nsIStyleRuleSupplier.h b/mozilla/layout/style/nsIStyleRuleSupplier.h
index 0c40584934b..0e8b3fe3232 100644
--- a/mozilla/layout/style/nsIStyleRuleSupplier.h
+++ b/mozilla/layout/style/nsIStyleRuleSupplier.h
@@ -1,3 +1,9 @@
+
+/*
+ * internal interface that allows XBL code to provide additional style
+ * rules matching an element
+ */
+
 #ifndef _nsIStyleRuleSupplier_h
 #define _nsIStyleRuleSupplier_h
 
diff --git a/mozilla/layout/style/nsIStyleSheet.h b/mozilla/layout/style/nsIStyleSheet.h
index 4f6d5326a3e..2412c8e82bc 100644
--- a/mozilla/layout/style/nsIStyleSheet.h
+++ b/mozilla/layout/style/nsIStyleSheet.h
@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * interface representing a collection of style data attached to a
+ * document, which may be or be combined into a style rule processor
+ */
+
 #ifndef nsIStyleSheet_h___
 #define nsIStyleSheet_h___
 
diff --git a/mozilla/layout/style/nsInspectorCSSUtils.cpp b/mozilla/layout/style/nsInspectorCSSUtils.cpp
index 20433fb8648..f35aa52c2a6 100644
--- a/mozilla/layout/style/nsInspectorCSSUtils.cpp
+++ b/mozilla/layout/style/nsInspectorCSSUtils.cpp
@@ -37,6 +37,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* XPCOM interface to provide some internal information to DOM inspector */
+
 #include "nsInspectorCSSUtils.h"
 #include "nsIStyleRule.h"
 #include "nsRuleNode.h"
diff --git a/mozilla/layout/style/nsInspectorCSSUtils.h b/mozilla/layout/style/nsInspectorCSSUtils.h
index dbcda9a92ec..813132f2efd 100644
--- a/mozilla/layout/style/nsInspectorCSSUtils.h
+++ b/mozilla/layout/style/nsInspectorCSSUtils.h
@@ -37,6 +37,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* XPCOM interface to provide some internal information to DOM inspector */
+
 #ifndef nsInspectorCSSUtils_h___
 #define nsInspectorCSSUtils_h___
 
diff --git a/mozilla/layout/style/nsROCSSPrimitiveValue.cpp b/mozilla/layout/style/nsROCSSPrimitiveValue.cpp
index b04ae498a00..6efb43ed2e4 100644
--- a/mozilla/layout/style/nsROCSSPrimitiveValue.cpp
+++ b/mozilla/layout/style/nsROCSSPrimitiveValue.cpp
@@ -35,6 +35,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* DOM object representing values in DOM computed style */
+
 #include "nsROCSSPrimitiveValue.h"
 
 #include "nsCOMPtr.h"
diff --git a/mozilla/layout/style/nsROCSSPrimitiveValue.h b/mozilla/layout/style/nsROCSSPrimitiveValue.h
index 9b36fc4b44a..15a28b5d617 100644
--- a/mozilla/layout/style/nsROCSSPrimitiveValue.h
+++ b/mozilla/layout/style/nsROCSSPrimitiveValue.h
@@ -35,6 +35,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* DOM object representing values in DOM computed style */
+
 #ifndef nsROCSSPrimitiveValue_h___
 #define nsROCSSPrimitiveValue_h___
 
diff --git a/mozilla/layout/style/nsRuleData.h b/mozilla/layout/style/nsRuleData.h
index 38060f44c20..d668814b898 100644
--- a/mozilla/layout/style/nsRuleData.h
+++ b/mozilla/layout/style/nsRuleData.h
@@ -36,6 +36,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * temporary (expanded) representation of property-value pairs used to
+ * hold data from matched rules during style data computation 
+ */
+
 #ifndef nsRuleData_h_
 #define nsRuleData_h_
 
diff --git a/mozilla/layout/style/nsRuleNode.cpp b/mozilla/layout/style/nsRuleNode.cpp
index c77ba74a259..4b8856e2b49 100644
--- a/mozilla/layout/style/nsRuleNode.cpp
+++ b/mozilla/layout/style/nsRuleNode.cpp
@@ -39,6 +39,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * a node in the lexicographic tree of rules that match an element,
+ * responsible for converting the rules' information into computed style
+ */
+
 #include "nsRuleNode.h"
 #include "nscore.h"
 #include "nsIServiceManager.h"
diff --git a/mozilla/layout/style/nsRuleNode.h b/mozilla/layout/style/nsRuleNode.h
index 99783ddf8dd..f4a10c3efd2 100644
--- a/mozilla/layout/style/nsRuleNode.h
+++ b/mozilla/layout/style/nsRuleNode.h
@@ -36,6 +36,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * a node in the lexicographic tree of rules that match an element,
+ * responsible for converting the rules' information into computed style
+ */
+
 #ifndef nsRuleNode_h___
 #define nsRuleNode_h___
 
diff --git a/mozilla/layout/style/nsRuleWalker.h b/mozilla/layout/style/nsRuleWalker.h
index a558599bb98..587c3b3bfcc 100644
--- a/mozilla/layout/style/nsRuleWalker.h
+++ b/mozilla/layout/style/nsRuleWalker.h
@@ -36,6 +36,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * a class that walks the lexicographic tree of rule nodes as style
+ * rules are matched
+ */
+
 #include "nsRuleNode.h"
 
 class nsRuleWalker {
diff --git a/mozilla/layout/style/nsStyleContext.cpp b/mozilla/layout/style/nsStyleContext.cpp
index 04a9e9e91cd..095e52b9457 100644
--- a/mozilla/layout/style/nsStyleContext.cpp
+++ b/mozilla/layout/style/nsStyleContext.cpp
@@ -37,6 +37,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
  
+/* the interface (to internal code) for retrieving computed style data */
+
 #include "nsStyleConsts.h"
 #include "nsString.h"
 #include "nsPresContext.h"
diff --git a/mozilla/layout/style/nsStyleContext.h b/mozilla/layout/style/nsStyleContext.h
index a44f0b4fad4..50070ceb364 100644
--- a/mozilla/layout/style/nsStyleContext.h
+++ b/mozilla/layout/style/nsStyleContext.h
@@ -37,6 +37,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* the interface (to internal code) for retrieving computed style data */
+
 #ifndef _nsStyleContext_h_
 #define _nsStyleContext_h_
 
diff --git a/mozilla/layout/style/nsStyleCoord.cpp b/mozilla/layout/style/nsStyleCoord.cpp
index abc8b13b7b5..b95de3215a6 100644
--- a/mozilla/layout/style/nsStyleCoord.cpp
+++ b/mozilla/layout/style/nsStyleCoord.cpp
@@ -35,6 +35,8 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/* representation of length values in computed style data */
+
 #include "nsStyleCoord.h"
 #include "nsString.h"
 #include "nsCRT.h"
diff --git a/mozilla/layout/style/nsStyleCoord.h b/mozilla/layout/style/nsStyleCoord.h
index b52c851bfe9..6393cdb89a1 100644
--- a/mozilla/layout/style/nsStyleCoord.h
+++ b/mozilla/layout/style/nsStyleCoord.h
@@ -34,6 +34,9 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/* representation of length values in computed style data */
+
 #ifndef nsStyleCoord_h___
 #define nsStyleCoord_h___
 
diff --git a/mozilla/layout/style/nsStyleSet.cpp b/mozilla/layout/style/nsStyleSet.cpp
index d6148174ab5..75922c640b5 100644
--- a/mozilla/layout/style/nsStyleSet.cpp
+++ b/mozilla/layout/style/nsStyleSet.cpp
@@ -36,6 +36,13 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * the container for the style sheets that apply to a presentation, and
+ * the internal API that the style system exposes for creating (and
+ * potentially re-creating) style contexts
+ */
+
 #include "nsStyleSet.h"
 #include "nsNetUtil.h"
 #include "nsICSSStyleSheet.h"
diff --git a/mozilla/layout/style/nsStyleSet.h b/mozilla/layout/style/nsStyleSet.h
index 908f6c2d1cc..0dd2151a972 100644
--- a/mozilla/layout/style/nsStyleSet.h
+++ b/mozilla/layout/style/nsStyleSet.h
@@ -37,6 +37,12 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * the container for the style sheets that apply to a presentation, and
+ * the internal API that the style system exposes for creating (and
+ * potentially re-creating) style contexts
+ */
+
 #ifndef nsStyleSet_h_
 #define nsStyleSet_h_
 
diff --git a/mozilla/layout/style/nsStyleStruct.cpp b/mozilla/layout/style/nsStyleStruct.cpp
index d316fe945e8..4d886e99829 100644
--- a/mozilla/layout/style/nsStyleStruct.cpp
+++ b/mozilla/layout/style/nsStyleStruct.cpp
@@ -37,6 +37,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * structs that contain the data provided by nsStyleContext, the
+ * internal API for computed style data for an element
+ */
+
 #include "nsStyleStruct.h"
 #include "nsStyleConsts.h"
 #include "nsString.h"
diff --git a/mozilla/layout/style/nsStyleStruct.h b/mozilla/layout/style/nsStyleStruct.h
index 2784578fe29..9bd191c891e 100644
--- a/mozilla/layout/style/nsStyleStruct.h
+++ b/mozilla/layout/style/nsStyleStruct.h
@@ -35,6 +35,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * structs that contain the data provided by nsStyleContext, the
+ * internal API for computed style data for an element
+ */
+
 #ifndef nsStyleStruct_h___
 #define nsStyleStruct_h___
 
diff --git a/mozilla/layout/style/nsStyleStructList.h b/mozilla/layout/style/nsStyleStructList.h
index 90758bb4954..a95f35275b5 100644
--- a/mozilla/layout/style/nsStyleStructList.h
+++ b/mozilla/layout/style/nsStyleStructList.h
@@ -37,6 +37,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * list of structs that contain the data provided by nsStyleContext, the
+ * internal API for computed style data for an element
+ */
+
 /*
  * This file is intended to be used by different parts of the code, with
  * the STYLE_STRUCT macro (or the STYLE_STRUCT_INHERITED and