JavaDoc and Copyright notice tidyup

core/src/java/org/jdom2/Attribute.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
@@ -63,6 +63,14 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 /**
  * An XML attribute. Methods allow the user to obtain the value of the attribute
  * as well as namespace and type information.
+ * <p>
+ * <strong>JDOM 1.x Compatibility Note:</strong><br>
+ * The Attribute class in JDOM 1.x had a number of int Constants declared to
+ * represent different Attribute Types. JDOM2 has introduced an AttributeType
+ * enumeration instead. To facilitate compatibility and to simplify JDOM 1.x
+ * migrations, the replacement AttributeType enums are referenced still using
+ * the JDOM 1.x constant names. In JDOM 1.x these names referenced constant
+ * int values. In JDOM2 these names reference Enum constants. 
  *
  * @author  Brett McLaughlin
  * @author  Jason Hunter
@@ -81,59 +89,37 @@ public class Attribute extends CloneBase
 
 	// Keep the old constant names for one beta cycle to help migration
 
-	/**
-	 * @see AttributeType#UNDECLARED
-	 */
+	/** JDOM 1.x compatible reference to {@link AttributeType#UNDECLARED} */
 	public final static AttributeType UNDECLARED_TYPE = AttributeType.UNDECLARED;
 
-	/**
-	 * @see AttributeType#CDATA
-	 */
+	/** JDOM 1.x compatible reference to {@link AttributeType#CDATA} */
 	public final static AttributeType CDATA_TYPE = AttributeType.CDATA;
 
-	/**
-	 * @see AttributeType#ID
-	 */
+	/** JDOM 1.x compatible reference to {@link AttributeType#ID} */
 	public final static AttributeType ID_TYPE = AttributeType.ID;
 
-	/**
-	 * @see AttributeType#IDREF
-	 */
+	/** JDOM 1.x compatible reference to {@link AttributeType#IDREF} */
 	public final static AttributeType IDREF_TYPE = AttributeType.IDREF;
 
-	/**
-	 * @see AttributeType#IDREFS
-	 */
+	/** JDOM 1.x compatible reference to {@link AttributeType#IDREFS} */
 	public final static AttributeType IDREFS_TYPE = AttributeType.IDREFS;
 
-	/**
-	 * @see AttributeType#ENTITY
-	 */
+	/** JDOM 1.x compatible reference to {@link AttributeType#ENTITY} */
 	public final static AttributeType ENTITY_TYPE = AttributeType.ENTITY;
 
-	/**
-	 * @see AttributeType#ENTITIES
-	 */
+	/** JDOM 1.x compatible reference to {@link AttributeType#ENTITIES} */
 	public final static AttributeType ENTITIES_TYPE = AttributeType.ENTITIES;
 
-	/**
-	 * @see AttributeType#NMTOKEN
-	 */
+	/** JDOM 1.x compatible reference to {@link AttributeType#NMTOKEN} */
 	public final static AttributeType NMTOKEN_TYPE = AttributeType.NMTOKEN;
 
-	/**
-	 * @see AttributeType#NMTOKENS
-	 */
+	/** JDOM 1.x compatible reference to {@link AttributeType#NMTOKENS} */
 	public final static AttributeType NMTOKENS_TYPE = AttributeType.NMTOKENS;
 
-	/**
-	 * @see AttributeType#NOTATION
-	 */
+	/** JDOM 1.x compatible reference to {@link AttributeType#NOTATION} */
 	public final static AttributeType NOTATION_TYPE = AttributeType.NOTATION;
 
-	/**
-	 * @see AttributeType#ENUMERATION
-	 */
+	/** JDOM 1.x compatible reference to {@link AttributeType#ENUMERATION} */
 	public final static AttributeType ENUMERATED_TYPE = AttributeType.ENUMERATION;
 
 
