HHH-7626 - Add javadoc to annotations

Author: sebersole

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

@@ -36,9 +36,13 @@
  * Prefer the standard {@link javax.persistence.Access} annotation
  *
  * @author Emmanuel Bernard
+ *
+ * @deprecated Use {@link AttributeAccessor} instead; renamed to avoid confusion with the JPA
+ * {@link javax.persistence.AccessType} enum.
  */
 @Target({ TYPE, METHOD, FIELD })
 @Retention(RUNTIME)
+@Deprecated
 public @interface AccessType {
 	String value();
 }

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

@@ -31,11 +31,32 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Define a ToOne association pointing to several entity types.
- * Matching the according entity type is doe through a metadata discriminator column
- * This kind of mapping should be only marginal.
- * 
+ * Defines a ToOne-style association pointing to one of several entity types depending on a local discriminator,
+ * as opposed to discriminated inheritance where the discriminator is kept as part of the entity hierarchy.
+ *
+ * For example, if you consider an Order entity containing Payment information where Payment might be of type
+ * CashPayment or CreditCardPayment the @Any approach would be to keep that discriminator and matching value on the
+ * Order itself.  Thought of another way, the "foreign-key" really is made up of the value and discriminator
+ * (there is no physical foreign key here as databases do not support this):
+ * <blockquote><pre>
+ *    &#064;Entity
+ *    class Order {
+ *        ...
+ *        &#064;Any( metaColumn = @Column( name="payment_type" ) )
+ *        &#064;AnyMetDef(
+ *                idType = "long"
+ *                metaValues = {
+ *                        &#064;MetaValue( value="C", targetEntity=CashPayment.class ),
+ *                        &#064;MetaValue( value="CC", targetEntity=CreditCardPayment.class ),
+ *                }
+ *        )
+ *        pubic Payment getPayment() { ... }
+ *    }
+ * }
+ * </pre></blockquote>
+ *
  * @author Emmanuel Bernard
+ * @author Steve Ebersole
  */
 @java.lang.annotation.Target({METHOD, FIELD})
 @Retention(RUNTIME)
@@ -48,10 +69,10 @@
 	String metaDef() default "";
 
 	/**
-	 * Metadata discriminator column description, This column will hold the meta value corresponding to the
-	 * targeted entity.
+	 * Identifies the discriminator column.  This column will hold the value that identifies the targeted entity.
 	 */
 	Column metaColumn();
+
 	/**
 	 * Defines whether the value of the field or property should be lazily loaded or must be
 	 * eagerly fetched. The EAGER strategy is a requirement on the persistence provider runtime

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

@@ -31,9 +31,12 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Defines @Any and @manyToAny metadata
+ * Used to provide metadata about an {@link Any} or {@link ManyToAny} mapping.
+ *
+ * @see AnyMetaDefs
  *
  * @author Emmanuel Bernard
+ * @author Steve Ebersole
  */
 @java.lang.annotation.Target( { PACKAGE, TYPE, METHOD, FIELD } )
 @Retention( RUNTIME )
@@ -45,18 +48,18 @@
 	String name() default "";
 
 	/**
-	 * meta discriminator Hibernate type
+	 * Names the discriminator Hibernate Type for this Any/ManyToAny mapping.  The default is to use
+	 * {@link org.hibernate.type.StringType}
 	 */
 	String metaType();
 
 	/**
-	 * Hibernate type of the id column
-	 * @return Hibernate type of the id column
+	 * Names the identifier Hibernate Type for the entity associated through this Any/ManyToAny mapping.
 	 */
 	String idType();
 
 	/**
-	 * Matching discriminator values with their respective entity
+	 * Maps discriminator values to the matching corresponding entity types.
 	 */
 	MetaValue[] metaValues();
 }

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

