Add comments describing some more files.

content/base/src/nsGenericDOMNodeList.cpp

@@ -35,6 +35,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * A base class for simple DOM NodeLists which implements nsISupports
+ * and expects subclasess to implement GetLength() and Item()
+ */
+
 #include "nsGenericDOMNodeList.h"
 #include "nsGenericElement.h"
 

content/base/src/nsGenericDOMNodeList.h

@@ -35,20 +35,17 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * A base class for simple DOM NodeLists which implements nsISupports
+ * and expects subclasess to implement GetLength() and Item()
+ */
+
 #ifndef nsGenericDOMNodeList_h__
 #define nsGenericDOMNodeList_h__
 
 #include "nsISupports.h"
 #include "nsIDOMNodeList.h"
 
-/**
- * This is a base class for a generic DOM Node List. The base class
- * provides implementations for nsISupports, it is up to the subclass
- * to implement the core node list methods:
- *
- *   GetLength
- *   Item
- * */
 class nsGenericDOMNodeList : public nsIDOMNodeList 
 {
 public:

content/base/src/nsGenericElement.cpp

@@ -34,6 +34,13 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * Base class for all element classes; this provides an implementation
+ * of DOM Core's Element, implements nsIContent, provides utility
+ * methods for subclasses, and so forth.
+ */
+
 #include "nsGenericElement.h"
 
 #include "nsDOMAttribute.h"

content/base/src/nsGenericElement.h

@@ -34,6 +34,13 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * Base class for all element classes; this provides an implementation
+ * of DOM Core's Element, implements nsIContent, provides utility
+ * methods for subclasses, and so forth.
+ */
+
 #ifndef nsGenericElement_h___
 #define nsGenericElement_h___
 

content/base/src/nsGkAtomList.h

@@ -35,12 +35,13 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
-/******
+/*
+  This file contains the list of all atoms used by gklayout;
+  see nsGkAtoms for access to the atoms.
+*/
 
-  This file contains the list of all atoms used by gklayout
-  See nsGkAtoms.h for access to the atoms
-
-  It is designed to be used as inline input to nsGkAtoms.cpp and nsGkAtoms.h
+/*
+  This file is designed to be used as inline input to nsGkAtoms.cpp and nsGkAtoms.h
   *only* through the magic of C preprocessing.
 
   All entires must be enclosed in the macro GK_ATOM which will have cruel
@@ -48,8 +49,7 @@
 
   The first argument to GK_ATOM is the C++ name of the atom
   The second argument it GK_ATOM is the string value of the atom
-
- ******/
+*/
 
 // OUTPUT_CLASS=nsGkAtoms
 // MACRO_NAME=GK_ATOM

content/base/src/nsGkAtoms.cpp

@@ -34,6 +34,13 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * This class wraps up the creation (and destruction) of the standard
+ * set of atoms used by gklayout; the atoms are created when gklayout
+ * is loaded and they are destroyed when gklayout is unloaded.
+ */
+
 #include "nsGkAtoms.h"
 #include "nsStaticAtom.h"
 

content/base/src/nsGkAtoms.h

@@ -34,17 +34,18 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * This class wraps up the creation (and destruction) of the standard
+ * set of atoms used by gklayout; the atoms are created when gklayout
+ * is loaded and they are destroyed when gklayout is unloaded.
+ */
+
 #ifndef nsGkAtoms_h___
 #define nsGkAtoms_h___
 
 #include "nsIAtom.h"
 
-/**
- * This class wraps up the creation (and destruction) of the standard
- * set of atoms used by gklayout. This objects are created when gklayout
- * is loaded and they destroyed when gklayout is unloaded.
- */
-
 class nsGkAtoms {
 public:
 

content/base/src/nsHTMLContentSerializer.cpp

@@ -36,6 +36,12 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * nsIContentSerializer implementation that can be used with an
+ * nsIDocumentEncoder to convert an HTML (not XHTML!) DOM to an HTML
+ * string that could be parsed into more or less the original DOM.
+ */
+
 #include "nsHTMLContentSerializer.h"
 
 #include "nsIDOMElement.h"

content/base/src/nsHTMLContentSerializer.h

@@ -35,6 +35,12 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * nsIContentSerializer implementation that can be used with an
+ * nsIDocumentEncoder to convert an HTML (not XHTML!) DOM to an HTML
+ * string that could be parsed into more or less the original DOM.
+ */
+
 #ifndef nsHTMLContentSerializer_h__
 #define nsHTMLContentSerializer_h__
 

content/base/src/nsImageLoadingContent.cpp

@@ -37,6 +37,12 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * A base class which implements nsIImageLoadingContent and can be
+ * subclassed by various content nodes that want to provide image
+ * loading functionality (eg <img>, <object>, etc).
+ */
+
 #include "nsImageLoadingContent.h"
 #include "nsContentErrors.h"
 #include "nsIContent.h"

content/base/src/nsImageLoadingContent.h

@@ -36,6 +36,12 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * A base class which implements nsIImageLoadingContent and can be
+ * subclassed by various content nodes that want to provide image
+ * loading functionality (eg <img>, <object>, etc).
+ */
+
 #ifndef nsImageLoadingContent_h__
 #define nsImageLoadingContent_h__
 
@@ -50,11 +56,6 @@ class nsIDocument;
 class imgILoader;
 class nsIIOService;
 
-/**
- * This is an implementation of nsIImageLoadingContent.  This class
- * can be subclassed by various content nodes that want to provide
- * image-loading functionality (eg <img>, <object>, etc).
- */
 class nsImageLoadingContent : public nsIImageLoadingContent
 {
   /* METHODS */

content/base/src/nsMappedAttributes.cpp

@@ -36,6 +36,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * A unique per-element set of attributes that is used as an
+ * nsIStyleRule; used to implement presentational attributes.
+ */
+
 #include "nsMappedAttributes.h"
 #include "nsHTMLStyleSheet.h"
 #include "nsRuleWalker.h"

content/base/src/nsMappedAttributes.h

@@ -36,6 +36,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * A unique per-element set of attributes that is used as an
+ * nsIStyleRule; used to implement presentational attributes.
+ */
+
 #ifndef nsMappedAttributes_h___
 #define nsMappedAttributes_h___
 

content/base/src/nsNameSpaceManager.cpp

@@ -34,6 +34,12 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * A class for managing namespace IDs and mapping back and forth
+ * between namespace IDs and namespace URIs.
+ */
+
 #include "nscore.h"
 #include "nsINameSpaceManager.h"
 #include "nsAutoPtr.h"

content/base/src/nsNodeInfo.cpp

@@ -35,6 +35,12 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * Class that represents a prefix/namespace/localName triple; a single
+ * nodeinfo is shared by all elements in a document that have that
+ * prefix, namespace, and localName.
+ */
+
 #include "nscore.h"
 #include "nsNodeInfo.h"
 #include "nsNodeInfoManager.h"

content/base/src/nsNodeInfo.h

@@ -35,6 +35,12 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * Class that represents a prefix/namespace/localName triple; a single
+ * nodeinfo is shared by all elements in a document that have that
+ * prefix, namespace, and localName.
+ */
+
 #ifndef nsNodeInfo_h___
 #define nsNodeInfo_h___
 

content/base/src/nsNodeInfoManager.cpp

@@ -35,6 +35,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * A class for handing out nodeinfos and ensuring sharing of them as needed.
+ */
+
 #include "nsNodeInfoManager.h"
 #include "nsNodeInfo.h"
 #include "nsCOMPtr.h"

content/base/src/nsNodeInfoManager.h

@@ -35,6 +35,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * A class for handing out nodeinfos and ensuring sharing of them as needed.
+ */
+
 #ifndef nsNodeInfoManager_h___
 #define nsNodeInfoManager_h___
 

content/base/src/nsObjectLoadingContent.cpp

@@ -35,6 +35,13 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * A base class which implements nsIObjectLoadingContent and can be
+ * subclassed by various content nodes that want to provide
+ * plugin/document/image loading functionality (eg <embed>, <object>,
+ * <applet>, etc).
+ */
+
 // Interface headers
 #include "imgILoader.h"
 #include "nsIContent.h"

content/base/src/nsObjectLoadingContent.h

@@ -35,6 +35,12 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * A base class which implements nsIObjectLoadingContent and can be
+ * subclassed by various content nodes that want to provide
+ * plugin/document/image loading functionality (eg <embed>, <object>,
+ * <applet>, etc).
+ */
 
 #ifndef NSOBJECTLOADINGCONTENT_H_
 #define NSOBJECTLOADINGCONTENT_H_

content/base/src/nsParserUtils.cpp

@@ -35,6 +35,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * Namespace class for some static parsing-related methods.
+ */
+
 #include "nsParserUtils.h"
 #include "nsIParser.h" // for kQuote et. al.
 #include "jsapi.h"
@@ -165,8 +169,6 @@ nsParserUtils::GetQuotedAttributeValue(const nsString& aSource, nsIAtom *aName,
 }
 
 
-// XXX Stolen from nsHTMLContentSink. Needs to be shared.
-// XXXbe share also with nsRDFParserUtils.cpp and nsHTMLContentSink.cpp
 // Returns PR_TRUE if the language name is a version of JavaScript and
 // PR_FALSE otherwise
 PRBool

content/base/src/nsParserUtils.h

@@ -35,6 +35,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * Namespace class for some static parsing-related methods.
+ */
+
 #ifndef nsParserUtils_h__
 #define nsParserUtils_h__
 

content/base/src/nsPlainTextSerializer.cpp

@@ -37,6 +37,12 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * nsIContentSerializer implementation that can be used with an
+ * nsIDocumentEncoder to convert a DOM into plaintext in a nice way
+ * (eg for copy/paste as plaintext).
+ */
+
 #include "nsPlainTextSerializer.h"
 #include "nsLWBrkCIID.h"
 #include "nsIServiceManager.h"

content/base/src/nsPlainTextSerializer.h

@@ -35,6 +35,12 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * nsIContentSerializer implementation that can be used with an
+ * nsIDocumentEncoder to convert a DOM into plaintext in a nice way
+ * (eg for copy/paste as plaintext).
+ */
+
 #ifndef nsPlainTextSerializer_h__
 #define nsPlainTextSerializer_h__
 

content/base/src/nsPropertyTable.cpp

@@ -45,6 +45,13 @@
  * 04/20/2000       IBM Corp.      OS/2 VisualAge build.
  */
 
+/**
+ * nsPropertyTable allows a set of arbitrary key/value pairs to be stored
+ * for any number of nodes, in a global hashtable rather than on the nodes
+ * themselves.  Nodes can be any type of object; the hashtable keys are
+ * nsIAtom pointers, and the values are void pointers.
+ */
+
 #include "nsPropertyTable.h"
 #include "pldhash.h"
 #include "nsContentErrors.h"

content/base/src/nsRange.cpp

@@ -36,7 +36,7 @@
  * ***** END LICENSE BLOCK ***** */
 
 /*
- * nsRange.cpp: Implementation of the nsIDOMRange object.
+ * Implementation of the DOM Range object.
  */
 
 #include "nscore.h"

content/base/src/nsRange.h

@@ -34,13 +34,14 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
-#ifndef nsRange_h___
-#define nsRange_h___
 
 /*
- * nsRange.h: interface of the nsRange object.
+ * Implementation of the DOM Range object.
  */
 
+#ifndef nsRange_h___
+#define nsRange_h___
+
 #include "nsIDOMRange.h"
 #include "nsIRangeUtils.h"
 #include "nsIDOMNSRange.h"

content/base/src/nsScriptEventManager.cpp

@@ -36,6 +36,12 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * Class that allows finding an event handler <script> node (one using
+ * FOR="....") for a given event and dispatching the event to that
+ * node.
+ */
+
 #include "nsScriptEventManager.h"
 
 #include "nsString.h"

content/base/src/nsScriptEventManager.h

@@ -36,6 +36,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * Class that allows finding an event handler <script> node (one using
+ * FOR="....") for a given event and dispatching the event to that
+ * node.
+ */
 
 #include "nsCOMPtr.h"
 #include "nsAString.h"

content/base/src/nsScriptLoader.cpp

@@ -37,6 +37,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * A class that handles loading and evaluation of <script> elements.
+ */
+
 #include "nsScriptLoader.h"
 #include "nsIDOMCharacterData.h"
 #include "nsParserUtils.h"

content/base/src/nsScriptLoader.h

@@ -36,6 +36,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * A class that handles loading and evaluation of <script> elements.
+ */
+
 #ifndef __nsScriptLoader_h__
 #define __nsScriptLoader_h__
 

content/base/src/nsStubDocumentObserver.cpp

@@ -35,6 +35,13 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * nsStubDocumentObserver is an implementation of the nsIDocumentObserver
+ * interface (except for the methods on nsISupports) that is intended to be
+ * used as a base class within the content/layout library.  All methods do
+ * nothing.
+ */
+
 #include "nsStubDocumentObserver.h"
 
 NS_IMPL_NSIDOCUMENTOBSERVER_CORE_STUB(nsStubDocumentObserver)

content/base/src/nsStubDocumentObserver.h

@@ -34,17 +34,20 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * nsStubDocumentObserver is an implementation of the nsIDocumentObserver
+ * interface (except for the methods on nsISupports) that is intended to be
+ * used as a base class within the content/layout library.  All methods do
+ * nothing.
+ */
+
 #ifndef nsStubDocumentObserver_h_
 #define nsStubDocumentObserver_h_
 
 #include "nsIDocumentObserver.h"
 
 /**
- * nsStubDocumentObserver is an implementation of the
- * nsIDocumentObserver interface (except for the methods on nsISupports)
- * that is intended to be used within the content/layout library.  All
- * methods do nothing.
- *
  * There are two advantages to inheriting from nsStubDocumentObserver
  * rather than directly from nsIDocumentObserver:
  *  1. smaller compiled code size (since there's no need for the code

content/base/src/nsStyleLinkElement.cpp

@@ -37,6 +37,12 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * A base class which implements nsIStyleSheetLinkingElement and can
+ * be subclassed by various content nodes that want to load
+ * stylesheets (<style>, <link>, processing instructions, etc).
+ */
+
 #include "nsStyleLinkElement.h"
 
 #include "nsHTMLAtoms.h"

content/base/src/nsStyleLinkElement.h

@@ -36,6 +36,13 @@
  * the terms of any one of the MPL, the GPL or the LGPL.
  *
  * ***** END LICENSE BLOCK ***** */
+
+/*
+ * A base class which implements nsIStyleSheetLinkingElement and can
+ * be subclassed by various content nodes that want to load
+ * stylesheets (<style>, <link>, processing instructions, etc).
+ */
+
 #ifndef nsStyleLinkElement_h___
 #define nsStyleLinkElement_h___
 

content/base/src/nsSyncLoadService.cpp

@@ -36,6 +36,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+/*
+ * A service that provides methods for synchronously loading a DOM in various ways.
+ */
+
 #include "nsCOMPtr.h"
 #include "nsIChannel.h"
 #include "nsIDOMLoadListener.h"