Index: src/java/javax/jdo/annotations/Join.java
===================================================================
--- src/java/javax/jdo/annotations/Join.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Join.java	(working copy)
@@ -28,27 +28,35 @@
  * @version 2.1
  * @since 2.1
  */
-@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD}) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Join
 {
-    /** Table to join to (used when joining to secondary tables). */
+    /** Table to join to (used when joining to secondary tables). 
+     */
     String table() default "";
 
-    /** Name of the column in the join table. */
+    /** Name of the column in the join table. 
+     */
     String column() default "";
 
-    /** Whether the join column is indexed. */
+    /** Whether the join column is indexed. 
+     */
     String indexed() default "";
 
-    /** Whether the join column is unique */
+    /** Whether the join column is unique 
+     */
     String unique() default "";
 
-    /** Whether to use an outer join. */
+    /** Whether to use an outer join. 
+     */
     String outer() default "";
 
-    /** Delete action to be applied to any ForeignKey on this join. */
+    /** Delete action to be applied to any ForeignKey on this join. 
+     */
     ForeignKeyAction deleteAction() default ForeignKeyAction.UNKNOWN;
 
-    /** Detail definition of the join column(s). */
+    /** Detail definition of the join column(s). 
+     */
     Column[] columns() default {};
 }
\ No newline at end of file
Index: src/java/javax/jdo/annotations/Extensions.java
===================================================================
--- src/java/javax/jdo/annotations/Extensions.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Extensions.java	(working copy)
@@ -33,7 +33,7 @@
 {
     /**
      * The extensions.
-     * @return The extensions
+     * @return the extensions
      */
     Extension[] value();
 }
\ No newline at end of file
Index: src/java/javax/jdo/annotations/PersistenceAware.java
===================================================================
--- src/java/javax/jdo/annotations/PersistenceAware.java	(revision 553258)
+++ src/java/javax/jdo/annotations/PersistenceAware.java	(working copy)
@@ -27,7 +27,8 @@
  * @version 2.1
  * @since 2.1
  */
-@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface PersistenceAware
 {
 }
\ No newline at end of file
Index: src/java/javax/jdo/annotations/Query.java
===================================================================
--- src/java/javax/jdo/annotations/Query.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Query.java	(working copy)
@@ -28,24 +28,37 @@
  * @version 2.1
  * @since 2.1
  */
-@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Query
 {
-    /** Name of the query (mandatory) */
+    /** Name of the query (mandatory)
+     * @return the name of the query
+     */
     String name();
 
-    /** The query string (mandatory) */
+    /** The query string (mandatory)
+     * @return the query string
+     */
     String value();
 
-    /** The query language */
+    /** The query language
+     * @return the query language
+     */
     QueryLanguage language() default QueryLanguage.JDOQL;
 
-    /** Whether the query is unmodifiable. */
+    /** Whether the query is unmodifiable.
+     * @return whether the query is unmodifiable
+     */
     String unmodifiable() default "";
 
-    /** Whether the query returns unique results. */
+    /** Whether the query returns a single unique result.
+     * @return whether the query returns a single unique result
+     */
     String unique() default "";
 
-    /** Result Class to dump the results into */
+    /** Result class to put the results into
+     * @return the class of the result
+     */
     Class resultClass() default void.class;
 }
