scala · ashawley · Dec 23, 2017 · Oct 9, 2017 · Oct 9, 2017
diff --git a/shared/src/main/scala/scala/xml/Attribute.scala b/shared/src/main/scala/scala/xml/Attribute.scala
@@ -14,7 +14,6 @@ package xml
  *  convenient construction and deconstruction.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 object Attribute {
   def unapply(x: Attribute) = x match {
@@ -47,7 +46,6 @@ object Attribute {
  *  [[scala.xml.PrefixedAttribute]] and [[scala.xml.UnprefixedAttribute]].
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 abstract trait Attribute extends MetaData {
   def pre: String // will be null if unprefixed

diff --git a/shared/src/main/scala/scala/xml/Document.scala b/shared/src/main/scala/scala/xml/Document.scala
@@ -16,7 +16,6 @@ package xml
  *  Also plays the role of an `XMLEvent` for pull parsing.
  *
  *  @author  Burak Emir
- *  @version 1.0, 26/04/2005
  */
 @SerialVersionUID(-2289320563321795109L)
 class Document extends NodeSeq with pull.XMLEvent with Serializable {

diff --git a/shared/src/main/scala/scala/xml/Elem.scala b/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

diff --git a/shared/src/main/scala/scala/xml/EntityRef.scala b/shared/src/main/scala/scala/xml/EntityRef.scala
@@ -13,7 +13,6 @@ package xml
  * The class `EntityRef` implements an XML node for entity references.
  *
  * @author  Burak Emir
- * @version 1.0
  * @param   entityName the name of the entity reference, for example `amp`.
  */
 case class EntityRef(entityName: String) extends SpecialNode {

diff --git a/shared/src/main/scala/scala/xml/Group.scala b/shared/src/main/scala/scala/xml/Group.scala
@@ -13,7 +13,6 @@ package xml
  * A hack to group XML nodes in one node for output.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 final case class Group(nodes: Seq[Node]) extends Node {
   override def theSeq = nodes

diff --git a/shared/src/main/scala/scala/xml/NamespaceBinding.scala b/shared/src/main/scala/scala/xml/NamespaceBinding.scala
@@ -18,7 +18,6 @@ import Utility.sbToString
  *  prefix nor uri may be empty, which is not checked.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 @SerialVersionUID(0 - 2518644165573446725L)
 case class NamespaceBinding(prefix: String, uri: String, parent: NamespaceBinding) extends AnyRef with Equality {

diff --git a/shared/src/main/scala/scala/xml/Node.scala b/shared/src/main/scala/scala/xml/Node.scala
@@ -14,7 +14,6 @@ package xml
  *  convenient deconstruction.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 object Node {
   /** the constant empty attribute sequence */
@@ -27,11 +26,17 @@ 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
  */
 abstract class Node extends NodeSeq {
 

diff --git a/shared/src/main/scala/scala/xml/NodeBuffer.scala b/shared/src/main/scala/scala/xml/NodeBuffer.scala
@@ -18,7 +18,6 @@ package xml
  * Calling the hashcode function will result in a runtime error.
  *
  * @author  Burak Emir
- * @version 1.0
  */
 class NodeBuffer extends scala.collection.mutable.ArrayBuffer[Node] {
 

diff --git a/shared/src/main/scala/scala/xml/NodeSeq.scala b/shared/src/main/scala/scala/xml/NodeSeq.scala
@@ -18,7 +18,6 @@ import scala.language.implicitConversions
  * This object ...
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 object NodeSeq {
   final val Empty = fromSeq(Nil)
@@ -40,7 +39,6 @@ object NodeSeq {
  *  and comprehension methods.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 abstract class NodeSeq extends AbstractSeq[Node] with immutable.Seq[Node] with SeqLike[Node, NodeSeq] with Equality with Serializable {
 

diff --git a/shared/src/main/scala/scala/xml/Null.scala b/shared/src/main/scala/scala/xml/Null.scala
@@ -18,7 +18,6 @@ import scala.collection.Iterator
  *  sort of a linked list of tails.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 case object Null extends MetaData {
   override def iterator = Iterator.empty

diff --git a/shared/src/main/scala/scala/xml/PCData.scala b/shared/src/main/scala/scala/xml/PCData.scala
@@ -15,7 +15,6 @@ package xml
  *  sections in the input and is to be preserved as CDATA section in the output.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 class PCData(data: String) extends Atom[String](data) {
 
@@ -35,7 +34,6 @@ class PCData(data: String) extends Atom[String](data) {
  *  convenient construction and deconstruction.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 object PCData {
   def apply(data: String) = new PCData(data)

diff --git a/shared/src/main/scala/scala/xml/PrettyPrinter.scala b/shared/src/main/scala/scala/xml/PrettyPrinter.scala
@@ -18,8 +18,6 @@ import Utility.sbToString
  *  XML nodes.
  *
  *  @author  Burak Emir
- *  @version 1.0
- *
  *  @param width the width to fit the output into
  *  @param step  indentation
  */

diff --git a/shared/src/main/scala/scala/xml/QNode.scala b/shared/src/main/scala/scala/xml/QNode.scala
@@ -14,7 +14,6 @@ package xml
  *  its namespace URI
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 object QNode {
   def unapplySeq(n: Node) = Some((n.scope.getURI(n.prefix), n.label, n.attributes, n.child))

diff --git a/shared/src/main/scala/scala/xml/Text.scala b/shared/src/main/scala/scala/xml/Text.scala
@@ -31,7 +31,6 @@ class Text(data: String) extends Atom[String](data) {
  *  convenient construction and deconstruction.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 object Text {
   def apply(data: String) = new Text(data)

diff --git a/shared/src/main/scala/scala/xml/Unparsed.scala b/shared/src/main/scala/scala/xml/Unparsed.scala
@@ -31,7 +31,6 @@ class Unparsed(data: String) extends Atom[String](data) {
  *  convenient construction and deconstruction.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 object Unparsed {
   def apply(data: String) = new Unparsed(data)

diff --git a/shared/src/main/scala/scala/xml/XML.scala b/shared/src/main/scala/scala/xml/XML.scala
@@ -54,7 +54,6 @@ object MinimizeMode extends Enumeration {
  *  when XML is handled using `Symbol` nodes.
  *
  *  @author  Burak Emir
- *  @version 1.0, 25/04/2005
  */
 object XML extends XMLLoader[Elem] {
   val xml = "xml"

diff --git a/shared/src/main/scala/scala/xml/dtd/Decl.scala b/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 {

diff --git a/shared/src/main/scala/scala/xml/dtd/impl/Base.scala b/shared/src/main/scala/scala/xml/dtd/impl/Base.scala
@@ -13,7 +13,6 @@ package xml.dtd.impl
  * Basic regular expressions.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 
 @deprecated("This class will be removed", "2.10.0")

diff --git a/shared/src/main/scala/scala/xml/dtd/impl/DetWordAutom.scala b/shared/src/main/scala/scala/xml/dtd/impl/DetWordAutom.scala
@@ -18,7 +18,6 @@ package xml.dtd.impl
  *  the partial function 'finals' is defined.
  *
  *  @author Burak Emir
- *  @version 1.0
  */
 // TODO: still used in ContentModel -- @deprecated("This class will be removed", "2.10.0")
 private[dtd] abstract class DetWordAutom[T <: AnyRef] {

diff --git a/shared/src/main/scala/scala/xml/dtd/impl/Inclusion.scala b/shared/src/main/scala/scala/xml/dtd/impl/Inclusion.scala
@@ -14,7 +14,6 @@ package xml.dtd.impl
  *  inspired by the ''AMoRE automata library''.
  *
  *  @author Burak Emir
- *  @version 1.0
  */
 @deprecated("This class will be removed", "2.10.0")
 private[dtd] trait Inclusion[A <: AnyRef] {

diff --git a/shared/src/main/scala/scala/xml/dtd/impl/PointedHedgeExp.scala b/shared/src/main/scala/scala/xml/dtd/impl/PointedHedgeExp.scala
@@ -13,7 +13,6 @@ package xml.dtd.impl
  * Pointed regular hedge expressions, a useful subclass of regular hedge expressions.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 @deprecated("This class will be removed", "2.10.0")
 private[dtd] abstract class PointedHedgeExp extends Base {

diff --git a/shared/src/main/scala/scala/xml/dtd/impl/SyntaxError.scala b/shared/src/main/scala/scala/xml/dtd/impl/SyntaxError.scala
@@ -14,7 +14,6 @@ package xml.dtd.impl
  *  syntactically incorrect expression is detected.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 @deprecated("This class will be removed", "2.10.0")
 private[dtd] class SyntaxError(e: String) extends RuntimeException(e)
diff --git a/shared/src/main/scala/scala/xml/dtd/impl/WordBerrySethi.scala b/shared/src/main/scala/scala/xml/dtd/impl/WordBerrySethi.scala
@@ -16,7 +16,6 @@ import scala.collection.{ immutable, mutable }
  * celebrated position automata construction (also called ''Berry-Sethi'' or ''Glushkov'').
  *
  *  @author Burak Emir
- *  @version 1.0
  */
 // TODO: still used in ContentModel -- @deprecated("This class will be removed", "2.10.0")
 @deprecated("This class will be removed", "2.10.0")

diff --git a/shared/src/main/scala/scala/xml/dtd/impl/WordExp.scala b/shared/src/main/scala/scala/xml/dtd/impl/WordExp.scala
@@ -35,7 +35,6 @@ package xml.dtd.impl
  *  }}}
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 // TODO: still used in ContentModel -- @deprecated("This class will be removed", "2.10.0")
 private[dtd] abstract class WordExp extends Base {

diff --git a/shared/src/main/scala/scala/xml/factory/LoggedNodeFactory.scala b/shared/src/main/scala/scala/xml/factory/LoggedNodeFactory.scala
@@ -28,7 +28,6 @@ package factory
  * }}}
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 @deprecated("This trait will be removed.", "2.11")
 trait LoggedNodeFactory[A <: Node] extends NodeFactory[A] {

diff --git a/shared/src/main/scala/scala/xml/package.scala b/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"
 

diff --git a/shared/src/main/scala/scala/xml/parsing/ConstructingHandler.scala b/shared/src/main/scala/scala/xml/parsing/ConstructingHandler.scala
@@ -14,7 +14,6 @@ package parsing
  * Implementation of MarkupHandler that constructs nodes.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 abstract class ConstructingHandler extends MarkupHandler {
   val preserveWS: Boolean

diff --git a/shared/src/main/scala/scala/xml/parsing/ExternalSources.scala b/shared/src/main/scala/scala/xml/parsing/ExternalSources.scala
@@ -17,7 +17,6 @@ import scala.io.Source
 
 /**
  *  @author  Burak Emir
- *  @version 1.0
  */
 trait ExternalSources {
   self: ExternalSources with MarkupParser with MarkupHandler =>

diff --git a/shared/src/main/scala/scala/xml/parsing/MarkupHandler.scala b/shared/src/main/scala/scala/xml/parsing/MarkupHandler.scala
@@ -16,11 +16,9 @@ import scala.xml.dtd._
 
 /**
  * class that handles markup - provides callback methods to MarkupParser.
- *  the default is nonvalidating behaviour
+ * the default is nonvalidating behaviour
  *
  *  @author  Burak Emir
- *  @version 1.0
- *
  *  @todo can we ignore more entity declarations (i.e. those with extIDs)?
  *  @todo expanding entity references
  */

diff --git a/shared/src/main/scala/scala/xml/parsing/MarkupParser.scala b/shared/src/main/scala/scala/xml/parsing/MarkupParser.scala
@@ -25,7 +25,6 @@ import Utility.Escapes.{ pairs => unescape }
  * collected using side-effects.
  *
  * @author  Burak Emir
- * @version 1.0
  */
 trait MarkupParser extends MarkupParserCommon with TokenTests {
   self: MarkupParser with MarkupHandler =>

diff --git a/shared/src/main/scala/scala/xml/transform/BasicTransformer.scala b/shared/src/main/scala/scala/xml/transform/BasicTransformer.scala
@@ -14,7 +14,6 @@ package transform
  * A class for XML transformations.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 abstract class BasicTransformer extends Function1[Node, Node] {
   protected def unchanged(n: Node, ns: Seq[Node]) =

diff --git a/shared/src/main/scala/scala/xml/transform/RewriteRule.scala b/shared/src/main/scala/scala/xml/transform/RewriteRule.scala
@@ -16,7 +16,6 @@ package transform
  *  is not applied.
  *
  *  @author  Burak Emir
- *  @version 1.0
  */
 abstract class RewriteRule extends BasicTransformer {
   /** a name for this rewrite rule */