very minor changes to javadoc

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

@@ -18,16 +18,13 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Marks certain of packages, types, etc. as incubating, potentially
- * recursively.  Incubating indicates something that is still being
- * actively developed and therefore may change at a later time; a
- * "tech preview".
- * <p>
- * Users of these types and methods are considered early adopters who
- * help shape the final definition of these types/methods, along with
- * the needs of consumers.
+ * Marks the annotated Java element as <em>incubating</em>, potentially
+ * recursively. An incubating API is one which is still being actively
+ * developed and therefore may change at a later time; a "tech preview".
+ * The user of such an API is considered an early adopter who helps shape
+ * the final definition of the API.
  *
- * @implNote Defined with RUNTIME retention so tooling can see it
+ * @implNote Defined with {@code RUNTIME} retention so tooling can see it
  *
  * @author Steve Ebersole
  */

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

@@ -17,9 +17,13 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Annotation used to identify a package, class, interface or method
- * as "internal", meaning that applications should expect no guarantees
- * with regard to the binary stability from release to release.
+ * Marks the annotated Java element as forming part of the <em>internal</em>
+ * implementation of Hibernate, meaning that clients should expect absolutely
+ * no guarantees with regard to the binary stability from release to release.
+ * The user of such an API is embracing the potential for their program to
+ * break with any point release of Hibernate.
+ *
+ * @implNote Defined with {@code RUNTIME} retention so tooling can see it
  *
  * @author Steve Ebersole
  */

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

@@ -19,12 +19,13 @@ import static java.lang.annotation.ElementType.TYPE_USE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Indicates that the annotated element is planned for removal as part
- * of a deprecation lifecycle.
+ * Indicates that the annotated element is planned for removal as part of a
+ * deprecation process.
  *
- * @apiNote Intended for use at development-time for developers to better understand
- * the lifecycle of the annotated element.  Also, useful for "deprecating" a package
- * as the Java compiler does not like `@Deprecated` on packages.
+ * @apiNote Intended for use at development time for developers to better
+ * understand the lifecycle of the annotated element. Also, useful for
+ * deprecating a whole package, since the Java compiler does not accept
+ * the {@link Deprecated @Deprecated} annotation on packages.
  *
  * @see Deprecated#forRemoval()
  *