src/javax/persistence/Cacheable.java

@@ -39,6 +39,7 @@ public @interface Cacheable {
 
     /**
      * (Optional) Whether or not the entity should be cached.
+     * @return boolean
      */
     boolean value() default true;
 }

src/javax/persistence/Column.java

@@ -1,4 +1,4 @@
-/*******************************************************************************
+/** *****************************************************************************
  * Copyright (c) 2008 - 2013 Oracle Corporation. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
@@ -12,7 +12,7 @@
  *     Linda DeMichiel - Java Persistence 2.1
  *     Linda DeMichiel - Java Persistence 2.0
  *
- ******************************************************************************/ 
+ ***************************************************************************** */
 package javax.persistence;
 
 import java.lang.annotation.Target;
@@ -48,75 +48,96 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *
  *
  * @since Java Persistence 1.0
- */ 
-@Target({METHOD, FIELD}) 
+ */
+@Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface Column {
 
     /**
-     * (Optional) The name of the column. Defaults to 
+     * (Optional) The name of the column. Defaults to
      * the property or field name.
+     *
+     * @return String
      */
     String name() default "";
 
     /**
-     * (Optional) Whether the column is a unique key.  This is a 
-     * shortcut for the <code>UniqueConstraint</code> annotation at the table 
-     * level and is useful for when the unique key constraint 
-     * corresponds to only a single column. This constraint applies 
-     * in addition to any constraint entailed by primary key mapping and 
+     * (Optional) Whether the column is a unique key. This is a
+     * shortcut for the <code>UniqueConstraint</code> annotation at the table
+     * level and is useful for when the unique key constraint
+     * corresponds to only a single column. This constraint applies
+     * in addition to any constraint entailed by primary key mapping and
      * to constraints specified at the table level.
+     *
+     * @return boolean
      */
     boolean unique() default false;
 
     /**
      * (Optional) Whether the database column is nullable.
+     *
+     * @return boolean
      */
     boolean nullable() default true;
 
     /**
-     * (Optional) Whether the column is included in SQL INSERT 
+     * (Optional) Whether the column is included in SQL INSERT
      * statements generated by the persistence provider.
+     *
+     * @return boolean
      */
     boolean insertable() default true;
 
     /**
-     * (Optional) Whether the column is included in SQL UPDATE 
+     * (Optional) Whether the column is included in SQL UPDATE
      * statements generated by the persistence provider.
+     *
+     * @return boolean
      */
     boolean updatable() default true;
 
     /**
-     * (Optional) The SQL fragment that is used when 
+     * (Optional) The SQL fragment that is used when
      * generating the DDL for the column.
-     * <p> Defaults to the generated SQL to create a
+     * <p>
+     * Defaults to the generated SQL to create a
      * column of the inferred type.
+     *
+     * @return String
      */
     String columnDefinition() default "";
 
     /**
-     * (Optional) The name of the table that contains the column. 
+     * (Optional) The name of the table that contains the column.
      * If absent the column is assumed to be in the primary table.
+     *
+     * @return String
      */
     String table() default "";
 
     /**
      * (Optional) The column length. (Applies only if a
      * string-valued column is used.)
+     *
+     * @return int
      */
     int length() default 255;
 
     /**
-     * (Optional) The precision for a decimal (exact numeric) 
+     * (Optional) The precision for a decimal (exact numeric)
      * column. (Applies only if a decimal column is used.)
-     * Value must be set by developer if used when generating 
+     * Value must be set by developer if used when generating
      * the DDL for the column.
+     *
+     * @return int
      */
     int precision() default 0;
 
     /**
-     * (Optional) The scale for a decimal (exact numeric) column. 
+     * (Optional) The scale for a decimal (exact numeric) column.
      * (Applies only if a decimal column is used.)
+     *
+     * @return int
      */
     int scale() default 0;
 }

src/javax/persistence/Entity.java

@@ -37,6 +37,7 @@ public @interface Entity {
 	 * name of the entity class. This name is used to refer to the
 	 * entity in queries. The name must not be a reserved literal
 	 * in the Java Persistence query language.
+     * @return String
 	 */
 	String name() default "";
 }

src/javax/persistence/GeneratedValue.java

@@ -51,8 +51,6 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * </pre>
  *
  * @see Id
- * @see TableGenerator
- * @see SequenceGenerator
  *
  * @since Java Persistence 1.0
  */
@@ -64,15 +62,17 @@ public @interface GeneratedValue {
      * (Optional) The primary key generation strategy
      * that the persistence provider must use to
      * generate the annotated entity primary key.
+     * @return GenerationType
      */
     @Deprecated
     GenerationType strategy() default GenerationType.AUTO;
 
     /**
      * (Optional) The name of the primary key generator
-     * to use as specified in the {@link SequenceGenerator} 
-     * or {@link TableGenerator} annotation.
+     * to use as specified in the SequenceGenerator
+     * or TableGenerator annotation.
      * <p> Defaults to the id generator supplied by persistence provider.
+     * @return  String
      */
     @Deprecated
     String generator() default "";

src/javax/persistence/Table.java

@@ -22,8 +22,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
  * Specifies the primary table for the annotated entity. Additional
- * tables may be specified using {@link SecondaryTable} or {@link
- * SecondaryTables} annotation.
+ * tables may be specified using  SecondaryTable or  SecondaryTables annotation.
  *
  * <p> If no <code>Table</code> annotation is specified for an entity 
  * class, the default values apply.
@@ -45,16 +44,19 @@ public @interface Table {
     /**
      * (Optional) The name of the table.
      * <p> Defaults to the entity name.
+     * @return String
      */
     String name() default "";
 
     /** (Optional) The catalog of the table.
      * <p> Defaults to the default catalog.
+     * @return String
      */
     String catalog() default "";
 
     /** (Optional) The schema of the table.
      * <p> Defaults to the default schema for user.
+     * @return String
      */
     String schema() default "";