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

dconeybe · 2025-01-02T20:47:51Z

…amp to explicitly document using the `@get` and/or `@set` use-site targets on Kotlin properties.

github-actions · 2025-01-02T20:48:04Z

Javadoc Changes:

--- /home/runner/diff/original/firebase-kotlindoc/android/com/google/firebase/firestore/DocumentId.html	2025-01-03 16:36:21.480169669 +0000
+++ /home/runner/diff/modified/firebase-kotlindoc/android/com/google/firebase/firestore/DocumentId.html	2025-01-03 16:33:24.225285841 +0000
@@ -20,6 +20,13 @@
       <li></li>
     </ul>
     <p>When using a POJO to write to a document (via <code><a href="/docs/reference/android/com/google/firebase/firestore/DocumentReference.html#set(java.lang.Object)">set</a></code> or @<code><a href="/docs/reference/android/com/google/firebase/firestore/WriteBatch.html#set(com.google.firebase.firestore.DocumentReference,java.lang.Object)">set</a></code>), the property annotated by <code>@DocumentId</code> is ignored, which allows writing the POJO back to any document, even if it's not the origin of the POJO.</p>
+    <h3>Kotlin Note</h3>
+ When applying this annotation to a property of a Kotlin class, the <code>@set</code> use-site target should always be used. There is no need to use the <code>@get</code> 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</code> property will be populated with the Document ID when being read and will be ignored when being written into Firestore: </p>
+    <pre class="prettyprint">data class Pojo(@set:DocumentId var foo: String? = null) {
+  constructor() : this(null) // Used by Firestore to create new instances
+}
+</pre>
   </body>
 </html>

--- /home/runner/diff/original/firebase-kotlindoc/android/com/google/firebase/firestore/Exclude.html	2025-01-03 16:36:21.484169667 +0000
+++ /home/runner/diff/modified/firebase-kotlindoc/android/com/google/firebase/firestore/Exclude.html	2025-01-03 16:33:24.225285841 +0000
@@ -12,6 +12,16 @@
     </p>
     <hr>
     <p>Marks a field as excluded from the database instance.</p>
-  </body>
+    <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: </p>
+    <pre class="prettyprint">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: </p>
+    <pre class="prettyprint">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.</body>
 </html>

--- /home/runner/diff/original/firebase-kotlindoc/android/com/google/firebase/firestore/PropertyName.html	2025-01-03 16:36:21.455169684 +0000
+++ /home/runner/diff/modified/firebase-kotlindoc/android/com/google/firebase/firestore/PropertyName.html	2025-01-03 16:33:24.221285845 +0000
@@ -12,6 +12,17 @@
     </p>
     <hr>
     <p>Marks a field to be renamed when serialized.</p>
