JavaDoc tidyup

build.xml

@@ -11,6 +11,7 @@ For instructions on how to build JDOM, please view the README.txt file.
 	<!-- =================================================================== -->
 	<tstamp >
 	    <format property="snapshot.time" pattern="yyyy.MM.dd.HH.mm" />
+	    <format property="year" pattern="yyyy" />
 	</tstamp>
 
 	<!--
@@ -34,7 +35,6 @@ For instructions on how to build JDOM, please view the README.txt file.
 	<property name="version" value="2.x-${snapshot.time}"/>
 	<property name="version.impl" value="${version}"/>
 	<property name="version.spec" value="2.alpha"/>
-	<property name="year" value="2011"/>
 
 	<property name="gpg" value="gpg" 
 		description="Path to the GNU gpg program for maven target"/>

core/src/java/org/jdom2/JDOMFactory.java

@@ -1,6 +1,6 @@
 /*--
 
- Copyright (C) 2000-2007 Jason Hunter & Brett McLaughlin.
+ Copyright (C) 2000-2012 Jason Hunter & Brett McLaughlin.
  All rights reserved.
 
  Redistribution and use in source and binary forms, with or without
@@ -65,6 +65,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  * @author  Ken Rune Holland
  * @author  Phil Nelson
  * @author  Bradley S. Huffman
+ * @author  Rolf Lear
  */
 public interface JDOMFactory {
 
@@ -183,6 +184,7 @@ public Attribute attribute(String name, String value,
 	 * @param col  The column on the line at which this content begins.
 	 * @param str <code>String</code> content of CDATA.
 	 * @return the created CDATA instance
+	 * @since JDOM2
 	 */
 	public CDATA cdata(int line, int col, String str);
 
@@ -195,6 +197,7 @@ public Attribute attribute(String name, String value,
 	 * @param col  The column on the line at which this content begins.
 	 * @param str <code>String</code> content of Text.
 	 * @return the created Text instance
+	 * @since JDOM2
 	 */
 	public Text text(int line, int col, String str);
 
@@ -225,6 +228,7 @@ public Attribute attribute(String name, String value,
 	 * @param col  The column on the line at which this content begins.
 	 * @param text <code>String</code> content of comment.
 	 * @return the created Comment instance
+	 * @since JDOM2
 	 */
 	public Comment comment(int line, int col, String text);
 
@@ -283,6 +287,7 @@ public DocType docType(String elementName,
 	 * @param systemID <code>String</code> system ID of
 	 *        referenced DTD
 	 * @return the created DocType instance
+	 * @since JDOM2
 	 */
 	public DocType docType(int line, int col, String elementName,
 			String publicID, String systemID);
@@ -299,6 +304,7 @@ public DocType docType(int line, int col, String elementName,
 	 * @param systemID <code>String</code> system ID of
 	 *        referenced DTD
 	 * @return the created DocType instance
+	 * @since JDOM2
 	 */
 	public DocType docType(int line, int col, String elementName, String systemID);
 
@@ -311,6 +317,7 @@ public DocType docType(int line, int col, String elementName,
 	 * @param elementName <code>String</code> name of
 	 *        element being constrained.
 	 * @return the created DocType instance
+	 * @since JDOM2
 	 */
 	public DocType docType(int line, int col, String elementName);
 
@@ -412,6 +419,7 @@ public DocType docType(int line, int col, String elementName,
 	 * @param name <code>String</code> name of element.
 	 * @param namespace <code>Namespace</code> to put element in.
 	 * @return the created Element instance
+	 * @since JDOM2
 	 */
 	public Element element(int line, int col, String name, Namespace namespace);
 
@@ -423,6 +431,7 @@ public DocType docType(int line, int col, String elementName,
 	 * @param col  The column on the line at which this content begins.
 	 * @param name <code>String</code> name of element.
 	 * @return the created Element instance
+	 * @since JDOM2
 	 */
 	public Element element(int line, int col, String name);
 
@@ -439,6 +448,7 @@ public DocType docType(int line, int col, String elementName,
 	 * @param uri <code>String</code> URI for <code>Namespace</code> element
 	 *        should be in.
 	 * @return the created Element instance
+	 * @since JDOM2
 	 */
 	public Element element(int line, int col, String name, String uri);
 
@@ -455,6 +465,7 @@ public DocType docType(int line, int col, String elementName,
 	 * @param uri <code>String</code> URI for <code>Namespace</code> element
 	 *        should be in.
 	 * @return the created Element instance
+	 * @since JDOM2
 	 */
 	public Element element(int line, int col, String name, String prefix, String uri);
 
@@ -502,6 +513,7 @@ public ProcessingInstruction processingInstruction(String target,
 	 * @param data <code>Map</code> data for PI, in
 	 *             name/value pairs
 	 * @return the created ProcessingInstruction instance
+	 * @since JDOM2
 	 */
 	public ProcessingInstruction processingInstruction(int line, int col, String target,
 			Map<String,String> data);
@@ -515,6 +527,7 @@ public ProcessingInstruction processingInstruction(int line, int col, String tar
 	 * @param target <code>String</code> target of PI.
 	 * @param data <code>String</code> data for PI.
 	 * @return the created ProcessingInstruction instance
+	 * @since JDOM2
 	 */
 	public ProcessingInstruction processingInstruction(int line, int col, String target,
 			String data);
@@ -527,6 +540,7 @@ public ProcessingInstruction processingInstruction(int line, int col, String tar
 	 * @param col  The column on the line at which this content begins.
 	 * @param target <code>String</code> target of PI.
 	 * @return the created ProcessingInstruction instance
+	 * @since JDOM2
 	 */
 	public ProcessingInstruction processingInstruction(int line, int col, String target);
 
@@ -570,6 +584,7 @@ public ProcessingInstruction processingInstruction(int line, int col, String tar
 	 * @param col  The column on the line at which this content begins.
 	 * @param name <code>String</code> name of element.
 	 * @return the created EntityRef instance
+	 * @since JDOM2
 	 */
 	public EntityRef entityRef(int line, int col, String name);
 
@@ -583,6 +598,7 @@ public ProcessingInstruction processingInstruction(int line, int col, String tar
 	 * @param publicID <code>String</code> public ID of element.
 	 * @param systemID <code>String</code> system ID of element.
 	 * @return the created EntityRef instance
+	 * @since JDOM2
 	 */
 	public EntityRef entityRef(int line, int col, String name, String publicID, String systemID);
 
@@ -595,6 +611,7 @@ public ProcessingInstruction processingInstruction(int line, int col, String tar
 	 * @param name <code>String</code> name of element.
 	 * @param systemID <code>String</code> system ID of element.
 	 * @return the created EntityRef instance
+	 * @since JDOM2
 	 */
 	public EntityRef entityRef(int line, int col, String name, String systemID);
 

core/src/java/org/jdom2/NamespaceAware.java

@@ -60,7 +60,8 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  * Classes implementing this interface are all sensitive to their
  * {@link Namespace} context. All the core JDOM classes are NamespaceAware (
  * {@link Parent} and subtypes, {@link Content} and subtypes, and
- * {@link Attribute}). You can use these methods to query the Namespace context.
+ * {@link Attribute}). You can use the methods that this interface provides
+ * to query the Namespace context.
  * <p>
  * JDOM2 introduces a consistency in reporting Namespace context. XML standards
  * do not dictate any conditions on Namespace reporting or ordering, but
@@ -96,7 +97,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  * <p>
  * In addition to the Element's Namespace, there could be other Namespaces that
  * are 'in scope' for the Element. The set of Namespaces that are in scope for
- * an Element are the union of five sets:
+ * an Element is the union of five sets:
  * <table>
  *   <tr>
  *     <th valign="top">XML</th>

core/src/java/org/jdom2/Parent.java

@@ -59,8 +59,8 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 import org.jdom2.filter.Filter;
 
 /**
- * Superclass for JDOM objects which are allowed to contain
- * {@link Content} content.
+ * Interface for JDOM objects which are allowed to contain
+ * {@link Content} content - {@link Element} and {@link Document}. 
  *
  * @see org.jdom2.Content
  * @see org.jdom2.Document

core/src/java/org/jdom2/input/SAXBuilder.java

@@ -113,8 +113,8 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  * Please read the full documentation of this class, {@link SAXHandler},
  * {@link SAXHandlerFactory}, {@link JDOMFactory}, and the package documentation
  * for {@link org.jdom2.input.sax} before overriding this class. Future versions
- * of JDOM2 may make this class may be made 'final'. I you feel you have a good
- * reason to subclass SAXBuilder please mention it on <a
+ * of JDOM2 may make this class 'final'. I you feel you have a good reason to
+ * subclass SAXBuilder please mention it on <a
  * href="http://www.jdom.org/involved/lists.html">jdom-interest</a> mailing list
  * so that SAXBuilder can be extended or adapted to handle your use-case.
  * <p>

core/src/java/org/jdom2/input/sax/package-info.java

@@ -1,6 +1,6 @@
 /*--
 
- Copyright (C) 2011 Jason Hunter & Brett McLaughlin.
+ Copyright (C) 2011-2012 Jason Hunter & Brett McLaughlin.
  All rights reserved.
 
  Redistribution and use in source and binary forms, with or without
@@ -53,7 +53,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  */
 
 /**
- Tools to build JDOM documents and content using SAX parsers.
+ Support classes for building JDOM documents and content using SAX parsers.
 
  <h2>Introduction</h2>
  Skip to the <a href="#Examples">Examples</a> section for a quick bootstrap. 

core/src/java/org/jdom2/package.html

@@ -56,7 +56,7 @@ <h1>JDOM helper classes</h1>
 If you have custom JDOM classes or want special treatment for content as it is
 being created you can supply you own JDOMFactory instance to the input Builder.
 Typically you would extend the DefaultJDOMFactory for this purpose. 
-The DefaultJDOMFactory ensures all XML rules are followed correctly, the
+The DefaultJDOMFactory ensures all XML rules are followed correctly. The
 UncheckedJDOMFactory may create JDOM content that does not follow XML
 well-formedness rules. Use the UncheckedJDOMFactory in places where you are
 certain the input is correct (perhaps the results of a document parsed by a