HHH-4933 deprecate legacy annotations, document @ElementCollection, reorganize collection description, remove legacy annotations documentation when a new one is in place

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@18915 1b8cb986-b30d-0410-93ca-fae66ebed9b2

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

@@ -34,6 +34,8 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 /**
  * Property Access type
  *
+ * Prefer the standard {@link javax.persistence.Access} annotation
+ *
  * @author Emmanuel Bernard
  */
 @Target({ TYPE, METHOD, FIELD })

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

@@ -35,9 +35,11 @@ public enum CascadeType {
 	DELETE,
 	SAVE_UPDATE,
 	REPLICATE,
+	/** @deprecated use @OneToOne(orphanRemoval=true) or @OneToMany(orphanRemoval=true) */
+	@Deprecated
 	DELETE_ORPHAN,
 	LOCK,
-	/** @deprecated use DETACH */
+	/** @deprecated use javax.persistence.CascadeType.DETACH */
 	@Deprecated
 	EVICT,
 	DETACH

annotations/src/main/java/org/hibernate/annotations/CollectionOfElements.java

@@ -35,10 +35,12 @@ import static javax.persistence.FetchType.LAZY;
  * Annotation used to mark a collection as a collection of elements or
  * a collection of embedded objects
  *
+ * @deprecated use @ElementCollection
  * @author Emmanuel Bernard
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
+@Deprecated
 public @interface CollectionOfElements {
 	/**
 	 * Represent the element class in the collection

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

@@ -31,6 +31,7 @@ import java.lang.annotation.Target;
 
 /**
  * Describe an index column of a List
+ * Prefer the standard {@link javax.persistence.OrderColumn} annotation
  *
  * @author Matthew Inger
  */