Javadoc fixes

[Jerry James]

When I try to build the javadoc:javadoc target with maven and Sun's
JDK, it triggers this bug:

http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5101868

Until Sun fixes this bug, there are three workarounds available for
JSR-305:
1. Do not try to generate javadocs for the files in the default
package, located in sampleUses/src/main/java.
2. Put those files into a non-default package.
3. Don't pass the -use option to javadoc.

I favor #1, since those files are not part of the API.

Also, this patch fixes a few javadoc infelicities in the current
subversion repository:

diff -dur jsr-305.ORIG/ri/src/main/java/javax/annotation/meta/
TypeQualifier.java jsr-305/ri/src/main/java/javax/annotation/meta/
TypeQualifier.java
--- jsr-305.ORIG/ri/src/main/java/javax/annotation/meta/
TypeQualifier.java 2007-07-23 11:12:22.000000000 -0600
+++ jsr-305/ri/src/main/java/javax/annotation/meta/TypeQualifier.java
2008-04-15 14:34:31.000000000 -0600
@@ -23,29 +23,28 @@
/** If this qualifier defines a value, are the distinct values
mutually exclusive?
*
* For example, the following defines a type qualifier such that if
you know
- * a value is @Foo(Color.Red), then the value cannot be
@Foo(Color.Blue) or @Foo(Color.Green).
+ * a value is {@literal @Foo(Color.Red)}, then the value cannot be
+ * {@literal @Foo(Color.Blue)} or {@literal @Foo(Color.Green)}.
*
- * <code>
- * @TypeQualifier(exclusive=true) @interface Foo {
- * enum Color {RED, BLUE, GREEN};
- * Color value();
- * }
- * </code>
+ * {@code
+ @TypeQualifier(exclusive=true) @interface Foo {
+ enum Color {RED, BLUE, GREEN};
+ Color value();
+ }}
*
* */

