doc

8 files changed, 109 insertions, 67 deletions

diff --git a/sources/scala/xml/AttributedNode.scala b/sources/scala/xml/AttributedNode.scala
index 3ff0d8f284..62674586a3 100644
--- a/sources/scala/xml/AttributedNode.scala
+++ b/sources/scala/xml/AttributedNode.scala
@@ -1,10 +1,17 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2004, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+** $Id$
+\*                                                                      */
 package scala.xml ;
 
 import scala.collection.Map;
 
 
-/** Superclass for specific representation of XML elements. These are created by
- *  a xxx2scala binding tool
+/** an XML node that may have attributes
  */
 trait AttributedNode extends Node {
 
@@ -30,14 +37,5 @@ trait AttributedNode extends Node {
 
     override def toXML:String = Utility.toXML(this);
 
-    override def toString() = toXML /*{
-        var s = new StringBuffer( "AttributedNode('"+label );
-        val as = attributes;
-        if( as != null )
-            s.append( Utility.attr2xml( as.elements ) );
-        s.append("(");
-        s.append( children.toString() );
-        s.append(")");
-        s.toString();
-    }*/
+    override def toString() = Utility.toXML(this);
 }
diff --git a/sources/scala/xml/BindingFactoryAdapter.scala b/sources/scala/xml/BindingFactoryAdapter.scala
index 6459f00968..02f247ca9e 100644
--- a/sources/scala/xml/BindingFactoryAdapter.scala
+++ b/sources/scala/xml/BindingFactoryAdapter.scala
@@ -1,9 +1,17 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2004, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+** $Id$
+\*                                                                      */
 package scala.xml ;
 
 import scala.collection.Map ;
 import scala.collection.mutable.HashMap ;
 
-/** a FactoryAdapter that creates instances of classes that bind XML types.
+/** a FactoryAdapter that creates instances of classes binding XML types.
 **   DTDs imported with the dtd2scala tool all use this class as interface
 **   to the SAX XML parser, by giving concrete values for the factory maps f and g.
 */
diff --git a/sources/scala/xml/FactoryAdapter.scala b/sources/scala/xml/FactoryAdapter.scala
index 19e2c0b64d..7e0595fb3a 100644
--- a/sources/scala/xml/FactoryAdapter.scala
+++ b/sources/scala/xml/FactoryAdapter.scala
@@ -1,16 +1,15 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2004, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+** $Id$
+\*                                                                      */
 package scala.xml ;
 
-
 import java.io.{OutputStream,OutputStreamWriter,PrintWriter,Writer};
 import java.io.UnsupportedEncodingException;
-
-
-/*import java.util.Map;
-import java.util.HashMap;
-import java.util.LinkedList;
-import java.util.Stack;
-import java.util.Iterator;
-*/
 import scala.collection.mutable.{HashMap,Stack};
 
 import org.xml.sax.Attributes;
@@ -31,6 +30,8 @@ import org.xml.sax.helpers.ParserAdapter;
 
 import org.xml.sax.helpers.XMLReaderFactory;
 
+/** SAX adapter class, for use with Java SAX parser
+**/
 abstract class FactoryAdapter
 	 extends DefaultHandler()
 	 // with ContentHandler
@@ -84,16 +85,6 @@ abstract class FactoryAdapter
   // ContentHandler methods
   //
 
-  /** Set document locator.
-   * @param locator
-  def setDocumentLocator( locator:Locator ):Unit = {}
-   */
-
-  /** Start document.
-  * @throws org.xml.sax.SAXException if ..
-  def startDocument():Unit = {}
-  */
-
   val normalizeWhitespace = false;
 
   /** Characters.
@@ -125,18 +116,7 @@ abstract class FactoryAdapter
 
           }
 	}
-        //System.err.println( "after \""+buffer+"\"" );
-        //System.err.println();
-
-    }
-
-    /** Ignorable whitespace.
-    def ignorableWhitespace(ch:Array[char] , offset:int , length:int ):Unit = {}
-     */
-
-    /** End document.
-     */
-    //def endDocument():Unit = {}
+   }
 
     //var elemCount = 0; //STATISTICS
 
