HHH-17441 - Deprecate @Comment

gradle/javadoc.gradle

@@ -45,10 +45,11 @@ tasks.named( "javadoc", Javadoc ) {
         linksOffline 'https://www.javadoc.io/doc/javax.cache/cache-api/1.0.0/', "${project.rootDir}/javadoc/javax-cache-1.0"
 
         tags(
-                'todo:X',
                 'apiNote:a:API Note:',
                 'implSpec:a:Implementation Specification:',
                 'implNote:a:Implementation Note:',
+                'todo:X',
+                'remove:a:Removal (deprecation):',
                 'settingDefault:f:Default Value:'
         )
 

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

@@ -6,6 +6,7 @@
  */
 package org.hibernate.annotations;
 
+import org.hibernate.Remove;
 import org.hibernate.binder.internal.CommentBinder;
 
 import java.lang.annotation.Repeatable;
@@ -47,12 +48,15 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  *
  * @author Yanming Zhou
  * @author Gavin King
+ *
+ * @remove JPA 3.2 adds a comment attribute to {@linkplain jakarta.persistence.Table}
  */
 @TypeBinderType(binder = CommentBinder.class)
 @AttributeBinderType(binder = CommentBinder.class)
 @Target({METHOD, FIELD, TYPE})
 @Retention(RUNTIME)
 @Repeatable(Comments.class)
+@Remove
 public @interface Comment {
 	/**
 	 * The text of the comment.

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

@@ -6,6 +6,7 @@
  */
 package org.hibernate.annotations;
 
+import org.hibernate.Remove;
 import org.hibernate.binder.internal.CommentBinder;
 import org.hibernate.binder.internal.CommentsBinder;
 
@@ -24,11 +25,14 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * they must have distinct {@link Comment#on() on} members.
  *
  * @author Gavin King
+ *
+ * @remove JPA 3.2 adds a comment attribute to {@linkplain jakarta.persistence.Table}
  */
 @TypeBinderType(binder = CommentsBinder.class)
 @AttributeBinderType(binder = CommentsBinder.class)
 @Target({METHOD, FIELD, TYPE})
 @Retention(RUNTIME)
+@Remove
 public @interface Comments {
 	Comment[] value();
 }