boolean exclusive() default false;
/** If this qualifier defines an enum value, are the distinct values
exhaustive?
* For example, the following defines a type qualifier such that if
you know
- * a value is neither @Foo(Color.Red) or @Foo(Color.Blue), then the
value must be
- * @Foo(Color.Green).
+ * a value is neither {@literal @Foo(Color.Red)} or {@literal
@Foo(Color.Blue)},
+ * then the value must be {@literal @Foo(Color.Green)}.
*
- * <code>
- * @TypeQualifier(exhaustive=true) @interface Foo {
- * enum Color {RED, BLUE, GREEN};
- * Color value();
- * }
- * </code>
+ * {@code
+ @TypeQualifier(exhaustive=true) @interface Foo {
+ enum Color {RED, BLUE, GREEN};
+ Color value();
+ }}
*
* */
boolean exhaustive() default false;
diff -dur jsr-305.ORIG/ri/src/main/java/javax/annotation/meta/
TypeQualifierNickname.java jsr-305/ri/src/main/java/javax/annotation/
meta/TypeQualifierNickname.java
--- jsr-305.ORIG/ri/src/main/java/javax/annotation/meta/
TypeQualifierNickname.java 2007-09-24 08:44:12.000000000 -0600
+++ jsr-305/ri/src/main/java/javax/annotation/meta/
TypeQualifierNickname.java 2008-04-15 14:34:31.000000000 -0600
@@ -11,16 +11,15 @@
* be interpreted as having the same meaning as applying all of
annotations of X
* (other than QualifierNickname) to Y.
*
- * Thus, you might define a qualifier SocialSecurityNumber as
follows:
+ * <p>Thus, you might define a qualifier SocialSecurityNumber as
follows:</p>
*
*
- * <code>
+ * {@code
@Documented
@QualifierNickname @Pattern("[0-9]{3}-[0-9]{2}-[0-9]{4}")
@Retention(RetentionPolicy.RUNTIME)
public @interface SocialSecurityNumber {
- }
- </code>
+ }}
*
*
*/
diff -dur jsr-305.ORIG/ri/src/main/java/javax/annotation/meta/
TypeQualifierValidator.java jsr-305/ri/src/main/java/javax/annotation/
meta/TypeQualifierValidator.java
--- jsr-305.ORIG/ri/src/main/java/javax/annotation/meta/
TypeQualifierValidator.java 2007-07-20 08:45:17.000000000 -0600
+++ jsr-305/ri/src/main/java/javax/annotation/meta/
TypeQualifierValidator.java 2008-04-15 14:34:31.000000000 -0600
@@ -8,10 +8,9 @@
/**
* Given a type qualifier, check to see if a value is an instance
of the
* set of values denoted by the qualifier
- * @param annotation
- * @param annotationArgument
- * @param value
- * @return
+ * @param qualifierqualifierArgument the type qualifier
+ * @param value the value to check for membership
+ * @return a description of when value is an instance of
qualifierqualifierArgument
*/
public @Nonnull When forConstantValue(@Nonnull A
qualifierqualifierArgument, Object value);
}
diff -dur jsr-305.ORIG/ri/src/main/java/javax/annotation/meta/
When.java jsr-305/ri/src/main/java/javax/annotation/meta/When.java
--- jsr-305.ORIG/ri/src/main/java/javax/annotation/meta/When.java
2007-08-15 08:37:04.000000000 -0600
+++ jsr-305/ri/src/main/java/javax/annotation/meta/When.java
2008-04-15 14:34:31.000000000 -0600
@@ -4,8 +4,8 @@
* Used to describe the relationship between a qualifier T and the
set of values S possible
* on an annotated element.
*
- * In particular, an issues should be reported if an ALWAYS,
MAYBE_YES, or MAYBE_EITHER
- * value is used where a NEVER value is required, or if a NEVER,
MAYBE_NO, or MAYBE_EITHER
+ * In particular, an issue should be reported if an ALWAYS or MAYBE
+ * value is used where a NEVER value is required, or if a NEVER or
MAYBE
* value is used where an ALWAYS value is required.
*
*
diff -dur jsr-305.ORIG/sampleUses/pom.xml jsr-305/sampleUses/pom.xml
--- jsr-305.ORIG/sampleUses/pom.xml 2008-04-15 10:52:35.000000000
-0600
+++ jsr-305/sampleUses/pom.xml 2008-04-15 14:35:15.000000000 -0600
@@ -12,9 +12,9 @@
<groupId>org.jsr-305</groupId>
<artifactId>sampleUses</artifactId>
<packaging>jar</packaging>
- <name>JSR 305 Sample Uses Cases</name>
+ <name>JSR 305 Sample Use Cases</name>
<version>0.1-SNAPSHOT</version>
- <description>Use Cases for JS-305</description>
+ <description>Use Cases for JSR-305</description>

<dependencies>
<dependency>

[Jerry James]

I might as well fix a few more typos I have found today. Here's an
updated version of the patch. Also, is anybody home? The lights are
on....

diff -dur jsr-305.ORIG/proposedAnnotations/pom.xml jsr-305/
proposedAnnotations/pom.xml
--- jsr-305.ORIG/proposedAnnotations/pom.xml 2007-03-04
14:21:55.000000000 -0700
+++ jsr-305/proposedAnnotations/pom.xml 2008-04-18 13:52:15.000000000
-0600
@@ -15,5 +15,5 @@
<packaging>jar</packaging>
<name>JSR 305 Proposed Annotations</name>
<version>0.1-SNAPSHOT</version>
- <description>Proposed Annotations for JS-305</description>
+ <description>Proposed Annotations for JSR-305</description>
</project>
diff -dur jsr-305.ORIG/ri/pom.xml jsr-305/ri/pom.xml
--- jsr-305.ORIG/ri/pom.xml 2007-03-04 14:28:11.000000000 -0700
+++ jsr-305/ri/pom.xml 2008-04-18 13:52:02.000000000 -0600
@@ -14,7 +14,7 @@
<packaging>jar</packaging>
<name>JSR 305 Implementation</name>
<version>0.1-SNAPSHOT</version>
- <description>Implementation for JS-305</description>
+ <description>Implementation for JSR-305</description>