Index: src/java/javax/jdo/annotations/FetchGroup.java
===================================================================
--- src/java/javax/jdo/annotations/FetchGroup.java	(revision 553258)
+++ src/java/javax/jdo/annotations/FetchGroup.java	(working copy)
@@ -34,20 +34,20 @@
 {
     /**
      * Name of the fetch group.
-     * @return the name of the fetch group.
+     * @return the name of the fetch group
      */
     String name() default "";
 
     /**
      * Whether we should load this group as part of the post load process.
-     * @return Whether we should load this group as part of the post load 
+     * @return whether we should load this group as part of the post load 
      * process.
      */
     String postLoad() default "";
 
     /**
-     * Field definition for the fetch group
-     * @return Field definition for the fetch group
+     * Field definition for the fetch group.
+     * @return field definition for the fetch group
      */
     FetchField[] fields();
 
Index: src/java/javax/jdo/annotations/Unique.java
===================================================================
--- src/java/javax/jdo/annotations/Unique.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Unique.java	(working copy)
@@ -28,21 +28,34 @@
  * @version 2.1
  * @since 2.1
  */
-@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD}) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Unique
 {
-    /** Name of the unique constraint. */
+    /** Name of the unique constraint.
+     * @return the name of the unique constraint
+     */
     String name() default "";
 
-    /** Table for the unique constraint (if required). */
+    /** Table for the unique constraint. This is needed iff annotating a type 
+     * where the unique constraint is not defined on the primary table for 
+     * the type.
+     * @return the table on which the unique constraint is defined
+     */
     String table() default "";
 
-    /** Whether this unique constraint is deferred */
+    /** Whether this unique constraint is deferred until commit.
+     * @return whether this unique constraint is deferred until commit
+     */
     String deferred() default "";
 
-    /** Field names that comprise this index. */
+    /** Field names that comprise this unique constraint.
+     * @return field names that comprise this unique constraint
+     */
     String[] fields() default {};
 
-    /** Columns that comprise this index. */
+    /** Columns that comprise this unique constraint.
+     * @return columns that comprise this unique constraint
+     */
     Column[] columns() default {};
 }
Index: src/java/javax/jdo/annotations/NullValue.java
===================================================================
--- src/java/javax/jdo/annotations/NullValue.java	(revision 553258)
+++ src/java/javax/jdo/annotations/NullValue.java	(working copy)
@@ -17,7 +17,7 @@
 package javax.jdo.annotations;
 
 /**
- * Enumeration of the JDO2 "null-value" behaviour values.
+ * Enumeration of the JDO2 "null-value" behavior values.
  * 
  * @version 2.1
  * @since 2.1
Index: src/java/javax/jdo/annotations/Joins.java
===================================================================
--- src/java/javax/jdo/annotations/Joins.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Joins.java	(working copy)
@@ -27,11 +27,15 @@
  * @version 2.1
  * @since 2.1
  */
