Firestore: update javadocs of Exclude, PropertyName, and ServerTimestamp to explicitly document using the @get and/or @set use-site targets on Kotlin properties (#6612)

Author: dconeybe

firebase-firestore/src/main/java/com/google/firebase/firestore/DocumentId.java

@@ -43,6 +43,21 @@
  * WriteBatch#set(DocumentReference, Object)}), the property annotated by {@code @DocumentId} is
  * ignored, which allows writing the POJO back to any document, even if it's not the origin of the
  * POJO.
+ *
+ * <h3>Kotlin Note</h3>
+ * When applying this annotation to a property of a Kotlin class, the {@code @set} use-site target
+ * should always be used. There is no need to use the {@code @get} use-site target as this
+ * annotation is <em>only</em> considered when <em>reading</em> instances from Firestore, and is
+ * ignored when <em>writing</em> instances into Firestore.
+ * <p>
+ * Here is an example of a class that can both be written into and read from Firestore whose
+ * {@code foo} property will be populated with the Document ID when being read and will be ignored
+ * when being written into Firestore:
+ * <pre>
+ * data class Pojo(@set:DocumentId var foo: String? = null) {
+ *   constructor() : this(null) // Used by Firestore to create new instances
+ * }
+ * </pre>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.FIELD, ElementType.METHOD})

firebase-firestore/src/main/java/com/google/firebase/firestore/Exclude.java

@@ -19,7 +19,31 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-/** Marks a field as excluded from the database instance. */
+/**
+ * Marks a field as excluded from the database instance.
+ *
+ * <h3>Kotlin Note</h3>
+ * When applying this annotation to a property of a Kotlin class, the {@code @get} use-site target
+ * should always be used. There is no need to use the {@code @set} use-site target as this
+ * annotation is <em>only</em> considered when <em>writing</em> instances into Firestore, and is
+ * ignored when <em>reading</em> instances from Firestore.
+ * <p>
+ * Here is an example of a class that can both be written into and read from Firestore whose
+ * {@code bar} property will never be written into Firestore:
+ * <pre>
+ * data class Pojo(var foo: String? = null, @get:Exclude var bar: String? = null) {
+ *   constructor() : this(null, null) // Used by Firestore to create new instances
+ * }
+ * </pre>
+ * <p>
+ * If the class only needs to be <em>written</em> into Firestore (and not read from Firestore) then
+ * the class can be simplified as follows:
+ * <pre>
+ * data class Pojo(val foo: String? = null, @get:Exclude val bar: String? = null)
+ * </pre>
+ * That is, {@code var} can be tightened to {@code val} and the secondary no-argument constructor
+ * can be omitted.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.METHOD, ElementType.FIELD})
 public @interface Exclude {}

firebase-firestore/src/main/java/com/google/firebase/firestore/PropertyName.java

@@ -19,7 +19,30 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-/** Marks a field to be renamed when serialized. */
+/**
+ * Marks a field to be renamed when serialized.
+ *
+ * <h3>Kotlin Note</h3>
+ * When applying this annotation to a property of a Kotlin class, both the {@code @get} and
+ * {@code @set} use-site targets should be used.
+ * <p>
+ * Here is an example of a class that can both be written into and read from Firestore whose
+ * {@code foo} property will be stored into and read from a field named {@code my_foo} in the
+ * Firestore document:
+ * <pre>
+ * data class Pojo(@get:PropertyName("my_foo") @set:PropertyName("my_foo") var foo: String? = null) {
+ *   constructor() : this(null) // Used by Firestore to create new instances
+ * }
+ * </pre>
+ * <p>
+ * If the class only needs to be <em>written</em> into Firestore (and not read from Firestore) then
+ * the class can be simplified as follows:
+ * <pre>
+ * data class Pojo(@get:PropertyName("my_foo") val foo: String? = null)
+ * </pre>
+ * That is, {@code var} can be tightened to {@code val}, the secondary no-argument constructor can
+ * be omitted, and the {@code @set} use-site target can be omitted.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.METHOD, ElementType.FIELD})
 public @interface PropertyName {

firebase-firestore/src/main/java/com/google/firebase/firestore/ServerTimestamp.java

@@ -23,6 +23,29 @@
  * Annotation used to mark a timestamp field to be populated with a server timestamp. If a POJO
  * being written contains {@code null} for a @ServerTimestamp-annotated field, it will be replaced
  * with a server-generated timestamp.
+ *
+ * <h3>Kotlin Note</h3>
+ * When applying this annotation to a property of a Kotlin class, the {@code @get} use-site target
+ * should always be used. There is no need to use the {@code @set} use-site target as this
+ * annotation is <em>only</em> considered when <em>writing</em> instances into Firestore, and is
+ * ignored when <em>reading</em> instances from Firestore.
+ * <p>
+ * Here is an example of a class that can both be written into and read from Firestore whose
+ * {@code foo} property will be populated with the server timestamp in Firestore if its value is
+ * null:
+ * <pre>
+ * data class Pojo(@get:ServerTimestamp var foo: Timestamp? = null) {
+ *   constructor() : this(null) // Used by Firestore to create new instances
+ * }
+ * </pre>
+ * <p>
+ * If the class only needs to be <em>written</em> into Firestore (and not read from Firestore) then
+ * the class can be simplified as follows:
+ * <pre>
+ * data class Pojo(@get:ServerTimestamp val foo: Timestamp? = null)
+ * </pre>
+ * That is, {@code var} can be tightened to {@code val} and the secondary no-argument constructor
+ * can be omitted.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.METHOD, ElementType.FIELD})