improve javadoc of @id annotation

this is a very important API, and it was barely documented!

Signed-off-by: Gavin King <[email protected]>

api/src/main/java/jakarta/persistence/Id.java

@@ -23,33 +23,64 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Identifies the primary key of an entity.
+ * Identifies the primary key field or property of an entity class.
+ * Every entity must have a primary key. The primary key must be
+ * declared by:
+ * <ul>
+ * <li>the entity class that is the root of the entity hierarchy, or
+ * <li>a mapped superclass that is a (direct or indirect) superclass
+ *     of all entity classes in the entity hierarchy.
+ * </ul>
+ * A primary key must be defined exactly once in each entity hierarchy.
  *
  * <p>The field or property to which the {@code Id} annotation is
  * applied should have one of the following types:
- * any Java primitive type;
- * any primitive wrapper type;
- * {@link String};
- * {@link java.util.UUID};
- * {@link java.util.Date};
- * {@link java.sql.Date};
- * {@link java.math.BigDecimal};
- * {@link java.math.BigInteger}.
+ * <ul>
+ * <li>a Java primitive type, or wrapper of a primitive type,
+ * <li>{@link String},
+ * <li>{@link java.util.UUID},
+ * <li>{@link java.util.Date},
+ * <li>{@link java.sql.Date},
+ * <li>{@link java.math.BigDecimal}, or
+ * <li>{@link java.math.BigInteger}.
+ * </ul>
  *
  * <p>The mapped column for the primary key of the entity is assumed 
  * to be the primary key of the primary table. If no {@link Column}
  * annotation is specified, the primary key column name is assumed to
  * be the name of the primary key property or field.
  *
- * <p>Example:
+ * <p>For example, this field holds a generated primary key assigned
+ * by the persistence provider:
+ * {@snippet :
+ * @Id @GeneratedValue
+ * UUID uuid;
+ * }
+ *
+ * <p>This property holds a primary key assigned by the application:
  * {@snippet :
  * @Id
- * public Long getId() { return id; }
+ * public String getIsbn() {
+ *     return isbn;
  * }
  *
+ * public void setIsbn(String isbn) {
+ *     this.isbn = isbn;
+ * }
+ * }
+ * <p>An entity must declare or inherit exactly one field or property
+ * annotated {@code @Id} or {@link EmbeddedId @EmbeddedId} unless the
+ * entity specifies an {@link IdClass @IdClass}, in which case the
+ * entity must have a field or property annotated {@code @Id} for
+ * each field or property of its id class.
+ *
+ * <p>The {@code @Id} annotation should never be applied to a field
+ * or property of an embeddable id or id class.
+ *
  * @see Column
  * @see GeneratedValue
  * @see EmbeddedId
+ * @see IdClass
  * @see PersistenceUnitUtil#getIdentifier(Object)
  *
  * @since 1.0