-@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Joins
 {
     /**
-     * The join definitions
+     * The join definitions used for the mapping of this type. Joins for
+     * secondary tables are usually defined at the type level and not the
+     * field or property level. This allows multiple fields and properties
+     * to share the same join definition and avoid redundancies.
      * @return The join definitions
      */
     Join[] value();
Index: src/java/javax/jdo/annotations/Field.java
===================================================================
--- src/java/javax/jdo/annotations/Field.java	(revision 553264)
+++ src/java/javax/jdo/annotations/Field.java	(working copy)
@@ -84,7 +84,7 @@
     String sequence() default "";
 
     /** Name of the fetch-group to use when this field is loaded 
-     * due to being referenced when not already loaded 
+     * due to being referenced when not already loaded.
      * @return the name of the load fetch group
      */
     String loadFetchGroup() default "";
Index: src/java/javax/jdo/annotations/Property.java
===================================================================
--- src/java/javax/jdo/annotations/Property.java	(revision 553264)
+++ src/java/javax/jdo/annotations/Property.java	(working copy)
@@ -27,7 +27,8 @@
  * @version 2.1
  * @since 2.1
  */
-@Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.METHOD}) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Property
 {
     /** Modifier for this property. 
Index: src/java/javax/jdo/annotations/Version.java
===================================================================
--- src/java/javax/jdo/annotations/Version.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Version.java	(working copy)
@@ -28,30 +28,31 @@
  * @version 2.1
  * @since 2.1
  */
-@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Version
 {
     /**
-     * Strategy for versioning of objects of this class
-     * @return Strategy for versioning objects of this class
+     * Strategy for versioning of objects of this class.
+     * @return the strategy for versioning objects of this class
      */
     VersionStrategy strategy();
 
     /**
-     * Name of the column for the version
-     * @return Name of the column for the version
+     * Name of the column for the version.
+     * @return the name of the column for the version
      */
     String column() default "";
 
     /**
-     * Whether the version column(s) is indexed
-     * @return Whether the version column(s) is indexed
+     * Whether the version column(s) is(are) indexed.
+     * @return whether the version column(s) is(are) indexed
      */
     String indexed() default "";
 
     /**
      * The column(s) making up the version.
-     * @return The column(s) making up the version.
+     * @return the column(s) making up the version
      */
     Column[] columns() default {};
 }
Index: src/java/javax/jdo/annotations/ForeignKeys.java
===================================================================
--- src/java/javax/jdo/annotations/ForeignKeys.java	(revision 553258)
+++ src/java/javax/jdo/annotations/ForeignKeys.java	(working copy)
@@ -27,7 +27,8 @@
  * @version 2.1
  * @since 2.1
  */
-@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface ForeignKeys
 {
     /**
Index: src/java/javax/jdo/annotations/Embedded.java
===================================================================
--- src/java/javax/jdo/annotations/Embedded.java	(revision 553348)
+++ src/java/javax/jdo/annotations/Embedded.java	(working copy)
@@ -51,10 +51,12 @@
     String nullIndicatorValue() default "";
 
     /** Field definitions for this embedding. 
+     * @return the fields embedded in the field or property being annotated
      */
     Field[] fields() default {};
 
     /** Property definitions for this embedding. 
-     */
+      * @return the properties embedded in the field or property being annotated
+    */
     Property[] properties() default {};
 }
\ No newline at end of file
Index: src/java/javax/jdo/annotations/Serialized.java
===================================================================
--- src/java/javax/jdo/annotations/Serialized.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Serialized.java	(working copy)
@@ -22,13 +22,14 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotation for whether the field is stored serialised.
+ * Annotation for whether the field is stored serialized.
  * This is the same as specifying @Field(serialized="true").
  * 
  * @version 2.1
  * @since 2.1
  */
-@Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.METHOD}) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Serialized
 {
 }
\ No newline at end of file
Index: src/java/javax/jdo/annotations/Transactional.java
===================================================================
--- src/java/javax/jdo/annotations/Transactional.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Transactional.java	(working copy)
@@ -23,12 +23,14 @@
 
 /**
  * Annotation for whether the field is transactional.
- * This is the same as specifying @Field(persistenceModifier=FieldPersistenceModifier.TRANSACTIONAL).
+ * This is the same as specifying 
+ * @Field(persistenceModifier=FieldPersistenceModifier.TRANSACTIONAL).
  * 
  * @version 2.1
  * @since 2.1
  */
-@Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.METHOD}) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Transactional
 {
 }
\ No newline at end of file
Index: src/java/javax/jdo/annotations/ForeignKey.java
===================================================================
--- src/java/javax/jdo/annotations/ForeignKey.java	(revision 553258)
+++ src/java/javax/jdo/annotations/ForeignKey.java	(working copy)
@@ -28,30 +28,49 @@
  * @version 2.1
  * @since 2.1
  */
-@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD}) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface ForeignKey
 {
-    /** Name of the foreign-key. */
+    /** Name of the foreign key.
+     * @return the name of the foreign key
+     */
     String name() default "";
 
-    /** Table for the foreign-key. */
+    /** Table for the foreign key. This is needed iff annotating a type where
+     * the foreign key is not defined on the primary table for the type.
+     * @return the table on which the foreign key is defined
+     */
     String table() default "";
 
-    /** Whether this foreign-key is deferred */
+    /** Whether this foreign key is deferred 
+     * (constraint is checked only at commit).
+     * @return whether this foreign key is deferred
+     */
     String deferred() default "";
 
-    /** Whether this foreign-key is unique */
+    /** Whether this foreign key is unique.
+     * @return whether this foreign key is unique
+     */
     String unique() default "";
 
-    /** The delete action of this FK */
+    /** The delete action of this foreign key.
+     * @return the delete action of this foreign key
+     */
     ForeignKeyAction deleteAction() default ForeignKeyAction.RESTRICT;
 
-    /** The update action of this FK */
+    /** The update action of this foreign key.
+     * @return the update action of this foreign key
+     */
     ForeignKeyAction updateAction() default ForeignKeyAction.RESTRICT;
 
-    /** Field names that comprise this index. */
+    /** Field names that comprise this foreign key.
+     * @return the field names that comprise this foreign key
+     */
     String[] fields() default {};
 
-    /** Columns that comprise this index. */
+    /** Columns that comprise this foreign key.
+     * @return the columns that comprise this foreign key
+     */
     Column[] columns() default {};
 }