@@ -22,17 +22,18 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 
 import static java.lang.annotation.ElementType.PACKAGE;
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Defines @Any and @ManyToAny set of metadata.
- * Can be defined at the entity level or the package level
+ * Used to group together {@link AnyMetaDef} annotations.  Can be defined at the entity or package level
  *
  * @author Emmanuel Bernard
+ * @author Steve Ebersole
  */
 @java.lang.annotation.Target( { PACKAGE, TYPE } )
 @Retention( RUNTIME )

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

@@ -0,0 +1,61 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * Copyright (c) 2012, Red Hat Inc. or third-party contributors as
+ * indicated by the @author tags or express copyright attribution
+ * statements applied by the authors.  All third-party contributions are
+ * distributed under license by Red Hat Inc.
+ *
+ * This copyrighted material is made available to anyone wishing to use, modify,
+ * copy, or redistribute it subject to the terms and conditions of the GNU
+ * Lesser General Public License, as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this distribution; if not, write to:
+ * Free Software Foundation, Inc.
+ * 51 Franklin Street, Fifth Floor
+ * Boston, MA  02110-1301  USA
+ */
+package org.hibernate.annotations;
+
+import java.lang.annotation.Retention;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Names a {@link org.hibernate.property.PropertyAccessor} strategy to use.
+ *
+ * Can be specified at either:<ul>
+ *     <li>
+ *         <strong>TYPE</strong> level, which will act as naming the default accessor strategy for
+ *         all attributes on the class which do not explicitly name an accessor strategy
+ *     </li>
+ *     <li>
+ *         <strong>METHOD/FIELD</strong> level, which will be in effect for just that attribute.
+ *     </li>
+ * </ul>
+ *
+ * Should only be used to name custom {@link org.hibernate.property.PropertyAccessor}.  For {@code property/field}
+ * access, the JPA {@link javax.persistence.Access} annotation should be preferred using the appropriate
+ * {@link javax.persistence.AccessType}.  However, if this annotation is used with either {@code value="property"}
+ * or {@code value="field"}, it will act just as the corresponding usage of {@link javax.persistence.Access}.
+ *
+ * @author Steve Ebersole
+ * @author Emmanuel Bernard
+ */
+@java.lang.annotation.Target({ TYPE, METHOD, FIELD })
+@Retention(RUNTIME)
+public @interface AttributeAccessor {
+	/**
+	 * Names the {@link org.hibernate.property.PropertyAccessor} strategy
+	 */
+	String value();
+}

hibernate-core/src/main/java/org/hibernate/annotations/BatchSize.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,31 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Batch size for SQL loading
+ * Defines size for batch loading of collections or lazy entities.  For example...
+ * <blockquote><pre>
+ *     &#064;Entity
+ *     &#064;BatchSize(size=100)
+ *     class Product {
+ *         ...
+ *     }
+ * </pre></blockquote>
+ * will initialize up to 100 lazy Product entity proxies at a time.
+ *
+ * <blockquote><pre>
+ *     	&#064;OneToMany
+ *     	&#064;BatchSize(size = 5) /
+ *     	Set<Product> getProducts() { ... };
+ * </pre></blockquote>
+ * will initialize up to 5 lazy collections of products at a time
  *
  * @author Emmanuel Bernard
