diff --git a/src/org/apache/xml/serializer/DOM3Serializer.java b/src/org/apache/xml/serializer/DOM3Serializer.java
index 11a81f8..b79ef91 100644
--- a/src/org/apache/xml/serializer/DOM3Serializer.java
+++ b/src/org/apache/xml/serializer/DOM3Serializer.java
@@ -23,37 +23,184 @@
 
 import java.io.IOException;
 
-import org.w3c.dom.Node;
 import org.w3c.dom.DOMErrorHandler;
+import org.w3c.dom.Node;
 import org.w3c.dom.ls.LSSerializerFilter;
 
 /**
  * Interface for a DOM serializer capable of serializing DOMs as specified in 
- * the DOM Level 3 Save Recommendation.
+ * the DOM Level 3 Save Recommendation. This interface is not intended to be used
+ * by an end user, but rather by an XML parser that is implementing the DOM 
+ * Level 3 Load and Save APIs.
+ * <p>
+ * 
+ * See the DOM Level 3 Load and Save interface at <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/load-save.html#LS-LSSerializer">LSSeializer</a>.
+ * 
+ * For a list of configuration parameters for DOM Level 3 see <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#DOMConfiguration">DOMConfiguration</a>.
+ * For additional configuration parameters available with the DOM Level 3 Load and Save API LSSerializer see
+ * <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/load-save.html#LS-LSSerializer-config">LSerializer config</a>.
+ * <p>
+ * The following example uses a DOM3Serializer indirectly, through an an XML
+ * parser that uses this class as part of its implementation of the DOM Level 3
+ * Load and Save APIs, and is the prefered way to serialize with DOM Level 3 APIs.
+ * <p>
+ * Example:
+ * <pre>
+ *    public class TestDOM3 {
+ *
+ *    public static void main(String args[]) throws Exception {
+ *        // Get document to serialize
+ *        TestDOM3 test = new TestDOM3();
+ *        
+ *        // Serialize using standard DOM Level 3 Load/Save APIs        
+ *        System.out.println(test.testDOM3LS());
+ *    }
+ *
+ *    public org.w3c.dom.Document getDocument() throws Exception {
+ *        // Create a simple DOM Document.
+ *        javax.xml.parsers.DocumentBuilderFactory factory = 
+ *            javax.xml.parsers.DocumentBuilderFactory.newInstance();
+ *        javax.xml.parsers.DocumentBuilder builder = factory.newDocumentBuilder();
+ *        byte[] bytes = "<parent><child/></parent>".getBytes();
+ *        java.io.InputStream is = new java.io.ByteArrayInputStream(bytes);
+ *        org.w3c.dom.Document doc = builder.parse(is);
+ *        return doc;
+ *    }
+ *    
+ *    //
+ *    // This method uses standard DOM Level 3 Load Save APIs:
+ *    //   org.w3c.dom.bootstrap.DOMImplementationRegistry
+ *    //   org.w3c.dom.ls.DOMImplementationLS
+ *    //   org.w3c.dom.ls.DOMImplementationLS
+ *    //   org.w3c.dom.ls.LSSerializer
+ *    //   org.w3c.dom.DOMConfiguration
+ *    //   
+ *    // The only thing non-standard in this method is the value set for the
+ *    // name of the class implementing the DOM Level 3 Load Save APIs,
+ *    // which in this case is:
+ *    //   org.apache.xerces.dom.DOMImplementationSourceImpl
+ *    //
+ *
+ *    public String testDOM3LS() throws Exception {
+ *        
+ *        // Get a simple DOM Document that will be serialized.
+ *        org.w3c.dom.Document docToSerialize = getDocument();
+ *
+ *        // Get a factory (DOMImplementationLS) for creating a Load and Save object.
+ *        System.setProperty(org.w3c.dom.bootstrap.DOMImplementationRegistry.PROPERTY,
+ *                "org.apache.xerces.dom.DOMImplementationSourceImpl");
+ *        org.w3c.dom.ls.DOMImplementationLS impl = 
+ *            (org.w3c.dom.ls.DOMImplementationLS) 
+ *            org.w3c.dom.bootstrap.DOMImplementationRegistry.newInstance().getDOMImplementation("LS");
+ *
+ *        // Use the factory to create an object (LSSerializer) used to 
+ *        // write out or save the document.
+ *        org.w3c.dom.ls.LSSerializer writer = impl.createLSSerializer();
+ *        org.w3c.dom.DOMConfiguration config = writer.getDomConfig();
+ *        config.setParameter("format-pretty-print", Boolean.TRUE);
+ *        
+ *        // Use the LSSerializer to write out or serialize the document to a String.
+ *        String serializedXML = writer.writeToString(docToSerialize);
+ *        return serializedXML;
+ *    }
+ *    
+ *    }  // end of class TestDOM3
+ * </pre>
  * <p>
  * The DOM3Serializer is a facet of a serializer and is obtained from the
  * asDOM3Serializer() method of the org.apache.xml.serializer.Serializer interface. 
  * A serializer may or may not support a level 3 DOM serializer, if it does not then the 
  * return value from asDOM3Serializer() is null.
  * <p>
+ * Using the DOM3Serializer interface directly is discouraged for use by end users.
+ * <p>
  * Example:
  * <pre>
- * Document     doc;
- * Serializer   ser;
- * OutputStream os;
- * DOMErrorHandler handler;
- * 
- * ser = ...;
- * os = ...;
- * handler = ...;
+ *   public class TestDOM3 {
  *
- * ser.setOutputStream( os );
- * DOM3Serialzier dser = (DOM3Serialzier)ser.asDOM3Serializer();
- * dser.setErrorHandler(handler);
- * dser.serialize(doc);
+ *   public static void main(String args[]) throws Exception {
+ *       // Get document to serialize
+ *       TestDOM3 test = new TestDOM3();
+ *       
+ *       // Serialize using implementation specific
+ *       // non-standard serialization
+ *       // APIs (use standard DOM Level 3 if you can) 
+ *       System.out.println(test.testDOM3Xalan());
+ *   }
+ *   
+ *   //
+ *   // This method uses non-standard, implementation specific
+ *   // classes:
+ *   //   org.apache.xml.serializer.OutputPropertiesFactory
+ *   //   org.apache.xml.serializer.SerializerFactory
+ *   //   org.apache.xml.serializer.Serializer
+ *   //   org.apache.xml.serializer.DOM3Serializer
+ *   // to serialize a Document.
+ *   // 
+ *   // These classes are intended to be used by an XML
+ *   // parser to implement Load Save support for DOM Level 3.
+ *   // They are not intended for use by an end user.
+ *   //
+ *   public String testDOM3Xalan() throws Exception {
+ *       // Get a simple DOM Document that will be serialized.
+ *       org.w3c.dom.Document doc = getDocument();
+ *    
+ *       // Get the default properties for serializing XML
+ *       java.util.Properties configProps = org.apache.xml.serializer.OutputPropertiesFactory
+ *               .getDefaultMethodProperties("xml");
+ *       
+ *       // Get a Serializer from the non-standard factory
+ *       org.apache.xml.serializer.Serializer ser = org.apache.xml.serializer.SerializerFactory
+ *               .getSerializer(configProps);
+ *       java.io.StringWriter sw = new java.io.StringWriter();
+ *       // Set the writer where the Serializer should write its output to.
+ *       ser.setWriter(sw);
+ *    
+ *       // Configure the Serializer with additional non-standard properties
+ *       // for DOM Level 3 serialization:
+ *       java.util.Properties props = new java.util.Properties();
+ *       props.setProperty(
+ *               "{http://www.w3.org/TR/DOM-Level-3-LS}format-pretty-print",
+ *               "explicit:yes");
+ *       ser.setOutputFormat(props);
+ *    
+ *       // Cast the Serializer to a DOM3Serializer and use it to serialize the Document.
+ *       org.apache.xml.serializer.DOM3Serializer dser = (org.apache.xml.serializer.DOM3Serializer) ser
+ *               .asDOM3Serializer();
+ *       dser.serializeDOM3(doc);
+ *       String serializedXML = sw.toString();
+ *       return serializedXML;
+ *   }
+ *   
+ *   }  // end of class TestDOM3
+ *   
  * </pre>
+ * <p>
+ * If a DOM3Serializer is used directly (not through the DOM Level 3 API LSSerializer,
+ * then the configuration properties for DOM Level 3 are supported:
+ * <ul>
+ * <li> "cdata-sections"
+ * <li> "comments"
+ * <li> "element-content-whitespace"
+ * <li> "entities"
+ * <li> "infoset"
+ * <li> "namespaces"
+ * <li> "namespace-declarations"
+ * <li> "split-cdata-sections"
+ * <li> "well-formed"
+ * </ul>
+ * <p>
+ * Also the following propertes for DOM Level 3 Load and Save are supported:
+ * <ul>
+ * <li> "{http://www.w3.org/TR/DOM-Level-3-LS}format-pretty-print" 
+ * <li> "format-pretty-print"
+ * <li> "xml-declaration"
+ * </ul>
  * 
+ * @see <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#DOMConfiguration">DOMConfiguration</a>
+ * @see <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/load-save.html#LS-LSSerializer-config">LSSerializer</a>
  * @see org.apache.xml.serializer.Serializer
+ * @see org.apache.xml.serializer.DOMSerializer
  * 
  * @xsl.usage general
  *