DATACASS-585 - Document relationship between @PrimaryKeyColumn and @Id.

Document that using PrimaryKeyColumn does not mark properties as Id properties.

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 })

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)

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 })

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