Index: src/java/javax/jdo/annotations/Transient.java
===================================================================
--- src/java/javax/jdo/annotations/Transient.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Transient.java	(working copy)
@@ -23,12 +23,14 @@
 
 /**
  * Annotation for whether the field is transient (not persisted).
- * This is the same as specifying @Field(persistenceModifier=FieldPersistenceModifier.NONE).
+ * This is the same as specifying 
+ * @Field(persistenceModifier=FieldPersistenceModifier.NONE).
  * 
  * @version 2.1
  * @since 2.1
  */
-@Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.METHOD}) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Transient
 {
 }
\ No newline at end of file
Index: src/java/javax/jdo/annotations/Discriminator.java
===================================================================
--- src/java/javax/jdo/annotations/Discriminator.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Discriminator.java	(working copy)
@@ -35,14 +35,14 @@
     /**
      * Strategy to use for discriminator. The discriminator determines
      * the class associated with a row in the datastore.
-     * @return Strategy to use for discriminator.
+     * @return Strategy to use for discriminator
      */
     DiscriminatorStrategy strategy() 
         default DiscriminatorStrategy.UNKNOWN;
 
     /**
      * Whether the discriminator is indexed.
-     * @return Whether the discriminator is indexed.
+     * @return Whether the discriminator is indexed
      */
     String indexed() default "";
 
@@ -56,13 +56,13 @@
      * The value for the discriminator for objects of this class 
      * when using "value-map" strategy.
      * @return The value for the discriminator for objects of this class 
-     * when using "value-map" strategy.
+     * when using "value-map" strategy
      */
     String value() default "";
 
     /**
      * The column(s) making up the discriminator.
-     * @return The column(s) making up the discriminator.
+     * @return The column(s) making up the discriminator
      */
     Column[] columns() default {};
 }
Index: src/java/javax/jdo/annotations/Index.java
===================================================================
--- src/java/javax/jdo/annotations/Index.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Index.java	(working copy)
@@ -28,21 +28,30 @@
  * @version 2.1
  * @since 2.1
  */
-@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD}) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Index
 {
-    /** Name of the index */
+    /** Name of the index
+     * @return the name of the index
+     */
     String name() default "";
 
-    /** Table for the index (if required). */
+    /** Table for the index. This is needed iff annotating a type where
+     * the index is not defined on the primary table for the type.
+     * @return the table on which the index is defined
+     */
     String table() default "";
 
-    /** Whether this index is unique */
+    /** Whether this index is unique 
+     */
     String unique() default "";
 
-    /** Field names that comprise this index. */
+    /** Field names that comprise this index. 
+     */
     String[] fields() default {};
 
-    /** Columns that comprise this index. */
+    /** Columns that comprise this index. 
+     */
     Column[] columns() default {};
 }
Index: src/java/javax/jdo/annotations/Order.java
===================================================================
--- src/java/javax/jdo/annotations/Order.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Order.java	(working copy)
@@ -28,15 +28,24 @@
  * @version 2.1
  * @since 2.1
  */
-@Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.METHOD}) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Order
 {
-    /** The name of the column to use for the ordering column (1-N relations). */
+    /** The name of the column to use for the ordering column (1-N and M-N
+     * relations).
+     * @return the name of the ordering column
+     */
     String column() default "";
 
-    /** Name of a field in the target object that acts as the ordering for this Collection/List. */
+    /** Name of a field or property in the target class that acts as the 
+     * ordering field or property for this Collection/List.
+     * Return the name of the field or property in the target class
+     */
     String mappedBy() default "";
 
-    /** The definition of the column(s) to use for ordering. */
+    /** The definition of the column(s) to use for ordering.
+     * @return the columns to use for ordering
+     */
     Column[] columns() default {};
 }
