From 9e825d376efecb07c21a6943ad1194f160bf6534 Mon Sep 17 00:00:00 2001
From: Mark Paluch <mpaluch@pivotal.io>
Date: Wed, 30 Jan 2019 09:51:08 +0100
Subject: [PATCH] DATACASS-585 - Document relationship between
 @PrimaryKeyColumn and @Id.

Document that using PrimaryKeyColumn does not mark properties as Id properties.
---
 .../data/cassandra/core/mapping/PrimaryKey.java            | 5 +++++
 .../data/cassandra/core/mapping/PrimaryKeyClass.java       | 2 ++
 .../data/cassandra/core/mapping/PrimaryKeyColumn.java      | 7 ++++++-
 src/main/asciidoc/reference/mapping.adoc                   | 2 +-
 4 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/PrimaryKey.java b/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/PrimaryKey.java
index 137ff52bd..b8a4d32c2 100644
--- a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/PrimaryKey.java
+++ b/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/PrimaryKey.java
@@ -29,9 +29,14 @@ import org.springframework.data.annotation.Id;
  * <p/>
  * Remember, if the Cassandra table has multiple primary key columns, then you must define a class annotated with
  * {@link PrimaryKeyClass} to represent the primary key!
+ * <p/>
+ * Use {@link PrimaryKeyColumn} in conjunction with {@link Id} to specify extended primary key column properties.
  *
  * @author Alex Shvid
  * @author Matthew T. Adams
+ * @author Mark Paluch
+ * @see Id
+ * @see PrimaryKeyColumn
  */
 @Retention(value = RetentionPolicy.RUNTIME)
 @Target(value = { ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.METHOD })
diff --git a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/PrimaryKeyClass.java b/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/PrimaryKeyClass.java
index b191bb4f5..d35be0041 100644
--- a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/PrimaryKeyClass.java
+++ b/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/PrimaryKeyClass.java
@@ -31,6 +31,8 @@ import org.springframework.data.annotation.Persistent;
  *
  * @author Alex Shvid
  * @author Matthew T. Adams
+ * @author Mark Paluch
+ * @see PrimaryKeyColumn
  */
 @Inherited
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/PrimaryKeyColumn.java b/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/PrimaryKeyColumn.java
index 1915cf5cf..de744b318 100644
--- a/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/PrimaryKeyColumn.java
+++ b/spring-data-cassandra/src/main/java/org/springframework/data/cassandra/core/mapping/PrimaryKeyColumn.java
@@ -26,10 +26,15 @@ import org.springframework.data.cassandra.core.cql.PrimaryKeyType;
 
 /**
  * Identifies the annotated field of a composite primary key class as a primary key field that is either a partition or
- * cluster key field.
+ * cluster key field. Annotated properties must be either reside in a {@link PrimaryKeyClass} to be part of the
+ * composite key or annotated with {@link org.springframework.data.annotation.Id} to identify a single property as
+ * primary key column.
  *
  * @author Matthew T. Adams
  * @author Mark Paluch
+ * @see org.springframework.data.annotation.Id
+ * @see PrimaryKey
+ * @see PrimaryKeyClass
  */
 @Retention(value = RetentionPolicy.RUNTIME)
 @Target(value = { ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.METHOD })
diff --git a/src/main/asciidoc/reference/mapping.adoc b/src/main/asciidoc/reference/mapping.adoc
index b362a8a7d..0111a3fc0 100644
--- a/src/main/asciidoc/reference/mapping.adoc
+++ b/src/main/asciidoc/reference/mapping.adoc
@@ -410,7 +410,7 @@ You can specify the name of the table where the object is stored.
 * `@PrimaryKey`: Similar to `@Id` but lets you specify the column name.
 * `@PrimaryKeyColumn`: Cassandra-specific annotation for primary key columns that lets you specify
 primary key column attributes, such as for clustered or partitioned. Can be used on single and multiple attributes
-to indicate either a single or a composite (compound) primary key.
+to indicate either a single or a composite (compound) primary key. If used on a property within the entity, make sure to apply the `@Id` annotation as well.
 * `@PrimaryKeyClass`: Applied at the class level to indicate that this class is a compound primary key class.
 Must be referenced with `@PrimaryKey` in the entity class.
 * `@Transient`: By default, all private fields are mapped to the row. This annotation excludes the field