Improve high-level api docs

Author: ashawley

shared/src/main/scala/scala/xml/Elem.scala

@@ -66,8 +66,15 @@ object Elem {
 }
 
 /**
- * The case class `Elem` extends the `Node` class,
- *  providing an immutable data object representing an XML element.
+ * An immutable data object representing an XML element.
+ *
+ * Child elements can be other [[Elem]]s or any one of the other [[Node]] types.
+ *
+ * XML attributes are implemented with the [[scala.xml.MetaData]] base
+ * class.
+ *
+ * Optional XML namespace scope is represented by
+ * [[scala.xml.NamespaceBinding]].
  *
  *  @param prefix        namespace prefix (may be null, but not the empty string)
  *  @param label         the element name

shared/src/main/scala/scala/xml/Node.scala

@@ -27,9 +27,16 @@ object Node {
 }
 
 /**
- * An abstract class representing XML with nodes of a labelled tree.
+ * An abstract class representing XML with nodes of a labeled tree.
  * This class contains an implementation of a subset of XPath for navigation.
  *
+ *  - [[scala.xml.Comment]] — XML comment
+ *  - [[scala.xml.Elem]] — XML element
+ *  - [[scala.xml.EntityRef]] — XML entity
+ *  - [[scala.xml.PCData]] — Character data section (CDATA)
+ *  - [[scala.xml.ProcInstr]] — Processing instruction (PI)
+ *  - [[scala.xml.Text]] — Stand-alone parsed character data
+ *
  * @author  Burak Emir and others
  * @version 1.1
  */

shared/src/main/scala/scala/xml/dtd/Decl.scala

@@ -12,6 +12,17 @@ package dtd
 
 import Utility.sbToString
 
+/**
+ * XML declarations
+ * 
+ *  - [[scala.xml.dtd.AttListDecl]] — Attribute list declaration (ATTLIST)
+ *  - [[scala.xml.dtd.AttrDecl]] — Attribute declaration
+ *  - [[scala.xml.dtd.ElemDecl]] — Element declaration (ELEMENT)
+ *  - [[scala.xml.dtd.ParameterEntityDecl]] — Parameter entity list (ENTITY %)
+ *  - [[scala.xml.dtd.ParsedEntityDecl]] — Parsed general entity list (ENTITY)
+ *  - [[scala.xml.dtd.PEReference]] — Parsed entity reference
+ *  - [[scala.xml.dtd.UnparsedEntityDecl]] — Unparsed entity list (ENTITY NDATA)
+ */
 sealed abstract class Decl
 
 sealed abstract class MarkupDecl extends Decl {

shared/src/main/scala/scala/xml/package.scala

@@ -8,6 +8,70 @@
 
 package scala
 
+/**
+ * This library provides support for the XML literal syntax in Scala programs.
+ * {{{
+ * val planets: scala.xml.Elem = <planets>
+ *   <planet id="earth">
+ *     <title>Earth</title>
+ *     <mass unit="kg">5.9742e24</mass>
+ *     <radius unit="m">6378.14e3</radius>
+ *   </planet>
+ *   <planet id="mars">
+ *     <title>Mars</title>
+ *     <mass unit="kg">0.64191e24</mass>
+ *     <radius unit="m">3397.0e3</radius>
+ *   </planet>
+ * </planets>
+ * }}}
+ *
+ * Additionally, you can mix Scala expressions in your XML elements by
+ * using the curly brace notation:
+ *
+ * {{{
+ * val sunMass = 1.99e30
+ * val sunRadius = 6.96e8
+ * val star = <star>
+ *   <title>Sun</title>
+ *   <mass unit="kg">{ sunMass }</mass>
+ *   <radius unit="m">{ sunRadius }</radius>
+ *   <surface unit="m²">{ 4 * Math.PI * Math.pow(sunRadius, 2) }</surface>
+ *   <volume unit="m³">{ 4/3 * Math.PI * Math.pow(sunRadius, 3) }</volume>
+ * </star>
+ * }}}
+ *
+ * An XML element, for example `<star/>` and `<planet/>`, is
+ * represented in this library as a case class, [[scala.xml.Elem]].
+ *
+ * The sub-elements of XML values share a common base class,
+ * [[scala.xml.Node]].
+ *
+ * However, the non-element declarations found in XML files share a
+ * different common base class, [[scala.xml.dtd.Decl]].  Additionally,
+ * document type declarations are represented by a different trait,
+ * [[scala.xml.dtd.DTD]].
+ *
+ * For reading and writing XML data to and from files, see
+ * [[scala.xml.XML]].  The default parser of XML data is the
+ * [[http://xerces.apache.org/ Xerces]] parser and is provided in Java
+ * by [[javax.xml.parsers.SAXParser]].
+ *
+ * A less greedy XML reader can return data as a sequential collection
+ * of events, see [[scala.xml.pull.XMLEventReader]].
+ *
+ * For more control of the input, use the parser written in Scala that
+ * is provided, [[scala.xml.parsing.ConstructingParser]].
+ *
+ * For working with XHTML input, use [[scala.xml.parsing.XhtmlParser]].
+ *
+ * For more control of the output, use the [[scala.xml.PrettyPrinter]].
+ *
+ * Utility methods for working with XML data are provided in
+ * [[scala.xml.Utility]].
+ *
+ * XML values in Scala are immutable, but you can traverse and
+ * transform XML data with a [[scala.xml.transform.RuleTransformer]].
+ */
 package object xml {
   val XercesClassName = "org.apache.xerces.parsers.SAXParser"