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

Author: dconeybe

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</code> use-site
+ * target should always be used. There is no need to use the <code>@set</code> 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</code> 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</code> can be tightened to <code>val</code> 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,34 @@
 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</code> and
+ * <code>@set</code> 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</code> property will be stored into and read from a field named "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</code> can be tightened to <code>val</code>, the secondary no-argument
+ * constructor can be omitted, and the <code>@set</code> 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</code> use-site
+ * target should always be used. There is no need to use the <code>@set</code> 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</code> 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</code> can be tightened to <code>val</code> and the secondary no-argument
+ * constructor can be omitted.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.METHOD, ElementType.FIELD})