diff --git a/extensions/xforms/nsIInstanceElementPrivate.idl b/extensions/xforms/nsIInstanceElementPrivate.idl
index f81ff2132abc..139f41d078b3 100644
--- a/extensions/xforms/nsIInstanceElementPrivate.idl
+++ b/extensions/xforms/nsIInstanceElementPrivate.idl
@@ -38,12 +38,11 @@
 
 #include "nsISupports.idl"
 
+interface nsIDOMDocument;
+
 /**
  * Private interface implemented by the instance element.
  */
-
-interface nsIDOMDocument;
-
 [uuid(8c9dd10d-4189-4a7b-a2eb-fd695cf33b27)]
 interface nsIInstanceElementPrivate : nsISupports
 {
diff --git a/extensions/xforms/nsIModelElementPrivate.idl b/extensions/xforms/nsIModelElementPrivate.idl
index af993cddd97b..e544a2ec6d6e 100644
--- a/extensions/xforms/nsIModelElementPrivate.idl
+++ b/extensions/xforms/nsIModelElementPrivate.idl
@@ -36,17 +36,16 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
-/**
- * Private interface implemented by the model element for other
- * elements to use.
- */
-
 #include "nsIXFormsModelElement.idl"
 
 interface nsIXFormsControl;
 interface nsISchemaType;
 interface nsIInstanceElementPrivate;
 
+/**
+ * Private interface implemented by the model element for other
+ * elements to use.
+ */
 [uuid(b21b65d3-3305-4ce0-a604-3648cff61aca)]
 interface nsIModelElementPrivate : nsIXFormsModelElement
 {
diff --git a/extensions/xforms/nsIXFormsControl.idl b/extensions/xforms/nsIXFormsControl.idl
index f4920cd733f2..f7bcd20fd8c9 100644
--- a/extensions/xforms/nsIXFormsControl.idl
+++ b/extensions/xforms/nsIXFormsControl.idl
@@ -36,12 +36,11 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+#include "nsISupports.idl"
+
 /**
  * Interface implemented by all XForms form control classes.
  */
-
-#include "nsISupports.idl"
-
 [uuid(8377c845-5d55-4eee-9a76-0f86751dcbc8)]
 interface nsIXFormsControl : nsISupports
 {
diff --git a/extensions/xforms/nsIXFormsModelElement.idl b/extensions/xforms/nsIXFormsModelElement.idl
index e328fbbfd9af..6b126c253640 100644
--- a/extensions/xforms/nsIXFormsModelElement.idl
+++ b/extensions/xforms/nsIXFormsModelElement.idl
@@ -38,19 +38,18 @@
 
 #include "domstubs.idl"
 
+interface nsIDOMDocument;
+interface nsIDOMDOMException;
+
 /**
- * The nsIXFormsModelElement interface defines scriptable methods for
- * manipulating instance data and updating computed and displayed values.
+ * Defines scriptable methods for manipulating instance data
+ * and updating computed and displayed values.
  *
  * For more information on this interface please see
  * http://www.w3.org/TR/xforms/
  *
  * @status FROZEN
  */
-
-interface nsIDOMDocument;
-interface nsIDOMDOMException;
-
 [scriptable, uuid(e891d132-46f8-464c-b93b-1fb883fa03da)]
 interface nsIXFormsModelElement : nsISupports
 {
diff --git a/extensions/xforms/nsXFormsAtoms.h b/extensions/xforms/nsXFormsAtoms.h
index 5eb7d372364a..3bed35ae2148 100644
--- a/extensions/xforms/nsXFormsAtoms.h
+++ b/extensions/xforms/nsXFormsAtoms.h
@@ -38,6 +38,9 @@
 
 #include "nsStaticAtom.h"
 
+/**
+ * Class for singleton XForms nsIAtom pointers
+ */
 class nsXFormsAtoms
 {
  public:
diff --git a/extensions/xforms/nsXFormsElementFactory.h b/extensions/xforms/nsXFormsElementFactory.h
index b4229e56c761..b3b33d6cd394 100644
--- a/extensions/xforms/nsXFormsElementFactory.h
+++ b/extensions/xforms/nsXFormsElementFactory.h
@@ -41,6 +41,9 @@
 #define NS_XFORMSELEMENTFACTORY_CID \
 {0xc068f682, 0x03b5, 0x4e96, {0x81, 0xe1, 0x60, 0x13, 0xf9, 0x12, 0x88, 0xb2}}
 
+/**
+ * Factory class for all XForms elements
+ */
 class nsXFormsElementFactory : public nsIXTFElementFactory
 {
  public:
diff --git a/extensions/xforms/nsXFormsInputElement.cpp b/extensions/xforms/nsXFormsInputElement.cpp
index b885a4f8d3bc..691bd15d0a3e 100644
--- a/extensions/xforms/nsXFormsInputElement.cpp
+++ b/extensions/xforms/nsXFormsInputElement.cpp
@@ -63,6 +63,9 @@ static const nsIID sScriptingIIDs[] = {
   NS_IDOM3NODE_IID
 };
 
+/**
+ * Implementation of the XForms \<input\> element.
+ */
 class nsXFormsInputElement : public nsIXTFXMLVisual,
                              public nsIDOMFocusListener,
                              public nsIXFormsControl
diff --git a/extensions/xforms/nsXFormsInstanceElement.h b/extensions/xforms/nsXFormsInstanceElement.h
index 2a198cd548a7..38bfb235573a 100644
--- a/extensions/xforms/nsXFormsInstanceElement.h
+++ b/extensions/xforms/nsXFormsInstanceElement.h
@@ -36,12 +36,6 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
-/**
- * nsXFormsInstanceElement implements the xforms <instance> element.
- * It creates an instance document by either cloning the inline instance data
- * or loading an external xml document given by the src attribute.
- */
-
 #ifndef nsXFormsInstanceElement_h_
 #define nsXFormsInstanceElement_h_
 
@@ -54,6 +48,12 @@
 
 class nsIDOMElement;
 
+/**
+ * Implementation of the XForms \<instance\> element.
+ * It creates an instance document by either cloning the inline instance data
+ * or loading an external xml document given by the src attribute.
+ */
+
 class nsXFormsInstanceElement : public nsXFormsStubElement,
                                 public nsIInstanceElementPrivate,
                                 public nsIDOMLoadListener
diff --git a/extensions/xforms/nsXFormsModelElement.h b/extensions/xforms/nsXFormsModelElement.h
index 974485026dc3..7b77c559e3fa 100644
--- a/extensions/xforms/nsXFormsModelElement.h
+++ b/extensions/xforms/nsXFormsModelElement.h
@@ -57,6 +57,11 @@ class nsIDOMNode;
 class nsIDOMXPathEvaluator;
 class nsXFormsControl;
 
+/**
+ * XForms event types
+ *
+ * @see http://www.w3.org/TR/xforms/slice4.html#rpm-events
+ */
 enum nsXFormsModelEvent {
   eEvent_ModelConstruct,
   eEvent_ModelConstructDone,
@@ -73,6 +78,14 @@ enum nsXFormsModelEvent {
   eEvent_ComputeException
 };
 
+/**
+ * Implementation of the XForms \<model\> element.
+ *
+ * This includes all of the code for loading the model's external resources and
+ * initializing the model and its controls.
+ *
+ * @see http://www.w3.org/TR/xforms/slice3.html#structure-model
+ */
 class nsXFormsModelElement : public nsXFormsStubElement,
                              public nsIModelElementPrivate,
                              public nsISchemaLoadListener,
diff --git a/extensions/xforms/nsXFormsStubElement.h b/extensions/xforms/nsXFormsStubElement.h
index 2c71c99193d9..469b39aeb827 100644
--- a/extensions/xforms/nsXFormsStubElement.h
+++ b/extensions/xforms/nsXFormsStubElement.h
@@ -41,6 +41,12 @@
 
 #include "nsIXTFGenericElement.h"
 
+/**
+ * An implementation of a generic non-UI XForms element.
+ * 
+ * This is used for e.g. bind so that the id attribute works correctly for
+ * these nodes.
+ */
 class nsXFormsStubElement : public nsIXTFGenericElement
 {
   NS_DECL_ISUPPORTS
diff --git a/extensions/xforms/nsXFormsSubmissionElement.h b/extensions/xforms/nsXFormsSubmissionElement.h
index 12ecf33e0e09..fee4cebd8e69 100644
--- a/extensions/xforms/nsXFormsSubmissionElement.h
+++ b/extensions/xforms/nsXFormsSubmissionElement.h
@@ -54,6 +54,11 @@ class nsString;
 
 class SubmissionAttachmentArray;
 
+/**
+ * Implementation of the XForms \<submission\> element.
+ *
+ * @see http://www.w3.org/TR/xforms/slice3.html#structure-model-submission
+ */
 class nsXFormsSubmissionElement : public nsXFormsStubElement,
                                   public nsIRequestObserver
 {
diff --git a/extensions/xforms/nsXFormsTypes.h b/extensions/xforms/nsXFormsTypes.h
index 2dee20cbe37e..5ef62be45856 100644
--- a/extensions/xforms/nsXFormsTypes.h
+++ b/extensions/xforms/nsXFormsTypes.h
@@ -39,6 +39,9 @@
 #ifndef __NSXFORMSTYPES_H__
 #define __NSXFORMSTYPES_H__
 
+/**
+ * The types of Model Item Properties (MIP) in XForms
+ */
 enum ModelItemPropName
 {
   eModel_type,
diff --git a/extensions/xforms/nsXFormsUtils.h b/extensions/xforms/nsXFormsUtils.h
index e24225e48942..5bb59e741f23 100644
--- a/extensions/xforms/nsXFormsUtils.h
+++ b/extensions/xforms/nsXFormsUtils.h
@@ -39,11 +39,6 @@
 #ifndef nsXFormsUtils_h_
 #define nsXFormsUtils_h_
 
-/**
- * This class has static helper methods that don't fit into a specific place
- * in the class hierarchy.
- */
-
 #include "prtypes.h"
 #include "nsCOMPtr.h"
 #include "nsIDOMXPathResult.h"
@@ -58,6 +53,10 @@ class nsString;
 #define NS_NAMESPACE_XML_SCHEMA          "http://www.w3.org/2001/XMLSchema"
 #define NS_NAMESPACE_XML_SCHEMA_INSTANCE "http://www.w3.org/2001/XMLSchema-instance"
 
+/**
+ * This class has static helper methods that don't fit into a specific place
+ * in the class hierarchy.
+ */
 class nsXFormsUtils
 {
 public:
@@ -82,7 +81,7 @@ public:
 
   /**
    * Locate the model that |aElement| is bound to, and if applicable, the
-   * <bind> element that it uses.  The model is returned and the
+   * \<bind\> element that it uses.  The model is returned and the
    * bind element is returned (addrefed) in |aBindElement|.
    */
   static NS_HIDDEN_(nsIDOMNode*)
diff --git a/extensions/xforms/nsXFormsXPathXMLUtil.h b/extensions/xforms/nsXFormsXPathXMLUtil.h
index e563dffd6922..bdcf17c51a46 100644
--- a/extensions/xforms/nsXFormsXPathXMLUtil.h
+++ b/extensions/xforms/nsXFormsXPathXMLUtil.h
@@ -40,7 +40,7 @@
 #include "nsString.h"
 
 /**
- * Misc. utility functions for determining the class of a character, used by
+ * Miscellaneous utility functions for determining the class of a character, used by
  * nsXFormsXPathScanner.
  * 
  * @note Should be reimplemented and moved to Transformiix