documentation for scala.xml.pull, contribution ...

documentation for scala.xml.pull, contribution by Dave Copeland. close
#3786, no review.

3 files changed, 77 insertions, 28 deletions

diff --git a/src/library/scala/xml/pull/XMLEvent.scala b/src/library/scala/xml/pull/XMLEvent.scala
index 3de618e3a7..255bf3b8a8 100644
--- a/src/library/scala/xml/pull/XMLEvent.scala
+++ b/src/library/scala/xml/pull/XMLEvent.scala
@@ -11,27 +11,49 @@
 package scala.xml
 package pull
 
-/** This class represents an XML event for pull parsing.
- *  Pull parsing means that during the traversal of the XML
- *  tree we are parsing, each "event" is returned to the caller
- *  and the traversal is suspended.
+/** An XML event for pull parsing.  All events received during
+ * parsing will be one of the subclasses of this trait.
  */
 trait XMLEvent
 
-/** An element is encountered the first time */
+/**
+ * An Element's start tag was encountered.
+ * @param pre prefix, if any, on the element.  This is the `xs` in `<xs:string>foo</xs:string>`.
+ * @param label the name of the element, not including the prefix
+ * @param attrs any attributes on the element
+ */
 case class EvElemStart(pre: String, label: String, attrs: MetaData, scope: NamespaceBinding) extends XMLEvent
 
-/** An element is encountered the last time */
+/**
+ * An Element's end tag was encountered.
+ * @param pre prefix, if any, on the element.  This is the `xs` in `<xs:string>foo</xs:string>`.
+ * @param label the name of the element, not including the prefix
+ */
 case class EvElemEnd(pre: String, label: String) extends XMLEvent
 
-/** A text node is encountered */
+/**
+ * A text node was encountered.
+ * @param text the text that was found
+ */
 case class EvText(text: String) extends XMLEvent
 
-/** An entity reference is encountered */
+/** An entity reference was encountered.
+ * @param the name of the entity, e.g. `gt` when encountering the entity `&gt;`
+ */
 case class EvEntityRef(entity: String) extends XMLEvent
 
-/** A processing instruction is encountered */
+/**
+ * A processing instruction was encountered.
+ * @param target the "PITarget" of the processing instruction.  For the instruction `<?foo bar="baz"?>`, the target would
+ * be `foo`
+ * @param text the remainder of the instruction.  For the instruction `<?foo bar="baz"?>`, the text would
+ * be `bar="baz"`
+ * @see [[http://www.w3.org/TR/REC-xml/#sec-pi]]
+ */
 case class EvProcInstr(target: String, text: String) extends XMLEvent
 
-/** A comment is encountered */
+/**
+ * A comment was encountered
+ * @param text the text of the comment
+ */
 case class EvComment(text: String) extends XMLEvent
diff --git a/src/library/scala/xml/pull/XMLEventReader.scala b/src/library/scala/xml/pull/XMLEventReader.scala
index 90c19f9c0b..fa428a440f 100644
--- a/src/library/scala/xml/pull/XMLEventReader.scala
+++ b/src/library/scala/xml/pull/XMLEventReader.scala
@@ -16,28 +16,14 @@ import java.nio.channels.ClosedChannelException
 import scala.io.Source
 import scala.xml.parsing.{ ExternalSources, MarkupHandler, MarkupParser }
 
-/** <p>
- *   A pull parser that offers to view an XML document as a series of events.
- *   Example usage:
- *  </p><pre>
- *  <b>import</b> scala.xml.pull._
- *  <b>import</b> scala.io.Source
- *
- *  <b>object</b> reader {
- *    <b>val</b> src = Source.fromString("<hello><world/></hello>")
- *    <b>val</b> er = new XMLEventReader(src)
- *
- *    <b>def</b> main(args: Array[String]) {
- *      while (er.hasNext)
- *        Console.println(er.next)
- *    }
- *  }
- *  </pre>
+/**
+ * Main entry point into creating an event-based XML parser.  Treating this
+ * as a [[scala.collection.Iterator]] will provide access to the generated events.
+ * @param src A [[scala.io.Source]] for XML data to parse
  *
  *  @author Burak Emir
  *  @author Paul Phillips
  */
-
 class XMLEventReader(src: Source) extends ProducerConsumerIterator[XMLEvent]
 {
   // We implement a pull parser as an iterator, but since we may be operating on
diff --git a/src/library/scala/xml/pull/package.scala b/src/library/scala/xml/pull/package.scala
new file mode 100644
index 0000000000..3742c55513
--- /dev/null
+++ b/src/library/scala/xml/pull/package.scala
@@ -0,0 +1,41 @@
+package scala.xml
+
+/**
+ * Classes needed to view an XML document as a series of events.  The document
+ * is parsed by an [[scala.xml.pull.XMLEventReader]] instance.  You can treat it as
+ * an [[scala.collection.Iterator]] to retrieve the events, which are all
+ * subclasses of [[scala.xml.pull.XMLEvent]].
+ *
+ * {{{
+ * scala> val source = Source.fromString("""<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+ * <?instruction custom value="customvalue"?>
+ * <!DOCTYPE foo [
+ *   <!ENTITY bar "BAR">
+ * ]><foo>Hello<!-- this is a comment --><bar>&bar;</bar><bar>&gt;</bar></foo>""")
+ *
+ * source: scala.io.Source = non-empty iterator
+ *
+ * scala> val reader = new XMLEventReader(source)
+ * reader: scala.xml.pull.XMLEventReader = non-empty iterator
+ *
+ * scala> reader.foreach{ println(_) }
+ * EvProcInstr(instruction,custom value="customvalue")
+ * EvText(
+ * )
+ * EvElemStart(null,foo,,)
+ * EvText(Hello)
+ * EvComment( this is a comment )
+ * EvElemStart(null,bar,,)
+ * EvText(BAR)
+ * EvElemEnd(null,bar)
+ * EvElemStart(null,bar,,)
+ * EvEntityRef(gt)
+ * EvElemEnd(null,bar)
+ * EvElemEnd(null,foo)
+ * EvText(
+ *
+ * )
+ *
+ * }}}
+ */
+package object pull