Merge "Minor improvements to documentation around null/empty repeated values." into androidx-main
diff --git a/appsearch/appsearch/src/main/java/androidx/appsearch/app/GenericDocument.java b/appsearch/appsearch/src/main/java/androidx/appsearch/app/GenericDocument.java
index 9fe9169..76af94b 100644
--- a/appsearch/appsearch/src/main/java/androidx/appsearch/app/GenericDocument.java
+++ b/appsearch/appsearch/src/main/java/androidx/appsearch/app/GenericDocument.java
@@ -275,12 +275,16 @@
* one of the typed versions of this method instead, such as {@link #getPropertyString} or
* {@link #getPropertyStringArray}.
*
+ * <p>If the property was assigned as an empty array using one of the
+ * {@code Builder#setProperty} functions, this method will return an empty array. If no such
+ * property exists at all, this method returns {@code null}.
+ *
* <!--@exportToFramework:ifJetpack()--><!--@exportToFramework:else()
- * <p>If the property has been set is an empty {@link GenericDocument}[] or {@code byte[][]},
- * this will return an empty {@link GenericDocument}[] or {@code byte[][]} respectively
- * starting in {@link android.os.Build.VERSION_CODES#TIRAMISU Android T} and {@code null} in
- * earlier versions of Android. For other types it will always return an empty
- * array if the property has been set as an empty array.
+ * <p>Note: If the property is an empty {@link GenericDocument}[] or {@code byte[][]},
+ * this method will return a {@code null} value in versions of Android prior to
+ * {@link android.os.Build.VERSION_CODES#TIRAMISU Android T}. Starting in Android T it will
+ * return an empty array if the property has been set as an empty array, matching the
+ * behavior of other property types.
* -->
*
* @param path The path to look for.
@@ -745,6 +749,12 @@
*
* <p>See {@link #getProperty} for a detailed description of the path syntax.
*
+ * <p>If the property has not been set via {@link Builder#setPropertyString}, this method
+ * returns {@code null}.
+ *
+ * <p>If it has been set via {@link Builder#setPropertyString} to an empty
+ * {@code String[]}, this method returns an empty {@code String[]}.
+ *
* @param path The path to look for.
* @return The {@code String[]} associated with the given path, or {@code null} if no value is
* set or the value is of a different type.
@@ -761,6 +771,12 @@
*
* <p>See {@link #getProperty} for a detailed description of the path syntax.
*
+ * <p>If the property has not been set via {@link Builder#setPropertyLong}, this method
+ * returns {@code null}.
+ *
+ * <p>If it has been set via {@link Builder#setPropertyLong} to an empty
+ * {@code long[]}, this method returns an empty {@code long[]}.
+ *
* @param path The path to look for.
* @return The {@code long[]} associated with the given path, or {@code null} if no value is
* set or the value is of a different type.
@@ -777,6 +793,12 @@
*
* <p>See {@link #getProperty} for a detailed description of the path syntax.
*
+ * <p>If the property has not been set via {@link Builder#setPropertyDouble}, this method
+ * returns {@code null}.
+ *
+ * <p>If it has been set via {@link Builder#setPropertyDouble} to an empty
+ * {@code double[]}, this method returns an empty {@code double[]}.
+ *
* @param path The path to look for.
* @return The {@code double[]} associated with the given path, or {@code null} if no value is
* set or the value is of a different type.
@@ -793,6 +815,12 @@
*
* <p>See {@link #getProperty} for a detailed description of the path syntax.
*
+ * <p>If the property has not been set via {@link Builder#setPropertyBoolean}, this method
+ * returns {@code null}.
+ *
+ * <p>If it has been set via {@link Builder#setPropertyBoolean} to an empty
+ * {@code boolean[]}, this method returns an empty {@code boolean[]}.
+ *
* @param path The path to look for.
* @return The {@code boolean[]} associated with the given path, or {@code null} if no value
* is set or the value is of a different type.
@@ -809,9 +837,15 @@
*
* <p>See {@link #getProperty} for a detailed description of the path syntax.
*
- * <!--@exportToFramework:ifJetpack()--><!--@exportToFramework:else()
- * <p> If the property has been set via @link Builder#setPropertyBytes} is an empty {@code
- * byte[][]}. This will return an empty {@code byte[][]} respectively starting in
+ * <p>If the property has not been set via {@link Builder#setPropertyBytes}, this method
+ * returns {@code null}.
+ *
+ * <!--@exportToFramework:ifJetpack()-->
+ * <p>If it has been set via {@link Builder#setPropertyBytes} to an empty {@code byte[][]},
+ * this method returns an empty {@code byte[][]}.
+ * <!--@exportToFramework:else()
+ * <p>If it has been set via {@link Builder#setPropertyBytes} to an empty {@code byte[][]},
+ * this method returns an empty {@code byte[][]} starting in
* {@link android.os.Build.VERSION_CODES#TIRAMISU Android T} and {@code null} in earlier
* versions of Android.
* -->
@@ -833,11 +867,17 @@
*
* <p>See {@link #getProperty} for a detailed description of the path syntax.
*
- * <!--@exportToFramework:ifJetpack()--><!--@exportToFramework:else()
- * <p> If the property has been set via {@link Builder#setPropertyDocument} is an empty
- * {@link GenericDocument}[], this will return an empty {@link GenericDocument}[] respectively
- * starting in {@link android.os.Build.VERSION_CODES#TIRAMISU Android T} and {@code null} in
- * earlier versions of Android.
+ * <p>If the property has not been set via {@link Builder#setPropertyDocument}, this method
+ * returns {@code null}.
+ *
+ * <!--@exportToFramework:ifJetpack()-->
+ * <p>If it has been set via {@link Builder#setPropertyDocument} to an empty
+ * {@code GenericDocument[]}, this method returns an empty {@code GenericDocument[]}.
+ * <!--@exportToFramework:else()
+ * <p>If it has been set via {@link Builder#setPropertyDocument} to an empty
+ * {@code GenericDocument[]}, this method returns an empty {@code GenericDocument[]} starting
+ * in {@link android.os.Build.VERSION_CODES#TIRAMISU Android T} and {@code null} in earlier
+ * versions of Android.
* -->
*
* @param path The path to look for.