+    <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 <code>my_foo</code> in the Firestore document: </p>
+    <pre class="prettyprint">data class Pojo(@get:PropertyName(&quot;my_foo&quot;) @set:PropertyName(&quot;my_foo&quot;) 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: </p>
+    <pre class="prettyprint">data class Pojo(@get:PropertyName(&quot;my_foo&quot;) 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.
     <h2>Summary</h2>
     <div class="devsite-table-wrapper">
       <table class="responsive">

--- /home/runner/diff/original/firebase-kotlindoc/android/com/google/firebase/firestore/ServerTimestamp.html	2025-01-03 16:36:21.484169667 +0000
+++ /home/runner/diff/modified/firebase-kotlindoc/android/com/google/firebase/firestore/ServerTimestamp.html	2025-01-03 16:33:24.225285841 +0000
@@ -12,6 +12,16 @@
     </p>
     <hr>
     <p>Annotation used to mark a timestamp field to be populated with a server timestamp. If a POJO being written contains <code>null</code> for a @ServerTimestamp-annotated field, it will be replaced with a server-generated timestamp.</p>
-  </body>
+    <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: </p>
+    <pre class="prettyprint">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: </p>
+    <pre class="prettyprint">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.</body>
 </html>

--- /home/runner/diff/original/firebase-kotlindoc/kotlin/com/google/firebase/firestore/DocumentId.html	2025-01-03 16:36:21.525169642 +0000
+++ /home/runner/diff/modified/firebase-kotlindoc/kotlin/com/google/firebase/firestore/DocumentId.html	2025-01-03 16:33:24.236285833 +0000
@@ -20,6 +20,13 @@
       <li></li>
     </ul>
     <p>When using a POJO to write to a document (via <code><a href="/docs/reference/kotlin/com/google/firebase/firestore/DocumentReference.html#set(java.lang.Object)">set</a></code> or @<code><a href="/docs/reference/kotlin/com/google/firebase/firestore/WriteBatch.html#set(com.google.firebase.firestore.DocumentReference,java.lang.Object)">set</a></code>), the property annotated by <code>@DocumentId</code> is ignored, which allows writing the POJO back to any document, even if it's not the origin of the POJO.</p>
+    <h3>Kotlin Note</h3>
+ When applying this annotation to a property of a Kotlin class, the <code>@set</code> use-site target should always be used. There is no need to use the <code>@get</code> 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</code> property will be populated with the Document ID when being read and will be ignored when being written into Firestore: </p>
+    <pre class="prettyprint">data class Pojo(@set:DocumentId var foo: String? = null) {
+  constructor() : this(null) // Used by Firestore to create new instances
+}
+</pre>
   </body>
 </html>

--- /home/runner/diff/original/firebase-kotlindoc/kotlin/com/google/firebase/firestore/Exclude.html	2025-01-03 16:36:21.525169642 +0000
+++ /home/runner/diff/modified/firebase-kotlindoc/kotlin/com/google/firebase/firestore/Exclude.html	2025-01-03 16:33:24.236285833 +0000
@@ -12,6 +12,16 @@
     </p>
     <hr>
     <p>Marks a field as excluded from the database instance.</p>
-  </body>
+    <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: </p>
+    <pre class="prettyprint">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: </p>
+    <pre class="prettyprint">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.</body>
 </html>

--- /home/runner/diff/original/firebase-kotlindoc/kotlin/com/google/firebase/firestore/PropertyName.html	2025-01-03 16:36:21.498169658 +0000
+++ /home/runner/diff/modified/firebase-kotlindoc/kotlin/com/google/firebase/firestore/PropertyName.html	2025-01-03 16:33:24.229285838 +0000
@@ -12,6 +12,17 @@
     </p>
     <hr>
     <p>Marks a field to be renamed when serialized.</p>
+    <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 <code>my_foo</code> in the Firestore document: </p>
+    <pre class="prettyprint">data class Pojo(@get:PropertyName(&quot;my_foo&quot;) @set:PropertyName(&quot;my_foo&quot;) 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: </p>
+    <pre class="prettyprint">data class Pojo(@get:PropertyName(&quot;my_foo&quot;) 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.
     <h2>Summary</h2>
     <div class="devsite-table-wrapper">
       <table class="responsive">

--- /home/runner/diff/original/firebase-kotlindoc/kotlin/com/google/firebase/firestore/ServerTimestamp.html	2025-01-03 16:36:21.525169642 +0000
+++ /home/runner/diff/modified/firebase-kotlindoc/kotlin/com/google/firebase/firestore/ServerTimestamp.html	2025-01-03 16:33:24.236285833 +0000
@@ -12,6 +12,16 @@
     </p>
     <hr>
     <p>Annotation used to mark a timestamp field to be populated with a server timestamp. If a POJO being written contains <code>null</code> for a @ServerTimestamp-annotated field, it will be replaced with a server-generated timestamp.</p>
-  </body>
+    <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: </p>
+    <pre class="prettyprint">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: </p>
+    <pre class="prettyprint">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.</body>
 </html>

github-actions · 2025-01-02T20:48:09Z

Vertex AI Mock Responses Check ⚠️

A newer major version of the mock responses for Vertex AI unit tests is available. update_responses.sh should be updated to clone the latest version of the responses: v5.3

google-oss-bot · 2025-01-02T20:54:09Z

Coverage Report ¹

Affected Products

firebase-firestore
Overall coverage changed from 45.73% (320a3ed) to 45.72% (feb597e) by -0.01%.
Filename Base (320a3ed) Merge (feb597e) Diff
DeleteMutation.java 95.24% 90.48% -4.76%
LruGarbageCollector.java 97.27% 93.64% -3.64%
PatchMutation.java 98.39% 100.00% +1.61%
SetMutation.java 94.44% 97.22% +2.78%

Test Logs

https://storage.googleapis.com/firebase-sdk-metric-reports/3XGxBTy8tJ.html

github-actions · 2025-01-02T20:55:24Z

Test Results

186 files + 172 186 suites +172 4m 37s ⏱️ + 4m 25s
1 234 tests +1 211 1 218 ✅ +1 195 16 💤 +16 0 ❌ ±0
2 492 runs +2 446 2 460 ✅ +2 414 32 💤 +32 0 ❌ ±0

Results for commit 98d526a. ± Comparison against base commit 320a3ed.

This pull request removes 23 and adds 1234 tests. Note that renamed tests count towards both.

com.google.firebase.functions.AppCheckLimitedUseTest ‑ FirebaseFunctions#getHttpsCallable should build callable with FAC settings (when false)
com.google.firebase.functions.AppCheckLimitedUseTest ‑ FirebaseFunctions#getHttpsCallable should build callable with FAC settings (when true)
com.google.firebase.functions.AppCheckLimitedUseTest ‑ FirebaseFunctions#getHttpsCallable should not use limited-use tokens by default
com.google.firebase.functions.AppCheckLimitedUseTest ‑ FirebaseFunctions#getHttpsCallableFromUrl callable with FAC settings (when false)
com.google.firebase.functions.AppCheckLimitedUseTest ‑ FirebaseFunctions#getHttpsCallableFromUrl callable with FAC settings (when true)
com.google.firebase.functions.AppCheckLimitedUseTest ‑ FirebaseFunctions#getHttpsCallableFromUrl should not use limited-use tokens by default
com.google.firebase.functions.FunctionsRegistrarTest ‑ getComponents_publishesLibVersionComponent
com.google.firebase.functions.FunctionsTests ‑ Firebase#functions should delegate to FirebaseFunctions#getInstance(FirebaseApp, region)
com.google.firebase.functions.FunctionsTests ‑ Firebase#functions should delegate to FirebaseFunctions#getInstance(region)
com.google.firebase.functions.FunctionsTests ‑ FirebaseApp#functions should delegate to FirebaseFunctions#getInstance(FirebaseApp)
…

com.google.firebase.firestore.AggregateQuerySnapshotTest ‑ createWithCountShouldReturnInstanceWithTheGivenQueryAndCount
com.google.firebase.firestore.AggregateQueryTest ‑ testSourceMustNotBeNull
com.google.firebase.firestore.BlobTest ‑ testComparison
com.google.firebase.firestore.BlobTest ‑ testEquals
com.google.firebase.firestore.BlobTest ‑ testMutableBytes
com.google.firebase.firestore.CollectionReferenceTest ‑ testEquals
com.google.firebase.firestore.DocumentChangeTest ‑ randomTests
com.google.firebase.firestore.DocumentChangeTest ‑ testAdditions
com.google.firebase.firestore.DocumentChangeTest ‑ testChangesWithSortOrderChange
com.google.firebase.firestore.DocumentChangeTest ‑ testDeletions
…

♻️ This comment has been updated with latest results.

google-oss-bot · 2025-01-02T20:57:40Z

Size Report ¹

Affected Products

No changes between base commit (320a3ed) and merge commit (feb597e).

Test Logs

https://storage.googleapis.com/firebase-sdk-metric-reports/Oh8zVn6iAh.html

Firestore: update javadocs of Exclude, PropertyName, and ServerTimest…

3a6018b

…amp to explicitly document using the `@get` and/or `@set` use-site targets on Kotlin properties.

dconeybe added api: firestore no-changelog main-merge-ack labels Jan 2, 2025

dconeybe self-assigned this Jan 2, 2025

google-oss-bot added the size/M label Jan 2, 2025

wu-hui approved these changes Jan 3, 2025

View reviewed changes

dconeybe added 5 commits January 3, 2025 11:14

PropertyName.java: fix rendering of code sample

2845a94

ServerTimestamp.java: use {@code } instead of <code></code>

a962cb4

remove unnecessary {@literal } block

fb667b7

Exclude.java: use {@code } instead of <code></code>

95df314

DocumentId.java: add comments for it too

98d526a

dconeybe merged commit f024090 into main Jan 3, 2025
32 checks passed

dconeybe deleted the dconeybe/firestore/AnnotationKtDocs branch January 3, 2025 23:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

dconeybe commented Jan 2, 2025

github-actions bot commented Jan 2, 2025 •

edited

Loading

github-actions bot commented Jan 2, 2025

google-oss-bot commented Jan 2, 2025 •

edited

Loading

`firebase-firestore`

github-actions bot commented Jan 2, 2025 •

edited

Loading

google-oss-bot commented Jan 2, 2025 •

edited

Loading

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

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

Conversation

dconeybe commented Jan 2, 2025

github-actions bot commented Jan 2, 2025 • edited Loading

github-actions bot commented Jan 2, 2025

Vertex AI Mock Responses Check ⚠️

google-oss-bot commented Jan 2, 2025 • edited Loading

Coverage Report 1

Affected Products

firebase-firestore

Test Logs

github-actions bot commented Jan 2, 2025 • edited Loading

Test Results

google-oss-bot commented Jan 2, 2025 • edited Loading

Size Report 1

Affected Products

Test Logs

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

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

github-actions bot commented Jan 2, 2025 •

edited

Loading

google-oss-bot commented Jan 2, 2025 •

edited

Loading

Coverage Report ¹

`firebase-firestore`

github-actions bot commented Jan 2, 2025 •

edited

Loading

google-oss-bot commented Jan 2, 2025 •

edited

Loading

Size Report ¹