\ No newline at end of file
Index: src/java/javax/jdo/annotations/Value.java
===================================================================
--- src/java/javax/jdo/annotations/Value.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Value.java	(working copy)
@@ -28,85 +28,91 @@
  * @version 2.1
  * @since 2.1
  */
-@Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.METHOD}) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Value
 {
     /**
-     * The type of the value. This can be determined if using JDK1.5 generics but is required otherwise.
+     * The type of the value. This can be determined if using JDK1.5 generics
+     * but is required otherwise.
      * @return The type of the value.
      */
     Class type() default void.class;
 
     /**
-     * Types of the values. This is used as an alternative to "type" when the implementation supports
-     * specification of multiple value types. If "type" is specified then this is ignored.
-     * @return The types of values
+     * Types of the values. This is used as an alternative to "type" when the 
+     * implementation supports specification of multiple value types. 
+     * If "type" is specified then this is ignored.
+     * @return the types of values
      */
     Class[] types() default {};
 
     /**
-     * Whether the value is to be stored serialised (into a join table)
+     * Whether the value  is to be stored serialized (into a single column of a
+     * join table).
      * @return Whether the value is to be stored serialised (into a join table)
      */
     String serialized() default "";
 
     /**
-     * Whether the value is to be stored embedded (into a join table)
+     * Whether the value is to be stored embedded (into one or several columns 
+     * of a join table).
      * @return Whether the value is to be stored embedded (into a join table)
      */
     String embedded() default "";
 
     /**
-     * Whether the value is dependent on the owner (and so will be deleted when it is)
-     * @return Whether the value is dependent on the owner (and so will be deleted when it is)
+     * Whether the value is dependent on the owner (and will be deleted 
+     * when the owner is deleted).
+     * @return whether the value is dependent on the owner
      */
     String dependent() default "";
 
     /**
-     * Name of the table for the value
-     * @return Name of the table for the value
+     * Name of the table for the value.
+     * @return the name of the table for the value
      */
     String table() default "";
 
     /**
-     * Name of the column to store the value in
-     * @return Name of the column to store the value in
+     * Name of the column to store the value in.
+     * @return the name of the column to store the value in
      */
     String column() default "";
 
     /**
-     * Delete action to apply to any foreign-key for the value
-     * @return Delete action to apply to any foreign-key for the value
+     * Delete action to apply to any foreign key for the value.
+     * @return delete action to apply to any foreign key for the value
      */
     ForeignKeyAction deleteAction() default ForeignKeyAction.UNKNOWN;
 
     /**
-     * Update action to apply to any foreign-key for the value
-     * @return Update action to apply to any foreign-key for the value
+     * Update action to apply to any foreign key for the value.
+     * @return update action to apply to any foreign key for the value
      */
     ForeignKeyAction updateAction() default ForeignKeyAction.UNKNOWN;
 
     /**
      * Whether the value column(s) should be indexed.
-     * @return Whether the value column(s) should be indexed.
+     * @return whether the value column(s) should be indexed.
      */
     String indexed() default "";
 
     /**
      * Whether the element column(s) contents should be considered unique
-     * @return Whether the element column(s) contents should be considered unique
+     * @return whether the element column(s) contents should be considered unique
      */
     String unique() default "";
 
     /**
      * Name of a field in the key class where this value is stored.
-     * @return Name of a field in the key class where this value is stored
+     * @return the name of a field in the key class where this value is stored
      */
     String mappedBy() default "";
 
     /**
-     * The column(s) for the value
-     * @return The column(s) for the value
+     * The column(s) for the value.
+     * @return the column(s) for the value
      */
     Column[] columns() default {};
 }
