mention all the ways @onDelete(CASCADE) can be used in the javadoc

Author: gavinking

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

@@ -20,15 +20,44 @@
  * @OnDelete(action = CASCADE)
  * Parent parent;
  * </pre>
- * Note that this results in an {@code on delete cascade} clause in
- * the DDL definition of the foreign key. It's completely different
- * to {@link jakarta.persistence.CascadeType#REMOVE}.
+ * This annotation results in an {@code on delete cascade} clause in
+ * the DDL definition of the foreign key.
  * <p>
- * In fact, {@code @OnDelete} may be combined with {@code cascade=REMOVE}.
+ * The {@code @OnDelete} annotation may be applied to any field or
+ * property representing an association or collection, or to a subclass
+ * in a {@linkplain jakarta.persistence.InheritanceType#JOINED joined}
+ * inheritance hierarchy.
  * <pre>
- * &#064;ManyToOne(cascade = REMOVE)
+ * &#064;Entity
+ * &#064;Inheritance(strategy = JOINED)
+ * class Publication {
+ *     &#064;Id
+ *     long id;
+ *     ...
+ *     &#064;ElementCollection
+ *     &#064;OnDelete(action = CASCADE)
+ *     String&lt;String&gt; keywords;
+ * }
+ *
+ * &#064;Entity
  * &#064;OnDelete(action = CASCADE)
- * Parent parent;
+ * class Book extends Publication {
+ *     &#064;Column(unique = true);
+ *     String isbn;
+ *     ...
+ *     &#064;ManyToMany
+ *     &#064;OnDelete(action = CASCADE)
+ *     Set&lt;Author&gt; authors;
+ * }
+ * </pre>
+ * <p>
+ * The affect of {@code @OnDelete(action = CASCADE)} is quite different
+ * to {@link jakarta.persistence.CascadeType#REMOVE}. In fact,
+ * {@code @OnDelete} may be combined with {@code cascade=REMOVE}.
+ * <pre>
+ * &#064;OneToMany(mappedBy = Child_.parent, cascade = {PERSIST, REMOVE})
+ * &#064;OnDelete(action = CASCADE)
+ * Set&lt;Child&gt; children = new HashSet<>();
  * </pre>
  * <ul>
  * <li>If {@code @OnDelete(action = CASCADE)} is used in conjunction