</project>

diff -dur jsr-305.ORIG/ri/src/main/java/javax/annotation/meta/
TypeQualifier.java jsr-305/ri/src/main/java/javax/annotation/meta/
TypeQualifier.java
--- jsr-305.ORIG/ri/src/main/java/javax/annotation/meta/
TypeQualifier.java 2007-07-23 11:12:22.000000000 -0600
+++ jsr-305/ri/src/main/java/javax/annotation/meta/TypeQualifier.java

2008-04-18 13:51:48.000000000 -0600

TypeQualifierNickname.java 2008-04-18 13:51:48.000000000 -0600

TypeQualifierValidator.java 2008-04-18 13:51:48.000000000 -0600

@@ -8,10 +8,9 @@
/**
* Given a type qualifier, check to see if a value is an instance
of the
* set of values denoted by the qualifier
- * @param annotation
- * @param annotationArgument
- * @param value
- * @return
+ * @param qualifierqualifierArgument the type qualifier
+ * @param value the value to check for membership
+ * @return a description of when value is an instance of
qualifierqualifierArgument
*/
public @Nonnull When forConstantValue(@Nonnull A
qualifierqualifierArgument, Object value);
}
diff -dur jsr-305.ORIG/ri/src/main/java/javax/annotation/meta/
When.java jsr-305/ri/src/main/java/javax/annotation/meta/When.java
--- jsr-305.ORIG/ri/src/main/java/javax/annotation/meta/When.java
2007-08-15 08:37:04.000000000 -0600
+++ jsr-305/ri/src/main/java/javax/annotation/meta/When.java

2008-04-18 13:51:48.000000000 -0600

@@ -4,8 +4,8 @@
* Used to describe the relationship between a qualifier T and the
set of values S possible
* on an annotated element.
*
- * In particular, an issues should be reported if an ALWAYS,
MAYBE_YES, or MAYBE_EITHER
- * value is used where a NEVER value is required, or if a NEVER,
MAYBE_NO, or MAYBE_EITHER
+ * In particular, an issue should be reported if an ALWAYS or MAYBE
+ * value is used where a NEVER value is required, or if a NEVER or
MAYBE
* value is used where an ALWAYS value is required.
*
*
diff -dur jsr-305.ORIG/sampleUses/pom.xml jsr-305/sampleUses/pom.xml

--- jsr-305.ORIG/sampleUses/pom.xml 2008-04-18 13:51:35.000000000
-0600
+++ jsr-305/sampleUses/pom.xml 2008-04-18 13:51:48.000000000 -0600

@@ -12,9 +12,9 @@
<groupId>org.jsr-305</groupId>
<artifactId>sampleUses</artifactId>
<packaging>jar</packaging>
- <name>JSR 305 Sample Uses Cases</name>
+ <name>JSR 305 Sample Use Cases</name>
<version>0.1-SNAPSHOT</version>
- <description>Use Cases for JS-305</description>
+ <description>Use Cases for JSR-305</description>

<dependencies>
<dependency>

diff -dur jsr-305.ORIG/tcl/pom.xml jsr-305/tcl/pom.xml
--- jsr-305.ORIG/tcl/pom.xml 2007-03-04 14:22:36.000000000 -0700
+++ jsr-305/tcl/pom.xml 2008-04-18 13:52:35.000000000 -0600
@@ -15,7 +15,7 @@
<packaging>jar</packaging>
<name>JSR 305 Test Cases</name>
<version>0.1-SNAPSHOT</version>
- <description>Test Cases for JS-305 Implementations</description>
+ <description>Test Cases for JSR-305 Implementations</description>

<dependencies>
<dependency>