\ No newline at end of file
Index: src/java/javax/jdo/annotations/Queries.java
===================================================================
--- src/java/javax/jdo/annotations/Queries.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Queries.java	(working copy)
@@ -27,7 +27,8 @@
  * @version 2.1
  * @since 2.1
  */
-@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Queries
 {
     /**
Index: src/java/javax/jdo/annotations/Indices.java
===================================================================
--- src/java/javax/jdo/annotations/Indices.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Indices.java	(working copy)
@@ -27,7 +27,8 @@
  * @version 2.1
  * @since 2.1
  */
-@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Indices
 {
     /**
Index: src/java/javax/jdo/annotations/Key.java
===================================================================
--- src/java/javax/jdo/annotations/Key.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Key.java	(working copy)
@@ -29,85 +29,91 @@
  * @version 2.1
  * @since 2.1
  */
-@Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.METHOD}) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Key
 {
     /**
-     * The type of the key. This can be determined if using JDK1.5 generics but is required otherwise.
-     * @return The type of the key.
+     * The type of the key. This can be determined if using JDK1.5 generics
+     * but is required otherwise.
+     * @return the type of the key
      */
     Class type() default void.class;
 
     /**
-     * Types of the keys. This is used as an alternative to "type" when the implementation supports
-     * specification of multiple key types. If "type" is specified then this is ignored.
-     * @return The types of keys
+     * Types of the keys. This is used as an alternative to "type" when the 
+     * implementation supports specification of multiple key types. 
+     * If "type" is specified then this is ignored.
+     * @return the types of keys
      */
     Class[] types() default {};
 
     /**
-     * Whether the key is to be stored serialised (into a join table)
-     * @return Whether the key is to be stored serialised (into a join table)
+     * Whether the key is to be stored serialized (into a single column of a
+     * join table).
+     * @return whether the key is to be stored serialized
      */
     String serialized() default "";
 
     /**
-     * Whether the key is to be stored embedded (into a join table)
-     * @return Whether the key is to be stored embedded (into a join table)
+     * Whether the key is to be stored embedded (into one or several columns 
+     * of a join table).
+     * @return whether the key is to be stored embedded (into a join table)
      */
     String embedded() default "";
 
     /**
-     * Whether the key is dependent on the owner (and so will be deleted when it is)
-     * @return Whether the key is dependent on the owner (and so will be deleted when it is)
+     * Whether the key is dependent on the owner (and will be deleted 
+     * when the owner is deleted).
+     * @return whether the key is dependent on the owner
      */
     String dependent() default "";
 
     /**
-     * Name of the table for the key
-     * @return Name of the table for the key
+     * Name of the table for the key.
+     * @return name of the table for the key
      */
     String table() default "";
 
     /**
-     * Name of the column to store the key in
-     * @return Name of the column to store the key in
+     * Name of the column to store the key in.
+     * @return name of the column to store the key in
      */
     String column() default "";
 
     /**
-     * Delete action to apply to any foreign-key for the key
-     * @return Delete action to apply to any foreign-key for the key
+     * Delete action to apply to the foreign key for the key.
+     * @return delete action to apply to the foreign key for the key
      */
     ForeignKeyAction deleteAction() default ForeignKeyAction.UNKNOWN;
 
     /**
-     * Update action to apply to any foreign-key for the key
-     * @return Update action to apply to any foreign-key for the key
+     * Update action to apply to the foreign key for the key.
+     * @return update action to apply to the foreign key for the key
      */
     ForeignKeyAction updateAction() default ForeignKeyAction.UNKNOWN;
 
     /**
      * Whether the key column(s) should be indexed.
-     * @return Whether the key column(s) should be indexed.
+     * @return whether the key column(s) should be indexed.
      */
     String indexed() default "";
 
     /**
      * Whether the key column(s) contents should be considered unique
-     * @return Whether the key column(s) contents should be considered unique
+     * @return whether the key column(s) contents should be considered unique
      */
     String unique() default "";
 
     /**
      * Name of a field in the value class where this key value is stored.
-     * @return Name of a field in the value where this key is stored
+     * @return the name of a field in the value where this key is stored
      */
     String mappedBy() default "";
 
     /**
      * The column(s) for the key
-     * @return The column(s) for the key
+     * @return the column(s) for the key
      */
     Column[] columns() default {};
 }