@@ -205,7 +191,7 @@ public Attribute(final String name, final String value, final Namespace namespac
 	 *         {@link org.jdom2.Verifier#checkCharacterData}) or
 	 *         if the given attribute type is not one of the
 	 *         supported types.
-	 * @deprecated Use Constructor with AttributeType type, not int type.
+	 * @deprecated Use {@link #Attribute(String, String, AttributeType, Namespace)}.
 	 */
 	@Deprecated
 	public Attribute(final String name, final String value, final int type, final Namespace namespace) {
@@ -219,7 +205,7 @@ public Attribute(final String name, final String value, final int type, final Na
 	 *
 	 * @param name <code>String</code> name of <code>Attribute</code>.
 	 * @param value <code>String</code> value for new attribute.
-	 * @param type <code>int</code> type for new attribute.
+	 * @param type <code>AttributeType</code> for new attribute.
 	 * @param namespace <code>Namespace</code> namespace for new attribute.
 	 * @throws IllegalNameException if the given name is illegal as an
 	 *         attribute name or if if the new namespace is the default
@@ -269,7 +255,7 @@ public Attribute(final String name, final String value) {
 	 *
 	 * @param name <code>String</code> name of <code>Attribute</code>.
 	 * @param value <code>String</code> value for new attribute.
-	 * @param type <code>int</code> type for new attribute.
+	 * @param type <code>AttributeType</code> for new attribute.
 	 * @throws IllegalNameException if the given name is illegal as an
 	 *         attribute name.
 	 * @throws IllegalDataException if the given attribute value is
@@ -506,10 +492,9 @@ public Attribute setValue(final String value) {
 	}
 
 	/**
-	 * This will return the actual declared type of this
-	 * <code>Attribute</code>.
+	 * This will return the declared type of this <code>Attribute</code>.
 	 *
-	 * @return <code>int</code> - type for this attribute.
+	 * @return <code>AttributeType</code> - type for this attribute.
 	 */
 	public AttributeType getAttributeType() {
 		return type;

core/src/java/org/jdom2/AttributeList.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

core/src/java/org/jdom2/AttributeType.java

@@ -1,3 +1,57 @@
+/*--
+
+ Copyright (C) 2011-2012 Jason Hunter & Brett McLaughlin.
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code must retain the above copyright
+    notice, this list of conditions, and the following disclaimer.
+
+ 2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions, and the disclaimer that follows
+    these conditions in the documentation and/or other materials
+    provided with the distribution.
+
+ 3. The name "JDOM" must not be used to endorse or promote products
+    derived from this software without prior written permission.  For
+    written permission, please contact <request_AT_jdom_DOT_org>.
+
+ 4. Products derived from this software may not be called "JDOM", nor
+    may "JDOM" appear in their name, without prior written permission
+    from the JDOM Project Management <request_AT_jdom_DOT_org>.
+
+ In addition, we request (but do not require) that you include in the
+ end-user documentation provided with the redistribution and/or in the
+ software itself an acknowledgement equivalent to the following:
+     "This product includes software developed by the
+      JDOM Project (http://www.jdom.org/)."
+ Alternatively, the acknowledgment may be graphical using the logos
+ available at http://www.jdom.org/images/logos.
+
+ THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED.  IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT
+ CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ SUCH DAMAGE.
+
+ This software consists of voluntary contributions made by many
+ individuals on behalf of the JDOM Project and was originally
+ created by Jason Hunter <jhunter_AT_jdom_DOT_org> and
+ Brett McLaughlin <brett_AT_jdom_DOT_org>.  For more information
+ on the JDOM Project, please see <http://www.jdom.org/>.
+
+ */
+
 package org.jdom2;
 
 import org.xml.sax.Attributes;

core/src/java/org/jdom2/CDATA.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
@@ -66,6 +66,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  * @author  Jason Hunter
  * @author  Bradley S. Huffman
  * @author  Victor Toni
+ * @author  Rolf Lear
  */
 public class CDATA extends Text {
 

core/src/java/org/jdom2/CloneBase.java

@@ -1,45 +1,99 @@
+/*--
+
+ Copyright (C) 2012 Jason Hunter & Brett McLaughlin.
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code must retain the above copyright
+    notice, this list of conditions, and the following disclaimer.
+
+ 2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions, and the disclaimer that follows
+    these conditions in the documentation and/or other materials
+    provided with the distribution.
+
+ 3. The name "JDOM" must not be used to endorse or promote products
+    derived from this software without prior written permission.  For
+    written permission, please contact <request_AT_jdom_DOT_org>.
+
+ 4. Products derived from this software may not be called "JDOM", nor
+    may "JDOM" appear in their name, without prior written permission
+    from the JDOM Project Management <request_AT_jdom_DOT_org>.
+
+ In addition, we request (but do not require) that you include in the
+ end-user documentation provided with the redistribution and/or in the
+ software itself an acknowledgement equivalent to the following:
+     "This product includes software developed by the
+      JDOM Project (http://www.jdom.org/)."
+ Alternatively, the acknowledgment may be graphical using the logos
+ available at http://www.jdom.org/images/logos.
+
+ THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED.  IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT
+ CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ SUCH DAMAGE.
+
+ This software consists of voluntary contributions made by many
+ individuals on behalf of the JDOM Project and was originally
+ created by Jason Hunter <jhunter_AT_jdom_DOT_org> and
+ Brett McLaughlin <brett_AT_jdom_DOT_org>.  For more information
+ on the JDOM Project, please see <http://www.jdom.org/>.
+
+ */
+
 package org.jdom2;
 
 /**
- * This simple class just tidies up any cloneable classes.
- * This method deals with any CloneNotSupported exceptions.
- * THis class is package private only.
+ * This simple class just tidies up any cloneable classes. This method deals
+ * with any CloneNotSupported exceptions. THis class is package private only.
+ * 
  * @author Rolf Lear
- *
  */
 class CloneBase implements Cloneable {
-	
+
 	/**
-	 * This convenience method simply deals with the irritating
-	 * CloneNotSupportedException, and wraps it in IllegalStateException.
-	 * This should never, ever, ever happen. But, it is a pain to deal with
-	 * ugly clone code in some classes.
+	 * Return a deep clone of this instance. Even if this instance has a parent,
+	 * the returned clone will not.
 	 * <p>
-	 * Subclasses of this should still call super.clone() in their clone method.
-	 * <p>
-	 * Additionally, when you use the concept of 'co-variant return values' you
-	 * create 'bridge' methods. By way of example, because we change the return
-	 * type of clone() from Object to CloneBase, Java is forced to put in a
-	 * 'bridge' method that has an Object return type, even though we never
-	 * actually call it.
+	 * All JDOM core classes are Cloneable, and never throw
+	 * CloneNotSupportedException. Additionally all Cloneable JDOM classes
+	 * return the correct type of instance from this method and there is no
+	 * need to cast the result (co-variant return vaue).
 	 * <p>
-	 * This has an impact on the code coverage tool Cobertura, which reports
-	 * that there is missed code (and there is, the bridge method). It reports
-	 * it as being '0' calls to the 'class' line (the class line is marked red).
-	 * <p>
-	 * By making this CloneBase code do the first level of co-variant return, it
-	 * is this class which is victim of the Cobertura reporting, not the
-	 * multiple subclasses (like Attribute, Document, Content, etc.).
+	 * Subclasses of this should still call super.clone() in their clone method.
 	 */
 	@Override
 	protected CloneBase clone() {
+		/*
+		 * Additionally, when you use the concept of 'co-variant return values'
+		 * you create 'bridge' methods. By way of example, because we change the
+		 * return type of clone() from Object to CloneBase, Java is forced to
+		 * put in a 'bridge' method that has an Object return type, even though
+		 * we never actually call it. <p> This has an impact on the code
+		 * coverage tool Cobertura, which reports that there is missed code (and
+		 * there is, the bridge method). It reports it as being '0' calls to the
+		 * 'class' line (the class line is marked red). By making this CloneBase
+		 * code do the first level of co-variant return, it is this class which
+		 * is victim of the Cobertura reporting, not the multiple subclasses
+		 * (like Attribute, Document, Content, etc.).
+		 */
 		try {
-			return (CloneBase)super.clone();
+			return (CloneBase) super.clone();
 		} catch (CloneNotSupportedException e) {
 			throw new IllegalStateException(String.format(
 					"Unable to clone class %s which should always support it.",
-					this.getClass().getName()),
-					e);
+					this.getClass().getName()), e);
 		}
 	}
 

core/src/java/org/jdom2/Comment.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

core/src/java/org/jdom2/Content.java

@@ -1,6 +1,6 @@
 /*--
 
- Copyright (C) 2007 Jason Hunter & Brett McLaughlin.
+ Copyright (C) 2007-2012 Jason Hunter & Brett McLaughlin.
  All rights reserved.
 
  Redistribution and use in source and binary forms, with or without
@@ -72,6 +72,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  * 
  * @author Bradley S. Huffman
  * @author Jason Hunter
+ * @author Rolf Lear
  */
 public abstract class Content extends CloneBase
 		implements Serializable, NamespaceAware {
@@ -238,16 +239,6 @@ public Document getDocument() {
 	 */
 	public abstract String getValue();
 
-	/**
-	 * Returns a deep, unattached copy of this child and its descendants
-	 * detached from any parent or document.
-	 * <p>
-	 * This method can be overridden by particular Content subclasses to return
-	 * a specific type of Content (co-variant return type). All overriding
-	 * subclasses <b>must</b> call <code>super.clone()</code>;
-	 *
-	 * @return a detached deep copy of this child and descendants
-	 */
 	@Override
 	public Content clone() {
 		Content c = (Content)super.clone();

core/src/java/org/jdom2/ContentList.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

core/src/java/org/jdom2/DataConversionException.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