HHH-8159 - Apply fixups indicated by analysis tools

build.gradle

@@ -308,6 +308,24 @@ subprojects { subProject ->
 	// eclipseClasspath will not add sources to classpath unless the dirs actually exist.
 	eclipseClasspath.dependsOn("generateSources")
 
+        // specialized API/SPI checkstyle tasks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+        task checkstylePublicSources(type: Checkstyle) {
+            checkstyleClasspath = checkstyleMain.checkstyleClasspath
+            classpath = checkstyleMain.classpath
+            configFile = rootProject.file( 'shared/config/checkstyle/public_checks.xml' )
+            source subProject.sourceSets.main.originalJavaSrcDirs
+            exclude '**/internal/**'
+            exclude '**/internal/*'
+            ignoreFailures = false
+            showViolations = true
+            reports {
+                xml {
+                    destination "$buildDir/reports/checkstyle/public.xml"
+                }
+            }
+        }
+        // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
         // Report configs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         checkstyle {
             configFile = rootProject.file( 'shared/config/checkstyle/checkstyle.xml' )

hibernate-core/src/main/java/org/hibernate/ScrollMode.java

@@ -40,14 +40,14 @@ public enum ScrollMode {
 	FORWARD_ONLY( ResultSet.TYPE_FORWARD_ONLY ),
 
 	/**
-	 * Requests a scrollable result which is sensitive to changes in the underlying data
+	 * Requests a scrollable result which is sensitive to changes in the underlying data.
 	 *
 	 * @see java.sql.ResultSet#TYPE_SCROLL_SENSITIVE
 	 */
 	SCROLL_SENSITIVE( ResultSet.TYPE_SCROLL_SENSITIVE ),
 
 	/**
-	 * Requests a scrollable result which is insensitive to changes in the underlying data
+	 * Requests a scrollable result which is insensitive to changes in the underlying data.
 	 *
 	 * Note that since the Hibernate session acts as a cache, you
 	 * might need to explicitly evict objects, if you need to see

hibernate-core/src/main/java/org/hibernate/StaleObjectStateException.java

@@ -38,7 +38,7 @@ public class StaleObjectStateException extends StaleStateException {
 	private final Serializable identifier;
 
 	/**
-	 * Constructs a StaleObjectStateException using the supplied information
+	 * Constructs a StaleObjectStateException using the supplied information.
 	 *
 	 * @param entityName The name of the entity
 	 * @param identifier The identifier of the entity

hibernate-core/src/main/java/org/hibernate/action/spi/Executable.java

@@ -28,9 +28,8 @@ import java.io.Serializable;
 import org.hibernate.HibernateException;
 
 /**
- * An operation which may be scheduled for later execution.
+ * An operation which may be scheduled for later execution.  Usually, the operation is a database
- * Usually, the operation is a database insert/update/delete,
+ * insert/update/delete, together with required second-level cache management.
- * together with required second-level cache management.
  * 
  * @author Gavin King
  * @author Steve Ebersole
@@ -51,7 +50,7 @@ public interface Executable {
 	public void beforeExecutions() throws HibernateException;
 
 	/**
-	 * Execute this action
+	 * Execute this action.
 	 *
 	 * @throws HibernateException Indicates a problem during execution.
 	 */

hibernate-core/src/main/java/org/hibernate/action/spi/package-info.java

@@ -0,0 +1,5 @@
+/**
+ * Defines SPI hooks into the {@link org.hibernate.engine.spi.ActionQueue}.  Mainly for registering custom
+ * {@link AfterTransactionCompletionProcess} and {@link BeforeTransactionCompletionProcess} hooks.
+ */
+package org.hibernate.action.spi;

hibernate-core/src/main/java/org/hibernate/annotations/AccessType.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -31,9 +32,8 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Property Access type
+ * Property Access type.  Prefer the standard {@link javax.persistence.Access} annotation; however,
- *
+ * {@code @Access} is limited to field/property access definitions.
- * Prefer the standard {@link javax.persistence.Access} annotation
  *
  * @author Emmanuel Bernard
  *
@@ -44,5 +44,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 @Deprecated
 public @interface AccessType {
+	/**
+	 * The access strategy name.
+	 */
 	String value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/AnyMetaDef.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 
 import static java.lang.annotation.ElementType.FIELD;
@@ -42,8 +43,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention( RUNTIME )
 public @interface AnyMetaDef {
 	/**
-	 * If defined, assign a global meta definition name to be used in an @Any or @ManyToAny annotation
+	 * If defined, assign a global meta definition name to be used in an @Any or @ManyToAny annotation.  If
-	 * If not defined, the metadata applies to the current property or field
+	 * not defined, the metadata applies to the current property or field.
 	 */
 	String name() default "";
 

hibernate-core/src/main/java/org/hibernate/annotations/AnyMetaDefs.java

@@ -38,5 +38,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @java.lang.annotation.Target( { PACKAGE, TYPE } )
 @Retention( RUNTIME )
 public @interface AnyMetaDefs {
+	/**
+	 * The collective set of any meta-defs.
+	 */
 	AnyMetaDef[] value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/AttributeAccessor.java

@@ -55,7 +55,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface AttributeAccessor {
 	/**
-	 * Names the {@link org.hibernate.property.PropertyAccessor} strategy
+	 * Names the {@link org.hibernate.property.PropertyAccessor} strategy.
 	 */
 	String value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/BatchSize.java

@@ -56,7 +56,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface BatchSize {
 	/**
-	 * Strictly positive integer
+	 * Strictly positive integer.
 	 */
 	int size();
 }

hibernate-core/src/main/java/org/hibernate/annotations/Cache.java

@@ -31,20 +31,26 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Add caching strategy to a root entity or a collection
+ * Add caching strategy to a root entity or a collection.
  *
  * @author Emmanuel Bernard
  */
 @Target({TYPE, METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface Cache {
-	/** concurrency strategy chosen */
-	CacheConcurrencyStrategy usage();
-	/** cache region name */
-	String region() default "";
 	/**
-	 * whether or not lazy-properties are included in the second level cache
+	 * The concurrency strategy chosen.
-	 * default all, other value: non-lazy
+	 */
+	CacheConcurrencyStrategy usage();
+
+	/**
+	 * The cache region name.
+	 */
+	String region() default "";
+
+	/**
+	 * How lazy properties are included in the second level cache. Default value is "all"; other allowable
+	 * value: "non-lazy"
 	 */
 	String include() default "all";
 }

hibernate-core/src/main/java/org/hibernate/annotations/CacheConcurrencyStrategy.java

@@ -26,15 +26,38 @@ package org.hibernate.annotations;
 import org.hibernate.cache.spi.access.AccessType;
 
 /**
- * Cache concurrency strategy
+ * Cache concurrency strategy.
  *
  * @author Emmanuel Bernard
  */
 public enum CacheConcurrencyStrategy {
+	/**
+	 * Indicates no concurrency strategy should be applied.
+	 */
 	NONE( null ),
+	/**
+	 * Indicates that read-only strategy should be applied.
+	 *
+	 * @see AccessType#READ_ONLY
+	 */
 	READ_ONLY( AccessType.READ_ONLY ),
+	/**
+	 * Indicates that the non-strict read-write strategy should be applied.
+	 *
+	 * @see AccessType#NONSTRICT_READ_WRITE
+	 */
 	NONSTRICT_READ_WRITE( AccessType.NONSTRICT_READ_WRITE ),
+	/**
+	 * Indicates that the read-write strategy should be applied.
+	 *
+	 * @see AccessType#READ_WRITE
+	 */
 	READ_WRITE( AccessType.READ_WRITE ),
+	/**
+	 * Indicates that the transaction strategy should be applied.
+	 *
+	 * @see AccessType#TRANSACTIONAL
+	 */
 	TRANSACTIONAL( AccessType.TRANSACTIONAL );
 
 	private final AccessType accessType;
@@ -43,13 +66,26 @@ public enum CacheConcurrencyStrategy {
 		this.accessType = accessType;
 	}
 
-	private boolean isMatch(String name) {
+	/**
-		return ( accessType != null && accessType.getExternalName().equalsIgnoreCase( name ) )
+	 * Get the AccessType corresponding to this concurrency strategy.
-				|| name().equalsIgnoreCase( name );
+	 *
+	 * @return The corresponding concurrency strategy.  Note that this will return {@code null} for
+	 * {@link #NONE}
+	 */
+	public AccessType toAccessType() {
+		return accessType;
 	}
 
+	/**
+	 * Conversion from {@link AccessType} to {@link CacheConcurrencyStrategy}.
+	 *
+	 * @param accessType The access type to convert
+	 *
+	 * @return The corresponding enum value.  {@link #NONE} is returned by default if unable to
+	 * recognize {@code accessType} or if {@code accessType} is {@code null}.
+	 */
 	public static CacheConcurrencyStrategy fromAccessType(AccessType accessType) {
-		if (null == accessType) {
+		if ( null == accessType ) {
 			return NONE;
 		}
 		
@@ -72,6 +108,13 @@ public enum CacheConcurrencyStrategy {
 		}
 	}
 
+	/**
+	 * Parse an external representation of a CacheConcurrencyStrategy value.
+	 *
+	 * @param name The external representation
+	 *
+	 * @return The corresponding enum value, or {@code null} if not match was found.
+	 */
 	public static CacheConcurrencyStrategy parse(String name) {
 		if ( READ_ONLY.isMatch( name ) ) {
 			return READ_ONLY;
@@ -93,7 +136,8 @@ public enum CacheConcurrencyStrategy {
 		}
 	}
 
-	public AccessType toAccessType() {
+	private boolean isMatch(String name) {
-		return accessType;
+		return ( accessType != null && accessType.getExternalName().equalsIgnoreCase( name ) )
+				|| name().equalsIgnoreCase( name );
 	}
 }

hibernate-core/src/main/java/org/hibernate/annotations/CacheModeType.java

@@ -23,6 +23,7 @@
  */
 package org.hibernate.annotations;
 
+import org.hibernate.CacheMode;
 
 /**
  * Enumeration for the different interaction modes between the session and
@@ -31,11 +32,83 @@ package org.hibernate.annotations;
  * @author Emmanuel Bernard
  * @author Carlos Gonzalez-Cadenas
  */
-
 public enum CacheModeType {
-	GET,
+	/**
-	IGNORE,
+	 * Corresponds to {@link CacheMode#GET}.
-	NORMAL,
+	 *
-	PUT,
+	 * @see CacheMode#GET
-	REFRESH
+	 */
+	GET( CacheMode.GET ),
+
+	/**
+	 * Corresponds to {@link CacheMode#IGNORE}.
+	 *
+	 * @see CacheMode#IGNORE
+	 */
+	IGNORE( CacheMode.IGNORE ),
+
+	/**
+	 * Corresponds to {@link CacheMode#NORMAL}.
+	 *
+	 * @see CacheMode#NORMAL
+	 */
+	NORMAL( CacheMode.NORMAL ),
+
+	/**
+	 * Corresponds to {@link CacheMode#PUT}.
+	 *
+	 * @see CacheMode#PUT
+	 */
+	PUT( CacheMode.PUT ),
+
+	/**
+	 * Corresponds to {@link CacheMode#REFRESH}.
+	 *
+	 * @see CacheMode#REFRESH
+	 */
+	REFRESH( CacheMode.REFRESH );
+
+	private final CacheMode cacheMode;
+
+	private CacheModeType(CacheMode cacheMode) {
+		this.cacheMode = cacheMode;
+	}
+
+	public CacheMode getCacheMode() {
+		return cacheMode;
+	}
+
+	/**
+	 * Conversion from {@link CacheMode} to {@link CacheModeType}.
+	 *
+	 * @param cacheMode The cache mode to convert
+	 *
+	 * @return The corresponding enum value.  Will be {@code null} if the given {@code accessType} is {@code null}.
+	 */
+	public static CacheModeType fromCacheMode(CacheMode cacheMode) {
+		if ( null == cacheMode ) {
+			return null;
+		}
+
+		switch ( cacheMode ) {
+			case NORMAL: {
+				return NORMAL;
+			}
+			case GET: {
+				return GET;
+			}
+			case PUT: {
+				return PUT;
+			}
+			case REFRESH: {
+				return REFRESH;
+			}
+			case IGNORE: {
+				return IGNORE;
+			}
+			default: {
+				throw new IllegalArgumentException( "Unrecognized CacheMode : " + cacheMode );
+			}
+		}
+	}
 }

hibernate-core/src/main/java/org/hibernate/annotations/Cascade.java

@@ -40,5 +40,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface Cascade {
+	/**
+	 * The cascade value.
+	 */
 	CascadeType[] value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/CascadeType.java

@@ -23,25 +23,62 @@
  */
 package org.hibernate.annotations;
 
-
 /**
- * Cascade types (can override default JPA cascades
+ * Cascade types (can override default JPA cascades).
  */
 public enum CascadeType {
+	/**
+	 * Includes all types listed here.
+	 */
 	ALL,
+	/**
+	 * Corresponds to {@link javax.persistence.CascadeType#PERSIST}.
+	 */
 	PERSIST,
+	/**
+	 * Corresponds to {@link javax.persistence.CascadeType#MERGE}.
+	 */
 	MERGE,
+	/**
+	 * Corresponds to {@link javax.persistence.CascadeType#REMOVE}.
+	 */
 	REMOVE,
+	/**
+	 * Corresponds to {@link javax.persistence.CascadeType#REFRESH}.
+	 */
 	REFRESH,
+	/**
+	 * Corresponds to the Hibernate native DELETE action.
+	 */
 	DELETE,
+	/**
+	 * Corresponds to the Hibernate native SAVE_UPDATE (direct reattachment) action.
+	 */
 	SAVE_UPDATE,
+	/**
+	 * Corresponds to the Hibernate native REPLICATE action.
+	 */
 	REPLICATE,
-	/** @deprecated use @OneToOne(orphanRemoval=true) or @OneToMany(orphanRemoval=true) */
+	/**
+	 * Hibernate originally handled orphan removal as a specialized cascade.
+	 *
+	 * @deprecated use @OneToOne(orphanRemoval=true) or @OneToMany(orphanRemoval=true)
+	 */
 	@Deprecated
 	DELETE_ORPHAN,
+	/**
+	 * Corresponds to the Hibernate native LOCK action.
+	 */
 	LOCK,
-	/** @deprecated use javax.persistence.CascadeType.DETACH */
+	/**
+	 * JPA originally planned on calling DETACH EVICT.
+	 *
+	 * @deprecated use javax.persistence.CascadeType.DETACH
+	 */
 	@Deprecated
 	EVICT,
+	/**
+	 * Corresponds to {@link javax.persistence.CascadeType#REFRESH}.
+	 */
 	DETACH
 }

hibernate-core/src/main/java/org/hibernate/annotations/Check.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -31,12 +32,15 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Arbitrary SQL CHECK constraints which can be defined at the class, property or collection level
+ * Arbitrary SQL CHECK constraints which can be defined at the class, property or collection level.
  *
  * @author Emmanuel Bernard
  */
 @Target({TYPE, METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface Check {
+	/**
+	 * The check constraints string.
+	 */
 	String constraints();
 }

hibernate-core/src/main/java/org/hibernate/annotations/CollectionId.java

@@ -31,7 +31,8 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Describe an identifier column for a bag (ie an idbag)
+ * Describe an identifier column for a bag (ie an idbag).
+ *
  * EXPERIMENTAL: the structure of this annotation might slightly change (generator() mix strategy and generator
  * 
  * @author Emmanuel Bernard
@@ -39,10 +40,18 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface CollectionId {
-	/** Collection id column(s) */
+	/**
+	 * Collection id column(s).
+	 */
 	Column[] columns();
-	/** id type, type.type() must be set  */
+
+	/**
+	 * id type, type.type() must be set.
+	 */
 	Type type();
-	/** generator name: 'identity' or a defined generator name */
+
+	/**
+	 * The generator name.  For example 'identity' or a defined generator name
+	 */
 	String generator();
 }

hibernate-core/src/main/java/org/hibernate/annotations/CollectionType.java

@@ -42,11 +42,11 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface CollectionType {
 	/**
-	 * Names the type (either {@link org.hibernate.type.CollectionType} or
+	 * Names the type.
-	 * {@link org.hibernate.usertype.UserCollectionType} implementation class.  Could also name a
-	 * custom type defined via a {@link TypeDef @TypeDef}
 	 *
-	 * @return The implementation class to use.
+	 * Could name the implementation class (an implementation of {@link org.hibernate.type.CollectionType} or
+	 * {@link org.hibernate.usertype.UserCollectionType}).  Could also name a custom type defined via a
+	 * {@link TypeDef @TypeDef}
 	 */
 	String type();
 
@@ -54,8 +54,6 @@ public @interface CollectionType {
 	 * Specifies configuration information for the type.  Note that if the named type is a
 	 * {@link org.hibernate.usertype.UserCollectionType}, it must also implement 
 	 * {@link org.hibernate.usertype.ParameterizedType} in order to receive these values.
-	 *
-	 * @return The configuration parameters.
 	 */
 	Parameter[] parameters() default {};
 }

hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformer.java

@@ -43,20 +43,20 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface ColumnTransformer {
 	/**
-	 * (Logical) column name for which the expression is used
+	 * (Logical) column name for which the expression is used.
 	 *
 	 * This can be left out if the property is bound to a single column
 	 */
 	String forColumn() default "";
 
 	/**
-	 * Custom SQL expression used to read from the column
+	 * Custom SQL expression used to read from the column.
 	 */
 	String read() default "";
 
 	/**
-	 * Custom SQL expression used to write to the column.
+	 * Custom SQL expression used to write to the column. The write expression must contain exactly
-	 * The write expression must contain exactly one '?' placeholder for the value.
+	 * one '?' placeholder for the value.
 	 */
 	String write() default "";
 }

hibernate-core/src/main/java/org/hibernate/annotations/ColumnTransformers.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 
 import static java.lang.annotation.ElementType.FIELD;
@@ -37,5 +38,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @java.lang.annotation.Target({FIELD,METHOD})
 @Retention(RUNTIME)
 public @interface ColumnTransformers {
+	/**
+	 * The aggregated transformers.
+	 */
 	ColumnTransformer[] value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/Columns.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 import javax.persistence.Column;
@@ -38,5 +39,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface Columns {
+	/**
+	 * The aggregated columns.
+	 */
 	Column[] columns();
 }

hibernate-core/src/main/java/org/hibernate/annotations/DiscriminatorFormula.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -42,5 +43,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target({TYPE})
 @Retention(RUNTIME)
 public @interface DiscriminatorFormula {
+	/**
+	 * The formula string.
+	 */
 	String value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/DiscriminatorOptions.java

@@ -38,18 +38,15 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface DiscriminatorOptions {
 	/**
-	 * "Forces" Hibernate to specify the allowed discriminator values, even when retrieving all instances of the root class.
+	 * "Forces" Hibernate to specify the allowed discriminator values, even when retrieving all instances of
-	 *
+	 * the root class.  {@code true} indicates that the discriminator value should be forced; Default is
-	 * @return {@code true} in case the discriminator value should be forces, {@code false} otherwise. Default is {@code false}.
+	 * {@code false}.
 	 */
 	boolean force() default false;
 
 	/**
-	 * Set this to {@code false}, if your discriminator column is also part of a mapped composite identifier.
+	 * Set this to {@code false} if your discriminator column is also part of a mapped composite identifier.
-	 * It tells Hibernate not to include the column in SQL INSERTs.
+	 * It tells Hibernate not to include the column in SQL INSERTs.  Default is {@code true}.
-	 *
-	 * @return {@code true} in case the discriminator value should be included in inserts, {@code false} otherwise.
-	 *         Default is {@code true}.
 	 */
 	boolean insert() default true;
 }

hibernate-core/src/main/java/org/hibernate/annotations/DynamicInsert.java

@@ -38,5 +38,9 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target( TYPE )
 @Retention( RUNTIME )
 public @interface DynamicInsert {
+	/**
+	 * Should dynamic insertion be used for this entity?  {@code true} says dynamic insertion will be used.
+	 * Default is {@code true} (since generally this annotation is not used unless the user wants dynamic insertion).
+	 */
 	boolean value() default true;
 }

hibernate-core/src/main/java/org/hibernate/annotations/DynamicUpdate.java

@@ -42,5 +42,10 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target( TYPE )
 @Retention( RUNTIME )
 public @interface DynamicUpdate {
+	/**
+	 * Should dynamic update generation be used for this entity?  {@code true} says the update sql will be dynamic
+	 * generated.  Default is {@code true} (since generally this annotation is not used unless the user wants dynamic
+	 * generation).
+	 */
 	boolean value() default true;
 }

hibernate-core/src/main/java/org/hibernate/annotations/Entity.java

@@ -30,7 +30,7 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Extends {@link javax.persistence.Entity} with Hibernate features
+ * Extends {@link javax.persistence.Entity} with Hibernate features.
  *
  * @author Emmanuel Bernard
  *
@@ -41,39 +41,46 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Deprecated
 public @interface Entity {
 	/**
-	 * Is this entity mutable (read only) or not
+	 * Is this entity mutable (read only) or not.
 	 *
 	 * @deprecated use {@link org.hibernate.annotations.Immutable} 
 	 */
+	@Deprecated
 	boolean mutable() default true;
 	/**
-	 * Needed column only in SQL on insert
+	 * Needed column only in SQL on insert.
 	 * @deprecated use {@link DynamicInsert} instead
 	 */
+	@Deprecated
 	boolean dynamicInsert() default false;
 	/**
-	 * Needed column only in SQL on update
+	 * Needed column only in SQL on update.
 	 * @deprecated Use {@link DynamicUpdate} instead
 	 */
+	@Deprecated
 	boolean dynamicUpdate() default false;
 	/**
-	 *  Do a select to retrieve the entity before any potential update
+	 *  Do a select to retrieve the entity before any potential update.
 	 *  @deprecated Use {@link SelectBeforeUpdate} instead
 	 */
+	@Deprecated
 	boolean selectBeforeUpdate() default false;
 	/**
-	 * polymorphism strategy for this entity
+	 * polymorphism strategy for this entity.
 	 * @deprecated use {@link Polymorphism} instead
 	 */
+	@Deprecated
 	PolymorphismType polymorphism() default PolymorphismType.IMPLICIT;
 	/**
-	 * optimistic locking strategy
+	 * optimistic locking strategy.
 	 * @deprecated use {@link OptimisticLocking} instead.
 	 */
+	@Deprecated
 	OptimisticLockType optimisticLock() default OptimisticLockType.VERSION;
 	/**
-	 * persister of this entity, default is hibernate internal one
+	 * persister of this entity, default is hibernate internal one.
 	 * @deprecated  use {@link Persister} instead
 	 */
+	@Deprecated
 	String persister() default "";
 }

hibernate-core/src/main/java/org/hibernate/annotations/Fetch.java

@@ -22,18 +22,22 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Define the fetching strategy used for the given association
+ * Define the fetching strategy used for the given association.
  *
  * @author Emmanuel Bernard
  */
 @Target({ElementType.METHOD, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Fetch {
+	/**
+	 * The style of fetch to use.
+	 */
 	FetchMode value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/FetchMode.java

@@ -23,23 +23,23 @@
  */
 package org.hibernate.annotations;
 
-
 /**
- * Fetch options on associations
+ * Fetch options on associations.  Defines more of the "how" of fetching, whereas JPA {@link javax.persistence.FetchType}
+ * focuses on the "when".
  *
  * @author Emmanuel Bernard
  */
 public enum FetchMode {
 	/**
-	 * use a select for each individual entity, collection, or join load
+	 * use a select for each individual entity, collection, or join load.
 	 */
 	SELECT,
 	/**
-	 * use an outer join to load the related entities, collections or joins
+	 * use an outer join to load the related entities, collections or joins.
 	 */
 	JOIN,
 	/**
-	 * use a subselect query to load the additional collections
+	 * use a subselect query to load the additional collections.
 	 */
 	SUBSELECT
 }

hibernate-core/src/main/java/org/hibernate/annotations/FetchProfile.java

@@ -21,10 +21,8 @@
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
  */
-
-// $Id$
-
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -40,17 +38,35 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target({ TYPE, PACKAGE })
 @Retention(RUNTIME)
 public @interface FetchProfile {
+	/**
+	 * The name of the fetch profile.
+	 */
 	String name();
 
+	/**
+	 * The association fetch overrides.
+	 */
 	FetchOverride[] fetchOverrides();
 
+	/**
+	 * Descriptor for a particular association override.
+	 */
 	@Target({ TYPE, PACKAGE })
 	@Retention(RUNTIME)
-			@interface FetchOverride {
+	@interface FetchOverride {
+		/**
+		 * The entity containing the association whose fetch is being overridden.
+		 */
 		Class<?> entity();
 
+		/**
+		 * The association whose fetch is being overridden.
+		 */
 		String association();
 
+		/**
+		 * The fetch mode to apply to the association.
+		 */
 		FetchMode mode();
 	}
 }

hibernate-core/src/main/java/org/hibernate/annotations/FetchProfiles.java

@@ -21,10 +21,8 @@
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
  */
-
-// $Id$
-
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -33,10 +31,15 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
+ * Collects together multiple fetch profiles.
+ *
  * @author Hardy Ferentschik
  */
 @Target({ TYPE, PACKAGE })
 @Retention(RUNTIME)
 public @interface FetchProfiles {
-	public abstract FetchProfile[] value();
+	/**
+	 * The aggregated fetch profiles.
+	 */
+	public FetchProfile[] value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/Filter.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -31,7 +32,7 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Add filters to an entity or a target entity of a collection
+ * Add filters to an entity or a target entity of a collection.
  *
  * @author Emmanuel Bernard
  * @author Matthew Inger
@@ -41,8 +42,24 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target({TYPE, METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface Filter {
+	/**
+	 * The filter name.
+	 */
 	String name();
+
+	/**
+	 * The filter condition.  If empty, the default condition from the correspondingly named {@link FilterDef} is used.
+	 */
 	String condition() default "";
+
+	/**
+	 * Do we need to determine all points within the condition fragment that are alias injection points?  Or
+	 * are injection points already marked?
+	 */
 	boolean deduceAliasInjectionPoints() default true;
+
+	/**
+	 * The alias descriptors for injection.
+	 */
 	SqlFragmentAlias[] aliases() default {};
 }

hibernate-core/src/main/java/org/hibernate/annotations/FilterDef.java

@@ -30,7 +30,7 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Filter definition
+ * Filter definition.  Defines a name, default condition and parameter types (if any).
  *
  * @author Matthew Inger
  * @author Emmanuel Bernard
@@ -38,9 +38,18 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target({TYPE, PACKAGE})
 @Retention(RUNTIME)
 public @interface FilterDef {
+	/**
+	 * The filter name.
+	 */
 	String name();
 
+	/**
+	 * The default filter condition.
+	 */
 	String defaultCondition() default "";
 
+	/**
+	 * The filter parameter definitions.
+	 */
 	ParamDef[] parameters() default {};
 }

hibernate-core/src/main/java/org/hibernate/annotations/FilterDefs.java

@@ -30,7 +30,7 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Array of filter definitions
+ * Array of filter definitions.
  *
  * @author Matthew Inger
  * @author Emmanuel Bernard
@@ -38,5 +38,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target({PACKAGE, TYPE})
 @Retention(RUNTIME)
 public @interface FilterDefs {
+	/**
+	 * The aggregated filter definitions.
+	 */
 	FilterDef[] value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/FilterJoinTable.java

@@ -21,16 +21,15 @@
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
  */
-
-//$Id$
 package org.hibernate.annotations;
+
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Add filters to a join table collection
+ * Add filters to a join table collection.
  *
  * @author Emmanuel Bernard
  * @author Rob Worsnop
@@ -38,8 +37,24 @@ import java.lang.annotation.Target;
 @Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface FilterJoinTable {
+	/**
+	 * The filter name.
+	 */
 	String name();
+
+	/**
+	 * The filter condition.  If empty, the default condition from the correspondingly named {@link FilterDef} is used.
+	 */
 	String condition() default "";
+
+	/**
+	 * Do we need to determine all points within the condition fragment that are alias injection points?  Or
+	 * are injection points already marked?
+	 */
 	boolean deduceAliasInjectionPoints() default true;
+
+	/**
+	 * The alias descriptors for injection.
+	 */
 	SqlFragmentAlias[] aliases() default {};
 }

hibernate-core/src/main/java/org/hibernate/annotations/FilterJoinTables.java

@@ -22,18 +22,22 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Add multiple @FilterJoinTable to a collection
+ * Add multiple {@code @FilterJoinTable} to a collection.
  *
  * @author Emmanuel Bernard
  */
 @Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface FilterJoinTables {
+	/**
+	 * The aggregated filters.
+	 */
 	FilterJoinTable[] value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/Filters.java

@@ -31,7 +31,7 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Add multiple @Filters
+ * Add multiple {@code @Filters}.
  *
  * @author Emmanuel Bernard
  * @author Matthew Inger
@@ -40,5 +40,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target({TYPE, METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface Filters {
+	/**
+	 * The aggregated filters.
+	 */
 	Filter[] value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/FlushModeType.java

@@ -23,38 +23,37 @@
  */
 package org.hibernate.annotations;
 
-
 /**
  * Enumeration extending javax.persistence flush modes.
  *
  * @author Carlos Gonz<EFBFBD>lez-Cadenas
  */
-
 public enum FlushModeType {
 	/**
-	 * see {@link org.hibernate.FlushMode#ALWAYS}
+	 * Corresponds to {@link org.hibernate.FlushMode#ALWAYS}.
 	 */
 	ALWAYS,
 	/**
-	 * see {@link org.hibernate.FlushMode#AUTO}
+	 * Corresponds to  {@link org.hibernate.FlushMode#AUTO}.
 	 */
 	AUTO,
 	/**
-	 * see {@link org.hibernate.FlushMode#COMMIT}
+	 * Corresponds to  {@link org.hibernate.FlushMode#COMMIT}.
 	 */
 	COMMIT,
 	/**
-	 * see {@link org.hibernate.FlushMode#NEVER}
+	 * Corresponds to  {@link org.hibernate.FlushMode#NEVER}.
+	 *
 	 * @deprecated use MANUAL, will be removed in a subsequent release
 	 */
+	@Deprecated
 	NEVER,
 	/**
-	 * see {@link org.hibernate.FlushMode#MANUAL}
+	 * Corresponds to  {@link org.hibernate.FlushMode#MANUAL}.
 	 */
 	MANUAL,
-
 	/**
-	 * Current flush mode of the persistence context at the time the query is executed
+	 * Current flush mode of the persistence context at the time the query is executed.
 	 */
 	PERSISTENCE_CONTEXT
 }

hibernate-core/src/main/java/org/hibernate/annotations/ForeignKey.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -30,12 +31,13 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+/**
+ * Define the foreign key name.
+ *
+ * Prefer the JPA 2.1 introduced {@link javax.persistence.ForeignKey} instead.
+ */
 @Target({FIELD, METHOD, TYPE})
 @Retention(RUNTIME)
-
-/**
- * Define the foreign key name
- */
 public @interface ForeignKey {
 	/**
 	 * Name of the foreign key.  Used in OneToMany, ManyToOne, and OneToOne

hibernate-core/src/main/java/org/hibernate/annotations/Formula.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -62,5 +63,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface Formula {
+	/**
+	 * The formula string.
+	 */
 	String value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/Generated.java

@@ -22,18 +22,22 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * The annotated property is generated by the database
+ * The annotated property is generated by the database.
  *
  * @author Emmanuel Bernard
  */
 @Target({ElementType.FIELD, ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Generated {
+	/**
+	 * The enum value representing when the value is generated.
+	 */
 	GenerationTime value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/GenerationTime.java

@@ -23,14 +23,22 @@
  */
 package org.hibernate.annotations;
 
-
 /**
- * When should the generation occurs
+ * At what time(s) will the generation occur?
  *
  * @author Emmanuel Bernard
  */
 public enum GenerationTime {
+	/**
+	 * Indicates the value is never generated.
+	 */
 	NEVER,
+	/**
+	 * Indicates the value is generated on insert.
+	 */
 	INSERT,
+	/**
+	 * Indicates the value is generated on insert and on update.
+	 */
 	ALWAYS
 }

hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerator.java

@@ -32,8 +32,7 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Generator annotation describing any kind of Hibernate
+ * Generator annotation describing any kind of Hibernate generator in a generic (de-typed) manner.
- * generator in a detyped manner
  *
  * @author Emmanuel Bernard
  */
@@ -41,16 +40,15 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface GenericGenerator {
 	/**
-	 * unique generator name
+	 * unique generator name.
 	 */
 	String name();
 	/**
-	 * Generator strategy either a predefined Hibernate
+	 * Generator strategy either a predefined Hibernate strategy or a fully qualified class name.
-	 * strategy or a fully qualified class name.
 	 */
 	String strategy();
 	/**
-	 * Optional generator parameters
+	 * Optional generator parameters.
 	 */
 	Parameter[] parameters() default {};
 }

hibernate-core/src/main/java/org/hibernate/annotations/GenericGenerators.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -30,13 +31,16 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Array of generic generator definitions
+ * Array of generic generator definitions.
  *
  * @author Paul Cowan
  */
 @Target({PACKAGE, TYPE})
 @Retention(RUNTIME)
 public @interface GenericGenerators {
+	/**
+	 * The aggregated generators.
+	 */
 	GenericGenerator[] value();
 }
 

hibernate-core/src/main/java/org/hibernate/annotations/Index.java

@@ -30,16 +30,23 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Define a DB index
+ * Define a DB index.
  *
  * @author Emmanuel Bernard
+ *
  * @deprecated Using {@link javax.persistence.Index} instead.
  */
 @Target({FIELD, METHOD})
 @Retention(RUNTIME)
 @Deprecated
 public @interface Index {
+	/**
+	 * The index name.
+	 */
 	String name();
 
+	/**
+	 * The column(s) that are indexed.
+	 */
 	String[] columnNames() default {};
 }

hibernate-core/src/main/java/org/hibernate/annotations/IndexColumn.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -30,20 +31,33 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Describe an index column of a List
+ * Describe an index column of a List.
- * Prefer the standard {@link javax.persistence.OrderColumn} annotation
+ *
+ * Prefer the standard {@link javax.persistence.OrderColumn} annotation.  Currently the only time to use
+ * this annotation is to specify {@link #base()}.
  *
  * @author Matthew Inger
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface IndexColumn {
-	/** column name */
+	/**
+	 * The column name.
+	 */
 	String name();
-	/** index in DB start from base */
+
+	/**
+	 * The starting index value.  Zero (0) by default, since Lists indexes start at zero (0).
+	 */
 	int base() default 0;
-	/** is the index nullable */
+
+	/**
+	 * Is the column nullable?
+	 */
 	boolean nullable() default true;
-	/** column definition, default to an appropriate integer */
+
+	/**
+	 * An explicit column definition.
+	 */
 	String columnDefinition() default "";
 }

hibernate-core/src/main/java/org/hibernate/annotations/JoinColumnOrFormula.java

@@ -21,9 +21,8 @@
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
  */
-
-
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 import javax.persistence.JoinColumn;
@@ -33,11 +32,21 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
+ * Allows joins based on column or a formula.  One of {@link #formula()} or {@link #column()} should be
+ * specified, but not both.
+ *
  * @author Sharath Reddy
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface JoinColumnOrFormula {
+	/**
+	 * The formula to use in joining.
+	 */
 	JoinFormula formula() default @JoinFormula(value="", referencedColumnName="");
+
+	/**
+	 * The column to use in joining.
+	 */
 	JoinColumn column() default @JoinColumn();
 }

hibernate-core/src/main/java/org/hibernate/annotations/JoinColumnsOrFormulas.java

@@ -31,10 +31,15 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
+ * Collection of {@code @JoinColumnOrFormula} definitions.
+ *
  * @author Sharath Reddy
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface JoinColumnsOrFormulas {
+	/**
+	 * The aggregated values.
+	 */
 	JoinColumnOrFormula [] value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/JoinFormula.java

@@ -21,8 +21,8 @@
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
  */
-
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -31,14 +31,21 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * JoinFormula. To be used as a replacement for @JoinColumn in most places
+ * To be used as a replacement for {@code @JoinColumn} in most places.  The formula has to be a valid
- * The formula has to be a valid SQL fragment
+ * SQL fragment
  *
  * @author Sharath Reddy
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface JoinFormula {
+	/**
+	 * The formula.
+	 */
 	String value();
+
+	/**
+	 * The column this formula references.
+	 */
 	String referencedColumnName() default "";
 }

hibernate-core/src/main/java/org/hibernate/annotations/LazyCollection.java

@@ -22,18 +22,22 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Define the lazy status of a collection
+ * Define the lazy status of a collection.
  *
  * @author Emmanuel Bernard
  */
 @Target({ElementType.METHOD, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface LazyCollection {
+	/**
+	 * The laziness option for the collection.
+	 */
 	LazyCollectionOption value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/LazyCollectionOption.java

@@ -23,17 +23,22 @@
  */
 package org.hibernate.annotations;
 
-
 /**
- * Lazy options available for a collection
+ * Lazy options available for a collection.
  *
  * @author Emmanuel Bernard
  */
 public enum LazyCollectionOption {
-	/** eagerly load it */
+	/**
+	 * Eagerly load it.
+	 */
 	FALSE,
-	/** load it when the state is requested */
+	/**
+	 * Load it when the state is requested.
+	 */
 	TRUE,
-	/** prefer extra queries over fill collection loading */
+	/**
+	 * Prefer extra queries over full collection loading.
+	 */
 	EXTRA
 }

hibernate-core/src/main/java/org/hibernate/annotations/LazyToOne.java

@@ -22,19 +22,22 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Define the lazy status of a ToOne association
+ * Define the laziness options available for a ToOne (ie OneToOne or ManyToOne) association.
- * (ie OneToOne or ManyToOne)
  *
  * @author Emmanuel Bernard
  */
 @Target({ElementType.METHOD, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface LazyToOne {
+	/**
+	 * Specify the laziness option.
+	 */
 	LazyToOneOption value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/LazyToOneOption.java

@@ -23,24 +23,28 @@
  */
 package org.hibernate.annotations;
 
-
 /**
- * Lazy options available for a ToOne association
+ * Lazy options available for a ToOne association.
  *
  * @author Emmanuel Bernard
  */
 public enum LazyToOneOption {
-	/** eagerly load the association */
+	/**
+	 * Eagerly load the association.
+	 */
 	FALSE,
 	/**
-	 * Lazy, give back a proxy which will be loaded when the state is requested
+	 * Lazy, give back a proxy which will be loaded when the state is requested.
-	 * This should be the prefered option
+	 *
+	 * This should be the preferred option.
 	 */
 	PROXY,
-	/** Lazy, give back the real object loaded when a reference is requested
+	/**
-	 * (Bytecode enhancement is mandatory for this option, fall back to PROXY
+	 * Lazy, give back the real object loaded when a reference is requested.
-	 * if the class is not enhanced)
+	 *
-	 * This option should be avoided unless you can't afford the use of proxies
+	 * Bytecode enhancement is mandatory for this option.  Falls back to {@link #PROXY}
+	 * if the class is not enhanced.  This option should be avoided unless you can't afford
+	 * the use of proxies
 	 */
 	NO_PROXY
 }

hibernate-core/src/main/java/org/hibernate/annotations/Loader.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -31,7 +32,8 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Loader Annotation for overwriting Hibernate default FIND method
+ * Used to override how Hibernate performs load operations. naming a named query to use instead of
+ * its generated SELECT SQL.
  *
  * @author L<EFBFBD>szl<EFBFBD> Benke
  */
@@ -39,7 +41,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention( RUNTIME )
 public @interface Loader {
 	/**
-	 * namedQuery to use for loading
+	 * THe namedQuery to use for loading.
 	 */
 	String namedQuery() default "";
 }

hibernate-core/src/main/java/org/hibernate/annotations/MapKeyType.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 
 import static java.lang.annotation.ElementType.FIELD;
@@ -36,5 +37,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @java.lang.annotation.Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface MapKeyType {
+	/**
+	 * The map key type definition.
+	 */
 	Type value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/MetaValue.java

@@ -33,12 +33,12 @@ package org.hibernate.annotations;
  */
 public @interface MetaValue {
 	/**
-	 * entity type
+	 * The entity type.
 	 */
 	Class targetEntity();
 
 	/**
-	 * discriminator value stored in database
+	 * The corresponding discriminator value stored in database.
 	 */
 	String value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQueries.java

@@ -30,13 +30,16 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Extends {@link javax.persistence.NamedNativeQueries} to hold hibernate NamedNativeQuery
+ * A grouping of Hibernate-specific {@link NamedNativeQuery} definitions.  Effectively extends the named native
- * objects
+ * query definitions made available through {@link javax.persistence.NamedNativeQueries}.
  *
  * @author Emmanuel Bernard
  */
 @Target({TYPE, PACKAGE})
 @Retention(RUNTIME)
 public @interface NamedNativeQueries {
+	/**
+	 * The grouping of Hibernate named native SQL queries.
+	 */
 	NamedNativeQuery[] value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/NamedNativeQuery.java

@@ -30,36 +30,77 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Extends {@link javax.persistence.NamedNativeQuery} with Hibernate features
+ * Extends {@link javax.persistence.NamedNativeQuery} with Hibernate features.
  *
  * @author Emmanuel Bernard
+ *
+ * @see org.hibernate.SQLQuery
  */
 @Target({TYPE, PACKAGE})
 @Retention(RUNTIME)
 public @interface NamedNativeQuery {
+	/**
+	 * The name.  It is a named query after all :)
+	 */
 	String name();
 
+	/**
+	 * The SQL query string.
+	 */
 	String query();
 
+	/**
+	 * The result Class.  Should not be used in conjunction with {@link #resultSetMapping()}
+	 */
 	Class resultClass() default void.class;
 
-	String resultSetMapping() default ""; // name of SQLResultSetMapping
+	/**
-	/** the flush mode for the query */
+	 * The name of a SQLResultSetMapping to use.  Should not be used in conjunction with {@link #resultClass()}.
+	 */
+	String resultSetMapping() default "";
+
+	/**
+	 * The flush mode for the query.
+	 */
 	FlushModeType flushMode() default FlushModeType.PERSISTENCE_CONTEXT;
-	/** mark the query as cacheable or not */
+
+	/**
+	 * Whether the query (results) is cacheable or not.  Default is {@code false}, that is not cacheable.
+	 */
 	boolean cacheable() default false;
-	/** the cache region to use */
+
+	/**
+	 * If the query results are cacheable, name the query cache region to use.
+	 */
 	String cacheRegion() default "";
-	/** the number of rows fetched by the JDBC Driver per roundtrip */
+
+	/**
+	 * The number of rows fetched by the JDBC Driver per trip.
+	 */
 	int fetchSize() default -1;
-	/**the query timeout in seconds*/
+
+	/**
+	 * The query timeout (in seconds).  Default is no timeout.
+	 */
 	int timeout() default -1;
 
+	/**
+	 * Does the SQL ({@link #query()}) represent a call to a procedure/function?
+	 */
 	boolean callable() default false;
-	/**comment added to the SQL query, useful for the DBA */
+
+	/**
+	 * A comment added to the SQL query.  Useful when engaging with DBA.
+	 */
 	String comment() default "";
-	/**the cache mode used for this query*/
+
+	/**
+	 * The cache mode used for this query.  This refers to entities/collections returned from the query.
+	 */
 	CacheModeType cacheMode() default CacheModeType.NORMAL;
-	/**marks whether the results are fetched in read-only mode or not*/
+
+	/**
+	 * Whether the results should be read-only.  Default is {@code false}.
+	 */
 	boolean readOnly() default false;
 }

hibernate-core/src/main/java/org/hibernate/annotations/NamedQueries.java

@@ -30,8 +30,8 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Extends {@link javax.persistence.NamedQueries} to hold hibernate NamedQuery
+ * A grouping of Hibernate-specific {@link NamedQuery} definitions.  Effectively extends the named query
- * objects
+ * definitions made available through {@link javax.persistence.NamedQueries}.
  *
  * @author Emmanuel Bernard
  * @author Carlos Gonz<EFBFBD>lez-Cadenas
@@ -39,5 +39,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target({TYPE, PACKAGE})
 @Retention(RUNTIME)
 public @interface NamedQueries {
+	/**
+	 * The grouping of named queries.
+	 */
 	NamedQuery[] value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/NamedQuery.java

@@ -31,61 +31,63 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Extends {@link javax.persistence.NamedQuery} with Hibernate features
+ * Extends {@link javax.persistence.NamedQuery} with Hibernate features.
  *
  * @author Carlos Gonzalez-Cadenas
+ *
+ * @see org.hibernate.Query
  */
 @Target( { TYPE, PACKAGE })
 @Retention(RUNTIME)
 public @interface NamedQuery {
 
 	/**
-	 * @return returns the name of this {@code NamedQuery}
+	 * The name of this {@code NamedQuery}.
 	 */
 	String name();
 
 	/**
-	 * @return returns the query string for this {@code NamedQuery}
+	 * The query string for this {@code NamedQuery}.
 	 */
 	String query();
 
 	/**
-	 * @return returns the flush mode for this query
+	 * The flush mode for this query.
 	 */
 	FlushModeType flushMode() default FlushModeType.PERSISTENCE_CONTEXT;
 
 	/**
-	 * @return returns whether this query is cacheable or not
+	 * Whether the query (results) is cacheable or not.  Default is {@code false}, that is not cacheable.
 	 */
 	boolean cacheable() default false;
 
 	/**
-	 * @return returns the the cache region to use
+	 * If the query results are cacheable, name the query cache region to use.
 	 */
 	String cacheRegion() default "";
 
 	/**
-	 * @return returns the number of rows fetched by the JDBC Driver per database round-trip
+	 * The number of rows fetched by the JDBC Driver per trip.
 	 */
 	int fetchSize() default -1;
 
 	/**
-	 * @return return the query timeout in seconds
+	 * The query timeout (in seconds).  Default is no timeout.
 	 */
 	int timeout() default -1;
 
 	/**
-	 * @return returns the comment added to the SQL query (useful for the DBA)
+	 * A comment added to the generated SQL query.  Useful when engaging with DBA.
 	 */
 	String comment() default "";
 
 	/**
-	 * @return returns the cache mode used for this query
+	 * The cache mode used for this query.  This refers to entities/collections returned from the query.
 	 */
 	CacheModeType cacheMode() default CacheModeType.NORMAL;
 
 	/**
-	 * @return returns whether the results are fetched in read-only mode or not. Default is {@code false}
+	 * Whether the results should be read-only.  Default is {@code false}.
 	 */
 	boolean readOnly() default false;
 }

hibernate-core/src/main/java/org/hibernate/annotations/NaturalId.java

@@ -34,15 +34,15 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * This specifies that a property is part of the natural id of the entity.
  *
  * @author Nicol<EFBFBD>s Lichtmaier
+ *
  * @see NaturalIdCache
  */
 @Target( { METHOD, FIELD } )
 @Retention( RUNTIME )
 public @interface NaturalId {
 	/**
-	 * Is this natural id mutable (or immutable)?
+	 * Whether the natural id is mutable (or immutable)?  {@code false} (the default) indicates it is immutable;
-	 *
+	 * {@code true} indicates it is mutable.
-	 * @return {@code true} indicates the natural id is mutable; {@code false} (the default) that it is immutable.
 	 */
 	boolean mutable() default false;
 }

hibernate-core/src/main/java/org/hibernate/annotations/NotFound.java

@@ -38,5 +38,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target( { METHOD, FIELD })
 @Retention(RUNTIME)
 public @interface NotFound {
+	/**
+	 * The action to perform when an associated entity is not found.  By default an exception is thrown.
+	 */
 	NotFoundAction action() default NotFoundAction.EXCEPTION;
 }

hibernate-core/src/main/java/org/hibernate/annotations/NotFoundAction.java

@@ -25,17 +25,18 @@ package org.hibernate.annotations;
 
 
 /**
- * Actoin to use when an element is not found in DB while beeing expected
+ * Possible actions when an associated entity is not found in the database.  Often seen with "legacy" foreign-key
+ * schemes which do not use {@code NULL} to indicate a missing reference, instead using a "magic value".
  *
  * @author Emmanuel Bernard
  */
 public enum NotFoundAction {
 	/**
-	 * raise an exception when an element is not found (default and recommended)
+	 * Raise an exception when an element is not found (default and recommended).
 	 */
 	EXCEPTION,
 	/**
-	 * ignore the element when not found in DB
+	 * Ignore the element when not found in database.
 	 */
 	IGNORE
 }

hibernate-core/src/main/java/org/hibernate/annotations/OnDelete.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -32,7 +33,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 
 /**
- * Strategy to use on collections, arrays and on joined subclasses delete
+ * Strategy to use on collections, arrays and on joined subclasses delete.
+ *
  * OnDelete of secondary tables currently not supported.
  *
  * @author Emmanuel Bernard
@@ -40,5 +42,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target({METHOD, FIELD, TYPE})
 @Retention(RUNTIME)
 public @interface OnDelete {
+	/**
+	 * The on-delete action.
+	 */
 	OnDeleteAction action();
 }

hibernate-core/src/main/java/org/hibernate/annotations/OnDeleteAction.java

@@ -23,19 +23,18 @@
  */
 package org.hibernate.annotations;
 
-
 /**
- * Possible actions on deletes
+ * Possible actions for on-delete.
  *
  * @author Emmanuel Bernard
  */
 public enum OnDeleteAction {
 	/**
-	 * the default
+	 * Take no action.  The default.
 	 */
 	NO_ACTION,
 	/**
-	 * use cascade delete capabilities of the DD
+	 * Use cascade delete capabilities of the database foreign-key.
 	 */
 	CASCADE
 }

hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLock.java

@@ -30,6 +30,7 @@ import java.lang.annotation.Target;
 
 /**
  * Whether or not a change of the annotated property will trigger a entity version increment.
+ *
  * If the annotation is not present, the property is involved in the optimistic lock strategy (default).
  *
  * @author Logi Ragnarsson
@@ -38,7 +39,7 @@ import java.lang.annotation.Target;
 @Retention(RetentionPolicy.RUNTIME)
 public @interface OptimisticLock {
 	/**
-	 * @return If {@code true}, the annotated property change will not trigger a version increment.
+	 * Whether the annotated property should be included in optimistic locking determinations for the owner.
 	 */
 	boolean excluded();
 }

hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLockType.java

@@ -23,28 +23,30 @@
  */
 package org.hibernate.annotations;
 
-
 /**
- * Optimistic locking strategy
+ * Possible optimistic locking strategies.
- * VERSION is the default and recommended one
  *
  * @author Emmanuel Bernard
  */
 public enum OptimisticLockType {
 	/**
-	 * no optimistic locking
+	 * Perform no optimistic locking.
 	 */
 	NONE,
 	/**
-	 * use a column version
+	 * Perform optimistic locking using a dedicated version column.
+	 *
+	 * @see javax.persistence.Version
 	 */
 	VERSION,
 	/**
-	 * dirty columns are compared
+	 * Perform optimistic locking based on *dirty* fields as part of an expanded WHERE clause restriction for the
+	 * UPDATE/DELETE SQL statement.
 	 */
 	DIRTY,
 	/**
-	 * all columns are compared
+	 * Perform optimistic locking based on *all* fields as part of an expanded WHERE clause restriction for the
+	 * UPDATE/DELETE SQL statement.
 	 */
 	ALL
 }

hibernate-core/src/main/java/org/hibernate/annotations/OptimisticLocking.java

@@ -38,5 +38,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target( TYPE )
 @Retention( RUNTIME )
 public @interface OptimisticLocking {
+	/**
+	 * Defines the style of optimistic locking for the entity.
+	 */
 	OptimisticLockType type() default OptimisticLockType.VERSION;
 }

hibernate-core/src/main/java/org/hibernate/annotations/OrderBy.java

@@ -30,13 +30,18 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Order a collection using SQL ordering (not HQL ordering)
+ * Order a collection using SQL ordering (not HQL ordering).
  *
  * @author Emmanuel Bernard
+ *
+ * @see javax.persistence.OrderBy
+ * @see Sort
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface OrderBy {
-	/** SQL orderby clause */
+	/**
+	 * SQL ordering clause.
+	 */
 	String clause();
 }

hibernate-core/src/main/java/org/hibernate/annotations/ParamDef.java

@@ -22,20 +22,29 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * A parameter definition
+ * A parameter definition.
  *
  * @author Emmanuel Bernard
  */
 @Target({})
 @Retention(RUNTIME)
 public @interface ParamDef {
+	/**
+	 * The name of the parameter definition.
+	 */
 	String name();
 
+	/**
+	 * The type being defined,  Typically this is the fully-qualified name of the {@link org.hibernate.type.Type},
+	 * {@link org.hibernate.usertype.UserType} or {@link org.hibernate.usertype.CompositeUserType} implementation
+	 * class.
+	 */
 	String type();
 }

hibernate-core/src/main/java/org/hibernate/annotations/Parameter.java

@@ -28,14 +28,20 @@ import java.lang.annotation.Target;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Parameter (basically key/value pattern)
+ * Generic parameter (basically a key/value combination) used to parametrize other annotations.
  *
  * @author Emmanuel Bernard
  */
 @Target({})
 @Retention(RUNTIME)
 public @interface Parameter {
+	/**
+	 * The parameter name.
+	 */
 	String name();
 
+	/**
+	 * The parameter value.
+	 */
 	String value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/Parent.java

@@ -30,7 +30,7 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Reference the property as a pointer back to the owner (generally the owning entity)
+ * Reference the property as a pointer back to the owner (generally the owning entity).
  * 
  * @author Emmanuel Bernard
  */

hibernate-core/src/main/java/org/hibernate/annotations/Persister.java

@@ -36,7 +36,7 @@ import java.lang.annotation.RetentionPolicy;
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Persister {
 	/**
-	 * @return The custom persister class
+	 * The custom persister class.
 	 */
 	Class<?> impl();
 }

hibernate-core/src/main/java/org/hibernate/annotations/Polymorphism.java

@@ -37,5 +37,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target( TYPE )
 @Retention( RUNTIME )
 public @interface Polymorphism {
+	/**
+	 * Specifies the polymorphism type.
+	 */
 	PolymorphismType type() default PolymorphismType.IMPLICIT;
 }

hibernate-core/src/main/java/org/hibernate/annotations/PolymorphismType.java

@@ -23,19 +23,18 @@
  */
 package org.hibernate.annotations;
 
-
 /**
- * Type of available polymorphism for a particular entity
+ * Type of available polymorphism for a particular entity.
  *
  * @author Emmanuel Bernard
  */
 public enum PolymorphismType {
 	/**
-	 * default, this entity is retrieved if any of its super entity is asked
+	 * This entity is retrieved if any of its super entity are retrieved.  The default,
 	 */
 	IMPLICIT,
 	/**
-	 * this entity is retrieved only if explicitly asked
+	 * This entity is retrieved only if explicitly asked.
 	 */
 	EXPLICIT
 }

hibernate-core/src/main/java/org/hibernate/annotations/Proxy.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -29,7 +30,7 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Lazy and proxy configuration of a particular class
+ * Lazy and proxy configuration of a particular class.
  *
  * @author Emmanuel Bernard
  */
@@ -37,12 +38,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface Proxy {
 	/**
-	 * Whether this class is lazy or not (default to true)
+	 * Whether this class is lazy or not.  Default to true.
 	 */
 	boolean lazy() default true;
 
 	/**
-	 * Proxy class or interface used. Default entity class name.
+	 * Proxy class or interface used.  Default is to use the entity class name.
 	 */
 	Class proxyClass() default void.class;
 }

hibernate-core/src/main/java/org/hibernate/annotations/QueryHints.java

@@ -24,21 +24,90 @@
 package org.hibernate.annotations;
 
 /**
- *
+ * Consolidation of hints available to Hibernate JPA queries.  Mainly used to define features available on
+ * Hibernate queries that have no corollary in JPA queries.
  */
 public class QueryHints {
+	/**
+	 * Disallow instantiation.
+	 */
+	private QueryHints() {
+	}
 
+	/**
+	 * The cache mode to use.
+	 *
+	 * @see org.hibernate.Query#setCacheMode
+	 * @see org.hibernate.SQLQuery#setCacheMode
+	 */
     public static final String CACHE_MODE = "org.hibernate.cacheMode";
+
+	/**
+	 * The cache region to use.
+	 *
+	 * @see org.hibernate.Query#setCacheRegion
+	 * @see org.hibernate.SQLQuery#setCacheRegion
+	 */
     public static final String CACHE_REGION = "org.hibernate.cacheRegion";
+
+	/**
+	 * Are the query results cacheable?
+	 *
+	 * @see org.hibernate.Query#setCacheable
+	 * @see org.hibernate.SQLQuery#setCacheable
+	 */
     public static final String CACHEABLE = "org.hibernate.cacheable";
+
+	/**
+	 * Is the query callable?  Note: only valid for named native sql queries.
+	 */
     public static final String CALLABLE = "org.hibernate.callable";
+
+	/**
+	 * Defines a comment to be applied to the SQL sent to the database.
+	 *
+	 * @see org.hibernate.Query#setComment
+	 * @see org.hibernate.SQLQuery#setComment
+	 */
     public static final String COMMENT = "org.hibernate.comment";
+
+	/**
+	 * Defines the JDBC fetch size to use.
+	 *
+	 * @see org.hibernate.Query#setFetchSize
+	 * @see org.hibernate.SQLQuery#setFetchSize
+	 */
     public static final String FETCH_SIZE = "org.hibernate.fetchSize";
+
+	/**
+	 * The flush mode to associate with the execution of the query.
+	 *
+	 * @see org.hibernate.Query#setFlushMode
+	 * @see org.hibernate.SQLQuery#setFlushMode
+	 * @see org.hibernate.Session#setFlushMode
+	 */
     public static final String FLUSH_MODE = "org.hibernate.flushMode";
+
+	/**
+	 * Should entities returned from the query be set in read only mode?
+	 *
+	 * @see org.hibernate.Query#setReadOnly
+	 * @see org.hibernate.SQLQuery#setReadOnly
+	 * @see org.hibernate.Session#setReadOnly
+	 */
     public static final String READ_ONLY = "org.hibernate.readOnly";
+
+	/**
+	 * Apply a Hibernate query timeout, which is defined in <b>seconds</b>.
+	 *
+	 * @see org.hibernate.Query#setTimeout
+	 * @see org.hibernate.SQLQuery#setTimeout
+	 */
     public static final String TIMEOUT_HIBERNATE = "org.hibernate.timeout";
+
+	/**
+	 * Apply a JPA query timeout, which is defined in <b>milliseconds</b>.
+	 */
     public static final String TIMEOUT_JPA = "javax.persistence.query.timeout";
 
-    private QueryHints() {
-    }
 }

hibernate-core/src/main/java/org/hibernate/annotations/ResultCheckStyle.java

@@ -23,18 +23,17 @@
  */
 package org.hibernate.annotations;
 
-
 /**
- * Possible checks on Sql Insert, Delete, Update
+ * Possible styles of checking return codes on SQL INSERT, UPDATE and DELETE queries.
  *
  * @author L<EFBFBD>szl<EFBFBD> Benke
  */
 public enum ResultCheckStyle {
 	/**
-	 * Do not perform checking.  Either user simply does not want checking, or is
+	 * Do not perform checking.  Might mean that the user really just does not want any checking.  Might
-	 * indicating a {@link java.sql.CallableStatement} execution in which the
+	 * also mean that the user is expecting a failure to be indicated by a {@link java.sql.SQLException} being
-	 * checks are being performed explicitly and failures are handled through
+	 * thrown (presumably from a {@link java.sql.CallableStatement} which is performing explicit checks and
-	 * propogation of {@link java.sql.SQLException}s.
+	 * propagating failures back through the driver).
 	 */
 	NONE,
 	/**

hibernate-core/src/main/java/org/hibernate/annotations/RowId.java

@@ -29,7 +29,7 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Support for {@literal ROWID} mapping feature of Hibernate.
+ * Support for {@code ROWID} mapping feature of Hibernate.
  *
  * @author Steve Ebersole
  */
@@ -37,9 +37,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface RowId {
 	/**
-	 * Names the {@literal ROWID} identifier
+	 * Names the {@code ROWID} identifier.
-	 *
-	 * @return The {@literal ROWID} identifier
 	 */
 	String value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/SQLDelete.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -31,7 +32,7 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * SqlDelete Annotation for overwriting Hibernate default DELETE method
+ * Custom SQL statement for delete of an entity/collection.
  *
  * @author L<EFBFBD>szl<EFBFBD> Benke
  */
@@ -39,12 +40,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention( RUNTIME )
 public @interface SQLDelete {
 	/**
-	 * Procedure name or DELETE STATEMENT
+	 * Procedure name or SQL DELETE statement.
 	 */
 	String sql();
 
 	/**
-	 * Is the statement using stored procedure or not
+	 * Is the statement callable (aka a {@link java.sql.CallableStatement})?
 	 */
 	boolean callable() default false;
 

hibernate-core/src/main/java/org/hibernate/annotations/SQLDeleteAll.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
@@ -31,7 +32,7 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.TYPE;
 
 /**
- * SqlDelete Annotation for overwriting Hibernate default DELETE ALL method
+ * Custom SQL statement for delete of all of a collection's elements.
  *
  * @author L<EFBFBD>szl<EFBFBD> Benke
  */
@@ -39,12 +40,12 @@ import static java.lang.annotation.ElementType.TYPE;
 @Retention( RetentionPolicy.RUNTIME )
 public @interface SQLDeleteAll {
 	/**
-	 * Procedure name or DELETE STATEMENT
+	 * Procedure name or SQL DELETE statement.
 	 */
 	String sql();
 
 	/**
-	 * Is the statement using stored procedure or not
+	 * Is the statement callable (aka a {@link java.sql.CallableStatement})?
 	 */
 	boolean callable() default false;
 

hibernate-core/src/main/java/org/hibernate/annotations/SQLInsert.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -31,7 +32,7 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * SqlInsert Annotation for overwriting Hibernate default INSERT INTO method
+ * Custom SQL statement for insertion of an entity/collection.
  *
  * @author L<EFBFBD>szl<EFBFBD> Benke
  */
@@ -39,12 +40,12 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention( RUNTIME )
 public @interface SQLInsert {
 	/**
-	 * Procedure name or INSERT STATEMENT
+	 * Procedure name or SQL INSERT statement.
 	 */
 	String sql();
 
 	/**
-	 * Is the statement using stored procedure or not
+	 * Is the statement callable (aka a {@link java.sql.CallableStatement})?
 	 */
 	boolean callable() default false;
 

hibernate-core/src/main/java/org/hibernate/annotations/SQLUpdate.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -31,21 +32,20 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * SqlUpdate Annotation for overwriting Hibernate default UPDATE method
+ * Custom SQL statement for update of an entity/collection.
  *
  * @author L<EFBFBD>szl<EFBFBD> Benke
  */
 @Target( {TYPE, FIELD, METHOD} )
 @Retention( RUNTIME )
 public @interface SQLUpdate {
-
 	/**
-	 * Procedure name or UPDATE STATEMENT
+	 * Procedure name or SQL UPDATE statement.
 	 */
 	String sql();
 
 	/**
-	 * Is the statement using stored procedure or not
+	 * Is the statement callable (aka a {@link java.sql.CallableStatement})?
 	 */
 	boolean callable() default false;
 

hibernate-core/src/main/java/org/hibernate/annotations/SelectBeforeUpdate.java

@@ -38,5 +38,10 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target( TYPE )
 @Retention( RUNTIME )
 public @interface SelectBeforeUpdate {
+	/**
+	 * {@code true} (which is the default when this annotation is present) indicates that
+	 * {@code select-before-update} processing should occur.  {@code false} indicates
+	 * {@code select-before-update} processing should not occur.
+	 */
 	boolean value() default true;
 }

hibernate-core/src/main/java/org/hibernate/annotations/Sort.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -30,22 +31,24 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Collection sort
+ * Collection sort (in-memory sorting).  Different that ordering, which is applied during the SQL select.
- * (Java level sorting)
  *
  * @author Emmanuel Bernard
+ *
+ * @see OrderBy
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface Sort {
 	/**
-	 * sort type
+	 * The type of sorting to use.  The default is to not use sorting.
 	 */
 	SortType type() default SortType.UNSORTED;
-	/**
-	 * Sort comparator implementation
-	 */
-	//TODO find a way to use Class<Comparator>
 
+	/**
+	 * Specifies the comparator to use.  Only valid when {@link #type} specifies {@link SortType#COMPARATOR}.
+	 *
+	 * TODO find a way to use Class<Comparator> -> see HHH-8164
+	 */
 	Class comparator() default void.class;
 }

hibernate-core/src/main/java/org/hibernate/annotations/SortType.java

@@ -23,14 +23,22 @@
  */
 package org.hibernate.annotations;
 
-
 /**
- * Sort strategies
+ * Possible collection sorting strategies.
  *
  * @author Emmanuel Bernard
  */
 public enum SortType {
+	/**
+	 * The collection is unsorted.
+	 */
 	UNSORTED,
+	/**
+	 * The collection is sorted using its natural sorting.
+	 */
 	NATURAL,
+	/**
+	 * The collection is sorted using a supplied comparator.
+	 */
 	COMPARATOR
 }

hibernate-core/src/main/java/org/hibernate/annotations/Source.java

@@ -21,8 +21,8 @@
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
  */
-
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -31,13 +31,16 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Optional annotation in conjunction with {@link javax.persistence.Version} and timestamp version properties.
+ * Optional annotation in conjunction with {@link javax.persistence.Version} and timestamp version properties
- * The annotation value decides where the timestamp is generated.
+ * indicating the source of the timestamp value.
  *
  * @author Hardy Ferentschik
  */
 @Target({ METHOD, FIELD })
 @Retention(RUNTIME)
 public @interface Source {
+	/**
+	 * How is the timestamp generated?  Default is a JVM generated value.
+	 */
 	SourceType value() default SourceType.VM;
 }

hibernate-core/src/main/java/org/hibernate/annotations/SourceType.java

@@ -21,10 +21,8 @@
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
  */
-
 package org.hibernate.annotations;
 
-
 /**
  * Where should Hibernate retrieve the value from? From the database, or from the current JVM?
  *
@@ -34,19 +32,24 @@ public enum SourceType {
 	/**
 	 * Get the timestamp from the current VM.
 	 */
-	VM("timestamp"),
+	VM( "timestamp" ),
 
 	/**
 	 * Get the timestamp from the database.
 	 */
-	DB("dbtimestamp");
+	DB( "dbtimestamp" );
 
 	private final String typeName;
 
-	SourceType(String typeName ) {
+	private SourceType(String typeName ) {
 		this.typeName = typeName;
 	}
 
+	/**
+	 * Get the corresponding Hibernate {@link org.hibernate.type.VersionType} name.
+	 *
+	 * @return The corresponding type name.
+	 */
 	public String typeName() {
 		return typeName;
 	}

hibernate-core/src/main/java/org/hibernate/annotations/SqlFragmentAlias.java

@@ -29,15 +29,27 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
+
 /**
- * Describe aliases for filters
+ * Describe aliases for filters.
  *
  * @author Rob Worsnop
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface SqlFragmentAlias {
+	/**
+	 * The alias within the fragment.
+	 */
 	String alias();
+
+	/**
+	 * The table corresponding to the alias.
+	 */
 	String table() default "";
+
+	/**
+	 * The entity class associated with the alias.
+	 */
 	Class entity() default void.class;
 }

hibernate-core/src/main/java/org/hibernate/annotations/Subselect.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -29,12 +30,17 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Map an immutable and read-only entity to a given SQL subselect expression:
+ * Map an immutable and read-only entity to a given SQL select expression.
- * @author Sharath Reddy
  *
+ * @see Synchronize
+ *
+ * @author Sharath Reddy
  */
 @Target(TYPE)
 @Retention(RUNTIME)
 public @interface Subselect {
+	/**
+	 * The query.
+	 */
 	String value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/Synchronize.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -32,7 +33,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * Ensures that auto-flush happens correctly and that queries against the derived 
  * entity do not return stale data.
  * 
- * Mostly used with Subselect.
+ * Mostly used with {@link Subselect}.
  * 
  * @author Sharath Reddy
  */
@@ -40,7 +41,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface Synchronize {
 	/**
-	 * Table names
+	 * Table names.
 	 */
-	String [] value();
+	String[] value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/Table.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -29,7 +30,7 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Complementary information to a table either primary or secondary
+ * Complementary information to a table either primary or secondary.
  *
  * @author Emmanuel Bernard
  */
@@ -37,23 +38,22 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface Table {
 	/**
-	 * name of the targeted table
+	 * name of the targeted table.
 	 */
 	String appliesTo();
 
 	/**
-	 * Indexes
+	 * Indexes.
 	 */
 	Index[] indexes() default {};
 
 	/**
-	 * define a table comment
+	 * define a table comment.
 	 */
 	String comment() default "";
 
 	/**
-	 * Defines the Foreign Key name of a secondary table
+	 * Defines the Foreign Key name of a secondary table pointing back to the primary table.
-	 * pointing back to the primary table
 	 */
 	ForeignKey foreignKey() default @ForeignKey( name="" );
 
@@ -86,21 +86,21 @@ public @interface Table {
 	boolean optional() default true;
 
 	/**
-	 * Defines a custom SQL insert statement
+	 * Defines a custom SQL insert statement.
 	 *
 	 * <b>Only applies to secondary tables</b>
 	 */
 	SQLInsert sqlInsert() default @SQLInsert(sql="");
 
 	/**
-	 * Defines a custom SQL update statement
+	 * Defines a custom SQL update statement.
 	 *
 	 * <b>Only applies to secondary tables</b>
 	 */
 	SQLUpdate sqlUpdate() default @SQLUpdate(sql="");
 
 	/**
-	 * Defines a custom SQL delete statement
+	 * Defines a custom SQL delete statement.
 	 *
 	 * <b>Only applies to secondary tables</b>
 	 */

hibernate-core/src/main/java/org/hibernate/annotations/Tables.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -29,13 +30,15 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Plural of Table
+ * A grouping of tables.
  *
  * @author Emmanuel Bernard
- * @see Table
  */
 @Target({TYPE})
 @Retention(RUNTIME)
 public @interface Tables {
+	/**
+	 * The table grouping.
+	 */
 	Table[] value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/Target.java

@@ -22,17 +22,21 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
 /**
- * Define an explicit target,a voiding reflection and generics resolving
+ * Define an explicit target, avoiding reflection and generics resolving.
  *
  * @author Emmanuel Bernard
  */
 @java.lang.annotation.Target({ElementType.FIELD, ElementType.METHOD})
 @Retention( RetentionPolicy.RUNTIME )
 public @interface Target {
+	/**
+	 * The target entity type.
+	 */
 	Class value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/Tuplizer.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 
 import org.hibernate.EntityMode;
@@ -32,19 +33,27 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Define a tuplizer for an entity or a component
+ * Define a tuplizer for an entity or a component.
+ *
  * @author Emmanuel Bernard
  */
 @java.lang.annotation.Target( {TYPE, FIELD, METHOD} )
 @Retention( RUNTIME )
 public @interface Tuplizer {
-	/** tuplizer implementation */
-	Class impl();
 	/**
-	 * either pojo, dynamic-map or dom4j
+	 * Tuplizer implementation.
+	 */
+	Class impl();
+
+	/**
+	 * either pojo, dynamic-map or dom4j.
 	 * @deprecated should use #entityModeType instead
 	 */
 	@Deprecated
 	String entityMode() default "pojo";
+
+	/**
+	 * The entity mode.
+	 */
 	EntityMode entityModeType() default EntityMode.POJO;
 }

hibernate-core/src/main/java/org/hibernate/annotations/Tuplizers.java

@@ -22,16 +22,21 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
 /**
- * Define a set of tuplizer for an entity or a component
+ * Grouping of tuplizers.
+ *
  * @author Emmanuel Bernard
  */
 @java.lang.annotation.Target( {ElementType.TYPE, ElementType.FIELD, ElementType.METHOD} )
 @Retention( RetentionPolicy.RUNTIME )
 public @interface Tuplizers {
+	/**
+	 * The grouping of tuplizers.
+	 */
 	Tuplizer[] value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/Type.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -30,14 +31,30 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * hibernate type
+ * Defines a Hibernate type mapping.
+ *
+ * @see org.hibernate.type.Type
+ * @see org.hibernate.usertype.UserType
+ * @see org.hibernate.usertype.CompositeUserType
+ *
+ * @see TypeDef
  *
  * @author Emmanuel Bernard
+ * @author Steve Ebersole
  */
 @Target({FIELD, METHOD})
 @Retention(RUNTIME)
 public @interface Type {
+	/**
+	 * The Hibernate type name.  Usually the fully qualified name of an implementation class for
+	 * {@link org.hibernate.type.Type}, {@link org.hibernate.usertype.UserType} or
+	 * {@link org.hibernate.usertype.CompositeUserType}.  May also refer to a type definition by name
+	 * {@link TypeDef#name()}
+	 */
 	String type();
 
+	/**
+	 * Any configuration parameters for the named type.
+	 */
 	Parameter[] parameters() default {};
 }

hibernate-core/src/main/java/org/hibernate/annotations/TypeDef.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -30,15 +31,38 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Type definition
+ * A type definition.  Much like {@link Type}, but here we can centralize the definition under a name and
+ * refer to that name elsewhere.
+ *
+ * @see org.hibernate.type.Type
+ * @see org.hibernate.usertype.UserType
+ * @see org.hibernate.usertype.CompositeUserType
+ *
+ * @see Type
  *
  * @author Emmanuel Bernard
+ * @author Steve Ebersole
  */
 @Target({TYPE, PACKAGE})
 @Retention(RUNTIME)
 public @interface TypeDef {
+	/**
+	 * The type name.  This is the name that would be used in other locations.
+	 */
 	String name() default "";
-	Class<?> defaultForType() default void.class;
+
+	/**
+	 * The type implementation class.
+	 */
 	Class<?> typeClass();
+
+	/**
+	 * Name a java type for which this defined type should be the default mapping.
+	 */
+	Class<?> defaultForType() default void.class;
+
+	/**
+	 * Any configuration parameters for this type definition.
+	 */
 	Parameter[] parameters() default {};
 }

hibernate-core/src/main/java/org/hibernate/annotations/TypeDefs.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -30,12 +31,15 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Type definition array
+ * Grouping of type definitions.
  *
  * @author Emmanuel Bernard
  */
 @Target({TYPE, PACKAGE})
 @Retention(RUNTIME)
 public @interface TypeDefs {
+	/**
+	 * The grouping of type defs.
+	 */
 	TypeDef[] value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/Where.java

@@ -22,6 +22,7 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -31,13 +32,16 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Where clause to add to the element Entity or target entity of a collection
+ * Where clause to add to the element Entity or target entity of a collection.  The clause is written in SQL.
- * The clause is written in SQL
+ * A common use case here is for soft-deletes.
  *
  * @author Emmanuel Bernard
  */
 @Target({TYPE, METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface Where {
+	/**
+	 * The where-clause predicate.
+	 */
 	String clause();
 }

hibernate-core/src/main/java/org/hibernate/annotations/WhereJoinTable.java

@@ -22,19 +22,23 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Where clause to add to the colleciton join table
+ * Where clause to add to the collection join table.  The clause is written in SQL.  Just as with
- * The clause is written in SQL
+ * {@link Where}, a common use case is for implementing soft-deletes.
  *
  * @author Emmanuel Bernard
  */
 @Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface WhereJoinTable {
+	/**
+	 * The where-clause predicate.
+	 */
 	String clause();
 }