\ No newline at end of file
Index: src/java/javax/jdo/annotations/Inheritance.java
===================================================================
--- src/java/javax/jdo/annotations/Inheritance.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Inheritance.java	(working copy)
@@ -28,9 +28,13 @@
  * @version 2.1
  * @since 2.1
  */
-@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Inheritance
 {
-    /** Strategy to use for inheritance. Relates to where the data for the class is stored. */
+    /** Strategy to use for inheritance. Specifies where the data for
+     * the class is stored.
+     * @return the inheritance strategy
+     */
     InheritanceStrategy strategy();
 }
Index: src/java/javax/jdo/annotations/Element.java
===================================================================
--- src/java/javax/jdo/annotations/Element.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Element.java	(working copy)
@@ -44,78 +44,78 @@
      * Types of the elements. This is used as an alternative to "type" when 
      * the implementation supports specification of multiple element types. 
      * If "type" is specified then this is ignored.
-     * @return The types of elements
+     * @return the types of elements
      */
     Class[] types() default {};
 
     /**
-     * Whether the element is to be stored serialised (into a join table)
-     * @return Whether the element is to be stored serialised 
+     * Whether the element is to be stored serialized (into a join table)
+     * @return whether the element is to be stored serialized 
      * (into a join table)
      */
     String serialized() default "";
 
     /**
-     * Whether the element is to be stored embedded (into a join table)
-     * @return Whether the element is to be stored embedded (into a join table)
+     * Whether the element is to be stored embedded (into a join table).
+     * @return whether the element is to be stored embedded (into a join table)
      */
     String embedded() default "";
 
     /**
      * Whether the element is dependent on the owner, and will be deleted 
-     * when the owner is deleted
-     * @return Whether the element is dependent on the owner, and will be 
+     * when the owner is deleted.
+     * @return whether the element is dependent on the owner, and will be 
      * deleted when the owner is deleted
      */
     String dependent() default "";
 
     /**
-     * Name of the table for the element
-     * @return Name of the table for the element
+     * Name of the table for the element.
+     * @return name of the table for the element
      */
     String table() default "";
 
     /**
-     * Name of the column to store the element in
-     * @return Name of the column to store the element in
+     * Name of the column to store the element in.
+     * @return name of the column to store the element in
      */
     String column() default "";
 
     /**
-     * Delete action to apply to any foreign-key for the element
-     * @return Delete action to apply to any foreign-key for the element
+     * Delete action to apply to any foreign-key for the element.
+     * @return delete action to apply to any foreign-key for the element
      */
     ForeignKeyAction deleteAction() default ForeignKeyAction.UNKNOWN;
 
     /**
      * Update action to apply to any foreign-key for the element
-     * @return Update action to apply to any foreign-key for the element
+     * @return update action to apply to any foreign-key for the element
      */
     ForeignKeyAction updateAction() default ForeignKeyAction.UNKNOWN;
 
     /**
      * Whether the element column(s) should be indexed.
-     * @return Whether the element column(s) should be indexed.
+     * @return whether the element column(s) should be indexed.
      */
     String indexed() default "";
 
     /**
-     * Whether the element column(s) contents are unique
-     * @return Whether the element column(s) contents are unique
+     * Whether the element column(s) contents are unique.
+     * @return whether the element column(s) contents are unique
      */
     String unique() default "";
 
     /**
      * Name of the field in the target class that forms a bidirectional 
      * relationship with this field. 
-     * @return Name of the field in the target class that forms a bidirectional 
+     * @return name of the field in the target class that forms a bidirectional 
      * relationship with this field
      */
     String mappedBy() default "";
 
     /**
      * The column(s) for the element.
-     * @return The column(s) for the element.
+     * @return the column(s) for the element
      */
     Column[] columns() default {};
 }