+ * @author Steve Ebersole
  */
 @Target({TYPE, METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface BatchSize {
-	/** Strictly positive integer */
+	/**
+	 * Strictly positive integer
+	 */
 	int size();
 }

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

@@ -30,7 +30,12 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Apply a cascade strategy on an association
+ * Apply a cascade strategy on an association.  Used to apply Hibernate specific cascades.  For JPA cascading, prefer
+ * using {@link javax.persistence.CascadeType} on {@link javax.persistence.OneToOne},
+ * {@link javax.persistence.OneToMany}, etc.  Hibernate will merge together both sets of cascades.
+ *
+ * @author Emmanuel Bernard
+ * @author Steve Ebersole
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)

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

@@ -25,7 +25,7 @@
 
 
 /**
- * Cascade types (can override default EJB3 cascades
+ * Cascade types (can override default JPA cascades
  */
 public enum CascadeType {
 	ALL,

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

@@ -31,8 +31,7 @@
 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
  */

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

@@ -30,7 +30,8 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Names a custom collection type for a persistent collection.
+ * Names a custom collection type for a persistent collection.  The collection can also name a @Type, which defines
+ * the Hibernate Type of the collection elements.
  *
  * @see org.hibernate.type.CollectionType
  * @see org.hibernate.usertype.UserCollectionType

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

@@ -34,7 +34,9 @@
  * The write expression must contain exactly one '?' placeholder for the value. 
  *
  * For example: <code>read="decrypt(credit_card_num)" write="encrypt(?)"</code>
- *  
+ *
+ * @see ColumnTransformers
+ *
  * @author Emmanuel Bernard
  */
 @java.lang.annotation.Target({FIELD,METHOD})

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

@@ -29,11 +29,15 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Discriminator formula
- * To be placed at the root entity.
+ * Used to apply a Hibernate formula (derived value) as the inheritance discriminator "column".  Used in place of
+ * the JPA {@link javax.persistence.DiscriminatorColumn} when a formula is wanted.
+ *
+ * To be placed on the root entity.
  *
- * @author Emmanuel Bernard
  * @see Formula
+ *
+ * @author Emmanuel Bernard
+ * @author Steve Ebersole
  */
 @Target({TYPE})
 @Retention(RUNTIME)

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

@@ -30,10 +30,34 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Formula. To be used as a replacement for @Column in most places
- * The formula has to be a valid SQL fragment
+ * Defines a formula (derived value) which is a SQL fragment that acts as a @Column alternative in most cases.
+ * Represents read-only state.
+ *
+ * In certain cases @ColumnTransformer might be a better option, especially as it leaves open the option of still
+ * being writable.
+ *
+ * <blockquote><pre>
+ *     // perform calculations
+ *     &#064;Formula( "sub_total + (sub_total * tax)" )
+ *     long getTotalCost() { ... }
+ * </pre></blockquote>
+ *
+ * <blockquote><pre>
+ *     // call functions
+ *     &#064;Formula( "upper( substring( middle_name, 1 ) )" )
+ *     Character getMiddleInitial() { ... }
+ * </pre></blockquote>
+ *
+ * <blockquote><pre>
+ *     // this might be better handled through @ColumnTransformer
+ *     &#064;Formula( "decrypt(credit_card_num)" )
+ *     String getCreditCardNumber() { ... }
+ * </pre></blockquote>
+ *
+ * @see ColumnTransformer
  *
  * @author Emmanuel Bernard
+ * @author Steve Ebersole
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)

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

@@ -22,20 +22,23 @@
  * Boston, MA  02110-1301  USA
  */
 package org.hibernate.annotations;
-import java.lang.annotation.Retention;
+
 import javax.persistence.Column;
 import javax.persistence.FetchType;
+import java.lang.annotation.Retention;
 
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Defined a ToMany association pointing to different entity types.
- * Matching the according entity type is doe through a metadata discriminator column
- * This kind of mapping should be only marginal.
+ * This is the collection-valued form of @Any definitions.  Defines a ToMany-style association pointing
+ * to one of several entity types depending on a local discriminator.  See {@link Any} for further information.
+ *
+ * @see Any
  *
  * @author Emmanuel Bernard
+ * @author Steve Ebersole
  */
 @java.lang.annotation.Target({METHOD, FIELD})
 @Retention(RUNTIME)

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

@@ -23,10 +23,13 @@
  */
 package org.hibernate.annotations;
 
-
 /**
- * Represent a discriminator value associated to a given entity type
+ * Maps a given discriminator value to the corresponding entity type.  See {@link Any} for more information.
+ *
+ * @see Any
+ *
  * @author Emmanuel Bernard
+ * @author Steve Ebersole
  */
 public @interface MetaValue {
 	/**