HHH-19965 remove misleading examples from the User Guide

@OrderColumn is like @MapKeyColumn. It's not supposed to
be used on the unowned side of an association.

Author: gavinking

documentation/src/main/asciidoc/introduction/Advanced.adoc

@@ -886,6 +886,17 @@ On the other hand, the following annotations specify how a collection should be
 
 Under the covers, Hibernate uses a `TreeSet` or `TreeMap` to maintain the collection in sorted order.
 
+[CAUTION]
+====
+The unowned (`mappedBy`) side of a bidirectional association is not responsible for specifying column mappings.
+So it's wrong in principle to use `@OrderColumn` or `@MapKeyColumn` on the unowned side of an association mapping.
+But for unowned collections, we may use `@OrderBy` or `@MapKey` instead.
+That is:
+
+- You can use `@OrderColumn` or `@MapKeyColumn` with an `@ElementCollection`, owned `@ManyToMany`, or owned `@OneToMany`.
+- But use `@OrderBy` or `@MapKey` when it's an _unowned_ `@ManyToMany` or `@OneToMany`.
+====
+
 [[any]]
 === Any mappings
 

documentation/src/main/asciidoc/userguide/chapters/domain/collections.adoc

@@ -683,7 +683,9 @@ include::{extrasdir}/collections-unidirectional-ordered-list-order-column-select
 ----
 ====
 
-With the `order_id` column in place, Hibernate can order the list in-memory after it's being fetched from the database.
+With the `order_id` column in place, Hibernate can order the list in-memory after it's fetched from the database.
+
+The <<collection-list-indexbase-ex,`@ListIndexBase` annotation>> may be used to choose between 0-based and 1-based indexing on the database side.
 
 [[collections-bidirectional-ordered-list]]
 ===== Bidirectional ordered lists
@@ -701,54 +703,6 @@ include::{example-dir-collection}/BidirectionalOrderByListTest.java[tags=collect
 
 Just like with the unidirectional `@OrderBy` list, the `number` column is used to order the statement on the SQL level.
 
-When using the `@OrderColumn` annotation, the `order_id` column is going to be embedded in the child table:
-
-[[collections-bidirectional-ordered-list-order-column-example]]
-.Bidirectional `@OrderColumn` list
-====
-[source,java]
-----
-include::{example-dir-collection}/BidirectionalOrderColumnListTest.java[tags=collections-bidirectional-ordered-list-order-column-example,indent=0]
-----
-
-[source,sql]
-----
-include::{extrasdir}/collections-bidirectional-ordered-list-order-column-example.sql[]
-----
-====
-
-When fetching the collection, Hibernate will use the fetched ordered columns to sort the elements according to the `@OrderColumn` mapping.
-
-[[collections-customizing-ordered-list-ordinal]]
-===== Customizing ordered list ordinal
-
-You can customize the ordinal of the underlying ordered list by using the https://docs.hibernate.org/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/ListIndexBase.html[`@ListIndexBase`] annotation.
-
-[[collections-customizing-ordered-list-ordinal-mapping-example]]
-.`@ListIndexBase` mapping example
-====
-[source,java]
-----
-include::{example-dir-collection}/OrderColumnListIndexBaseTest.java[tags=collections-customizing-ordered-list-ordinal-mapping-example,indent=0]
-----
-====
-
-When inserting two `Phone` records, Hibernate is going to start the List index from 100 this time.
-
-[[collections-customizing-ordered-list-ordinal-persist-example]]
-.`@ListIndexBase` persist example
-====
-[source,java]
-----
-include::{example-dir-collection}/OrderColumnListIndexBaseTest.java[tags=collections-customizing-ordered-list-ordinal-persist-example,indent=0]
-----
-
-[source,sql]
-----
-include::{extrasdir}/collections-customizing-ordered-list-ordinal-persist-example.sql[]
-----
-====
-
 [[collections-customizing-ordered-by-sql-clause]]
 ===== Customizing ORDER BY SQL clause