\ No newline at end of file
Index: src/java/javax/jdo/annotations/Uniques.java
===================================================================
--- src/java/javax/jdo/annotations/Uniques.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Uniques.java	(working copy)
@@ -27,12 +27,13 @@
  * @version 2.1
  * @since 2.1
  */
-@Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface Uniques
 {
     /**
-     * The (unique) candidate keys
-     * @return The (unique) candidate keys
+     * The unique constraints.
+     * @return The unique constraints
      */
     Unique[] value();
 }
\ No newline at end of file
Index: src/java/javax/jdo/annotations/PrimaryKey.java
===================================================================
--- src/java/javax/jdo/annotations/PrimaryKey.java	(revision 553258)
+++ src/java/javax/jdo/annotations/PrimaryKey.java	(working copy)
@@ -29,24 +29,25 @@
  * @version 2.1
  * @since 2.1
  */
-@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD}) 
+@Retention(RetentionPolicy.RUNTIME)
 public @interface PrimaryKey
 {
     /**
      * Name of the primary key constraint
-     * @return Name of the primary key constraint
+     * @return the name of the primary key constraint
      */
     String name() default "";
 
     /**
      * Name of the column to use for the primary key
-     * @return Name of the column to use for the primary key
+     * @return the name of the column to use for the primary key
      */
     String column() default "";
 
     /**
      * The column(s) for the primary key
-     * @return The column(s) for the primary key
+     * @return the column(s) for the primary key
      */
     Column[] columns() default {};
 }
\ No newline at end of file
Index: src/java/javax/jdo/annotations/Column.java
===================================================================
--- src/java/javax/jdo/annotations/Column.java	(revision 553258)
+++ src/java/javax/jdo/annotations/Column.java	(working copy)
@@ -34,61 +34,65 @@
 {
     /**
      * Name of the column.
-     * @return Name of the column
+     * @return the name of the column
      */
     String name() default "";
 
     /**
-     * Target column for this column when part of a foreign key relation.
-     * @return Target column for this column when part of a foreign key relation.
+     * Target column for this column in the other table when part of a 
+     * foreign key relation.
+     * @return the target column in the other table for this column 
+     * when part of a foreign key relation.
      */
     String target() default "";
 
     /**
-     * Target field for this column when part of a bidirectional relation.
-     * @return Target field for this column when part of a bidirectional relation.
+     * Target field in the other class or interface for this column 
+     * when part of a bidirectional relation.
+     * @return the target field for this column when part of 
+     * a bidirectional relation.
      */
     String targetField() default "";
 
     /**
-     * JDBC Type for this column
-     * @return JDBC Type for this column
+     * JDBC Type for this column.
+     * @return JDBC type for this column
      */
     String jdbcType() default "";
 
     /**
-     * SQL Type for this column
-     * @return SQL Type for this column
+     * SQL Type for this column.
+     * @return SQL type for this column
      */
     String sqlType() default "";
 
     /**
-     * Maximum length of data stored in this column
-     * @return Maximum length of data stored in this column
+     * Maximum length of data stored in this column.
+     * @return the maximum length of data stored in this column
      */
     int length() default -1;
 
     /**
      * Scale for the column when handling floating point values
-     * @return Scale for the column when handling floating point values
+     * @return the scale for the column when handling floating point values
      */
     int scale() default -1;
 
     /**
      * Whether the column allows nulls to be inserted.
-     * @return Whether the column allows nulls to be inserted.
+     * @return whether the column allows nulls to be inserted
      */
     String allowsNull() default "";
 
     /**
-     * Default value for this column
-     * @return Default value for this column
+     * Default value for this column.
+     * @return the default value for this column
      */
     String defaultValue() default "";
 
     /**
      * Value to be inserted when this is an "unmapped" column
-     * @return Value to be inserted when this is an "unmapped" column
+     * @return the value to be inserted when this is an "unmapped" column
      */
     String insertValue() default "";
 }
\ No newline at end of file