@@ -163,17 +143,16 @@ abstract class FactoryAdapter
         var map:HashMap[String,String] = null:HashMap[String,String];
 
         if (attributes == null) {
-              //fOut.println("null");
+          // may not happen
         }
         else {
               map = new HashMap[String,String];
 
 	      for( val i <- List.range( 0, attributes.getLength() )) {
                 val attrLocalName = attributes.getLocalName(i);
-                //String attrQName = attributes.getQName(i);
-                //String attrURI = attributes.getURI(i);
                 val attrType = attributes.getType(i);
                 val attrValue = attributes.getValue(i);
+                // we only handle string attributes
                 if( attrType.equals("CDATA") ) {
 		  map.update( attrLocalName, attrValue );
 		}
@@ -185,8 +164,7 @@ abstract class FactoryAdapter
     } // startElement(String,String,String,Attributes)
 
 
-    /** this way to deal with whitespace is quite nonstandard, but useful
-     *
+    /** captures text, possibly normalizing whitespace
      */
     def captureText():Unit = {
         if (capture == true) {
@@ -233,14 +211,6 @@ abstract class FactoryAdapter
 
     } // endElement(String,String,String)
 
-    /** End prefix mapping.
-     def endPrefixMapping(prefix:String ):Unit  = {}
-     */
-
-    /** Skipped entity.
-     def skippedEntity(name:String ):Unit /*throws SAXException*/ = {}
-     */
-
     //
     // ErrorHandler methods
     //
diff --git a/sources/scala/xml/Node.scala b/sources/scala/xml/Node.scala
index 10a3f75221..92d5d7bd5b 100644
--- a/sources/scala/xml/Node.scala
+++ b/sources/scala/xml/Node.scala
@@ -1,11 +1,23 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2004, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+** $Id$
+\*                                                                      */
+
 package scala.xml ;
 
 
 /** Trait for representation of XML elements. These are created by
- *  a xxx2scala binding tool
+ *  a dtd2scala binding tool
  */
 trait Node {
+  /** the label of this XML node */
     def label: String;
+  /** the children of this XML node */
     def children: Seq[Node];
+  /** the string representation of this XML node */
     def toXML: String;
 }
diff --git a/sources/scala/xml/Text.scala b/sources/scala/xml/Text.scala
index 1c2b36faf8..bbb2a20e12 100644
--- a/sources/scala/xml/Text.scala
+++ b/sources/scala/xml/Text.scala
@@ -1,21 +1,38 @@
-/* BE */
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2004, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+** $Id$
+\*                                                                      */
+
 package scala.xml;
 
 import scala.collection.Map ;
 
-/** a text node. Used in both unsafe and typed XML representation
+/** an XML node for text (PCDATA). Used in both non-bound and bound XML representations
+ * @param text the text contained in this node
 **/
 
 case class Text( text:String ) extends Node {
 
+  /** the constant "#PCDATA"
+  */
   def label    = "#PCDATA";
 
-  def children = Nil;
+  /** always returns an empty list
+  */
+  final def children = Nil;
 
+  /** returns PCDATA text, with some characters escaped according to XML spec
+  */
   override def toXML = Utility.escape( text );
 
-  override def hashCode() = text.hashCode(); /* could be done at parse time, too */
-  override def toString() = "Text("+text+")";
+  override def hashCode() = text.hashCode();
 
-} // Text
+  /** returns "Text("+raw text+")"
+  */
+  override def toString() = "Text("+text+")";
 
+}
diff --git a/sources/scala/xml/Utility.scala b/sources/scala/xml/Utility.scala
index 72c8bcdcf8..985f7fd3c1 100644
--- a/sources/scala/xml/Utility.scala
+++ b/sources/scala/xml/Utility.scala
@@ -1,9 +1,19 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2004, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+** $Id$
+\*                                                                      */
+
 package scala.xml ;
 
 import java.lang.StringBuffer ; /* Java dependency! */
 import scala.collection.Map ;
 
-/** Utility functions for processing instances of bound and not bound XML classes.
+/** Utility functions for processing instances of bound and not bound XML classes,
+** as well as escaping text nodes
 **/
 
 object Utility {
diff --git a/sources/scala/xml/nobinding/NoBindingFactoryAdapter.scala b/sources/scala/xml/nobinding/NoBindingFactoryAdapter.scala
index 488ad0fba8..17bf4be118 100644
--- a/sources/scala/xml/nobinding/NoBindingFactoryAdapter.scala
+++ b/sources/scala/xml/nobinding/NoBindingFactoryAdapter.scala
@@ -1,3 +1,11 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2004, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+** $Id$
+\*                                                                      */
 package scala.xml.nobinding;
 
 import scala.collection.mutable.HashMap ;
@@ -10,11 +18,17 @@ import org.xml.sax.InputSource;
 */
 class NoBindingFactoryAdapter extends FactoryAdapter  {
 
+  // FactoryAdpater methods
+
+  /** returns true. Every XML node may contain text that the application needs
+  **/
   def nodeContainsText( label:java.lang.String ):boolean = true;
 
-  /* default behaviour is hash-consing */
+  /* default behaviour is to use hash-consing */
   val cache = new HashMap[int,Symbol]();
 
+  /** creates a node. never creates the same node twice, using hash-consing
+  */
   def createNode( label: String, attrs: HashMap[String,String], children: List[Node] ):Symbol = {
 
     val elHashCode = Utility.hashCode( label, attrs, children ) ;
@@ -41,8 +55,12 @@ class NoBindingFactoryAdapter extends FactoryAdapter  {
     }
   }
 
+  /** creates a text node
+  */
   def createText( text:String ) = Text( text );
 
+  /** loads an XML document, returning a Symbol node.
+  */
   override def loadXML( source:InputSource ):Symbol =
     super.loadXML( source ).asInstanceOf[ Symbol ]
 }
diff --git a/sources/scala/xml/nobinding/XML.scala b/sources/scala/xml/nobinding/XML.scala
index a50abd8b2a..e5cdf741cb 100644
--- a/sources/scala/xml/nobinding/XML.scala
+++ b/sources/scala/xml/nobinding/XML.scala
@@ -1,3 +1,11 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2004, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+** $Id$
+\*                                                                      */
 package scala.xml.nobinding ;
 
 import org.xml.sax.InputSource;
@@ -6,8 +14,9 @@ import scala.collection.Map ;
 import scala.collection.mutable.HashMap ;
 
 import scala.xml.Utility ;
+
 /** functions to load and save XML elements. use this when data binding is not
-**  desired.
+**  desired, i.e. when XML is handled using Symbol nodes
 **/
 object XML {