dataconnect: fix various kdoc documentation issues (#7399)

Author: dconeybe

firebase-dataconnect/README.md

@@ -13,15 +13,15 @@ To build Firebase Data Connect, from the source root run:
 ./gradlew :firebase-dataconnect:assembleRelease
 ```
 
-## Unit Testing
+## Unit testing
 
 To run unit tests for Firebase Data Connect, from the source root run:
 
 ```bash
 ./gradlew :firebase-dataconnect:check
 ```
 
-## Integration Testing
+## Integration testing
 
 Running integration tests requires a Firebase project because they connect to the Firebase Data
 Connect backend.
@@ -34,10 +34,10 @@ Make sure you have created a Firebase Data Connect instance for your project, be
 
 By default, integration tests run against the Firebase Data Connect emulator.
 
-### Setting up the Firebase Data Connect Emulator
+### Setting up the Firebase Data Connect emulator
 
 The integration tests require that the Firebase Data Connect emulator is running on port 9399, which
-is default when running it via the Data Connect Toolkit.
+is default when running it via the Firebase CLI.
 
 - [Install the Firebase CLI](https://firebase.google.com/docs/cli/).
   ```
@@ -57,7 +57,7 @@ is default when running it via the Data Connect Toolkit.
 To run the integration tests against prod, select `DataConnectProdIntegrationTest` run
 configuration.
 
-### Run on Local Android Emulator
+### Run on local Android emulator
 
 Then run:
 
@@ -79,7 +79,7 @@ Run:
 ./gradlew :firebase-dataconnect:deviceCheck
 ```
 
-## Code Formatting
+## Code formatting
 
 Run below to format Kotlin and Java code:
 
@@ -90,7 +90,7 @@ Run below to format Kotlin and Java code:
 See [here](../README.md#code-formatting) if you want to be able to format code from within Android
 Studio.
 
-## Build Local Jar of Firebase Data Connect SDK
+## Build local jar of Firebase Data Connect SDK
 
 ```bash
 ./gradlew -PprojectsToPublish="firebase-dataconnect" publishReleasingLibrariesToMavenLocal

firebase-dataconnect/androidTestutil/src/main/kotlin/com/google/firebase/dataconnect/testutil/DataConnectBackend.kt

@@ -81,11 +81,11 @@ import java.net.URL
  * - https://screenshot.googleplex.com/AmNdgDkWmR4gQXr
  * - https://screenshot.googleplex.com/8Aq5YKUXCLUAjKr
  *
- * When using "autopush" or "staging", the `firebase-tools` cli must be told about the URL of the
- * Data Connect server to which to deploy using the `FIREBASE_DATACONNECT_URL` environment variable.
- * This only matters if running a command line `firebase deploy --only dataconnect` or other
- * `firebase` commands that talk to a Data Connect backend. See the documentation of [Staging] and
- * [Autopush] for details.
+ * When using "autopush" or "staging", the Firebase CLI must be told about the URL of the Data
+ * Connect server to which to deploy using the `FIREBASE_DATACONNECT_URL` environment variable. This
+ * only matters if running a command line `firebase deploy --only dataconnect` or other `firebase`
+ * commands that talk to a Data Connect backend. See the documentation of [Staging] and [Autopush]
+ * for details.
  */
 sealed interface DataConnectBackend {
 

firebase-dataconnect/demo/build.gradle.kts

@@ -67,7 +67,7 @@ dokka {
 
 // The remaining code in this file can be omitted from customer facing
 // documentation. It's here just to make things compile and/or configure
-// optional components of the build (e.g. spotless code formatting).
+// optional components of the build (for example, spotless code formatting).
 
 android {
   namespace = "com.google.firebase.dataconnect.minimaldemo"

firebase-dataconnect/emulator/README.md

@@ -17,7 +17,7 @@ Here is a summary of the detailed steps from below:
 5. Start the Postgresql container: `./start_postgres_pod.sh`
 6. Start the emulator: `./cli -alsologtostderr=1 -stderrthreshold=0 dev`
 
-## Step 1: Compile Firebase Data Connect Emulator
+## Step 1: Compile Firebase Data Connect emulator
 
 Compile the Firebase Data Connect Emulator in google3 using `blaze`. The build must be done in a
 gLinux workstation or go/cloudtop instance; namely, building on a macOS host is not supported, even
@@ -65,7 +65,7 @@ If successful, the emulator binary will be located at
 blaze-bin/third_party/firebase/dataconnect/emulator/cli/cli_macos
 ```
 
-#### Copy Emulator Binary to Target Machine
+#### Copy emulator binary to target machine
 
 If the machine used to build the emulator binary is the same as the target machine, then you are
 done. Otherwise, you need to copy the binary to the target machine. There are two easy ways to do
@@ -105,7 +105,7 @@ or
 chmod a+x cli_macos
 ```
 
-#### Precompiled Emulator Binaries
+#### Precompiled emulator binaries
 
 dconeybe maintains a directory with precompiled emulator binaries:
 
@@ -114,7 +114,7 @@ http://x20/teams/firestore-clients/DataConnectEmulator
 At the time of writing, these builds incorporate the patch to remove vector support, as mentioned in
 the "Troubleshooting" section below.
 
-## Step 2: Start Postgresql Server
+## Step 2: Start Postgresql server
 
 The Firebase Data Connect emulator requires a real Postgresql server to talk to. Installing and
 configuring a Postgresql server on a given platform is a tedious and non-standard process. Moreover,
@@ -151,7 +151,7 @@ To install Podman, run these commands:
 
 The "machine" commands create and start the Linux virtual machine, respectively.
 
-#### Launch the Postgresql Containers
+#### Launch the Postgresql containers
 
 A handy helper script is all that is needed to start the Postgresql server:
 
@@ -168,7 +168,7 @@ the Postgresql server and delete the Postgresql server's database.
 There is also a Web UI called "pgadmin4" that can be used to visually interact with the database.
 The URL and login credentials are included in the final lines of output from the script.
 
-#### Launch the Data Connect Emulator
+#### Launch the Data Connect emulator
 
 With the Postgresql containers running, launch the Data Connect emulator with this command:
 

firebase-dataconnect/emulator/start_postgres_pod.sh

@@ -66,7 +66,7 @@ cat <<EOF
 PostegreSQL server running on port 5432
 The pgAdmin web UI can be viewed at http://localhost:8888
 The pgAdmin login credentails are: username "${PGADMIN_EMAIL}" and password "${PGADMIN_PASSWORD}"
-If prompted later on for a Postgresql database password, any value should be accepted (e.g. "password").
+If prompted later on for a Postgresql database password, any value should be accepted (for example, "password").
 
 To shut everything down, run
   podman pod stop dataconnect_postgres

firebase-dataconnect/gradleplugin/plugin/src/main/kotlin/com/google/firebase/dataconnect/gradle/plugin/DataConnectDslExtension.kt

@@ -64,8 +64,8 @@ abstract class DataConnectDslExtension @Inject constructor(objectFactory: Object
   fun emulator(block: DataConnectEmulatorDslExtension.() -> Unit): Unit = block(emulator)
 
   /**
-   * Values to use when running ktfmt to format the code generated by the Data Connect toolkit,
-   * which override the values from those defined in the outer scope.
+   * Values to use when running ktfmt to format the code generated by the Firebase CLI, which
+   * overrides the values defined in the outer scope.
    */
   val ktfmt: DataConnectKtfmtDslExtension =
     objectFactory.newInstance<DataConnectKtfmtDslExtension>()

firebase-dataconnect/src/main/kotlin/com/google/firebase/dataconnect/AnyValue.kt

@@ -34,15 +34,15 @@ import kotlinx.serialization.serializer
 /**
  * Represents a variable or field of the Data Connect custom scalar type `Any`.
  *
- * ### Valid Values for `AnyValue`
+ * ### Valid values for `AnyValue`
  *
  * `AnyValue` can encapsulate [String], [Boolean], [Double], a [List] of one of these types, or a
- * [Map] whose values are one of these types. The values can be arbitrarily nested (e.g. a list that
- * contains a map that contains other maps, and so on. The lists and maps can contain heterogeneous
- * values; for example, a single [List] can contain a [String] value, some [Boolean] values, and
- * some [List] values. The values of a [List] or a [Map] may be `null`. The only exception is that a
- * variable or field declared as `[Any]` in GraphQL may _not_ have `null` values in the top-level
- * list; however, nested lists or maps _may_ contain null values.
+ * [Map] whose values are one of these types. The values can be arbitrarily nested (for example, a
+ * list that contains a map that contains other maps, and so on). The lists and maps can contain
+ * heterogeneous values; for example, a single [List] can contain a [String] value, some [Boolean]
+ * values, and some [List] values. The values of a [List] or a [Map] may be `null`. The only
+ * exception is that a variable or field declared as `[Any]` in GraphQL may _not_ have `null` values
+ * in the top-level list; however, nested lists or maps _may_ contain null values.
  *
  * ### Storing `Int` in an `AnyValue`
  *
@@ -51,15 +51,15 @@ import kotlinx.serialization.serializer
  * ### Storing `Long` in an `AnyValue`
  *
  * To store a [Long] value, converting it to a [Double] can be lossy if the value is sufficiently
- * large (or small) to not be exactly represented by [Double]. The _largest_ [Long] value that can
+ * large (or small) to not be exactly representable by [Double]. The _largest_ [Long] value that can
  * be stored in a [Double] with its exact value is `2^53 – 1` (`9007199254740991`). The _smallest_
  * [Long] value that can be stored in a [Double] with its exact value is `-(2^53 – 1)`
  * (`-9007199254740991`). This limitation is exactly the same in JavaScript, which does not have a
  * native "int" or "long" type, but rather stores all numeric values in a 64-bit floating point
  * value. See
- * [MAX_SAFE_INTEGER](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER])
+ * [MAX_SAFE_INTEGER](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)
  * and
- * [MIN_SAFE_INTEGER](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER])
+ * [MIN_SAFE_INTEGER](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER)
  * for more details.
  *
  * ### Integration with `kotlinx.serialization`
@@ -72,6 +72,7 @@ import kotlinx.serialization.serializer
  *
  * ```
  * type Foo @table { value: Any }
+ *
  * mutation FooInsert($value: Any) {
  *   key: foo_insert(data: { value: $value })
  * }
@@ -102,10 +103,11 @@ public class AnyValue internal constructor(internal val protoValue: Value) {
    *
    * An exception is thrown if any of the values of the map, or its sub-values, are invalid for
    * being stored in [AnyValue]; see the [AnyValue] class documentation for a detailed description
-   * of value values.
+   * of valid values.
    *
-   * This class makes a _copy_ of the given map; therefore, any modifications to the map after this
-   * object is created will have no effect on this [AnyValue] object.
+   * This class makes a _deep copy_ of the given map; therefore, any modifications to the map or its
+   * constituent lists or maps after this object is created will have no effect on this [AnyValue]
+   * object.
    */
   public constructor(value: Map<String, Any?>) : this(value.toValueProto())
 
@@ -114,10 +116,11 @@ public class AnyValue internal constructor(internal val protoValue: Value) {
    *
    * An exception is thrown if any of the values of the list, or its sub-values, are invalid for
    * being stored in [AnyValue]; see the [AnyValue] class documentation for a detailed description
-   * of value values.
+   * of valid values.
    *
-   * This class makes a _copy_ of the given list; therefore, any modifications to the list after
-   * this object is created will have no effect on this [AnyValue] object.
+   * This class makes a _deep copy_ of the given list; therefore, any modifications to the list or
+   * its constituent lists or maps after this object is created will have no effect on this
+   * [AnyValue] object.
    */
   public constructor(value: List<Any?>) : this(value.toValueProto())
 
@@ -133,7 +136,7 @@ public class AnyValue internal constructor(internal val protoValue: Value) {
   /**
    * The native Kotlin type of the value encapsulated in this object.
    *
-   * Although this type is `Any` it will be one of `String, `Boolean`, `Double`, `List<Any?>` or
+   * Although this type is `Any` it will be one of `String`, `Boolean`, `Double`, `List<Any?>` or
    * `Map<String, Any?>`. See the [AnyValue] class documentation for a detailed description of the
    * types of values that are supported.
    */

firebase-dataconnect/src/main/kotlin/com/google/firebase/dataconnect/ConnectorConfig.kt

@@ -22,13 +22,13 @@ import java.util.Objects
  * Information about a Firebase Data Connect "connector" that is used by [FirebaseDataConnect] to
  * connect to the correct Google Cloud resources.
  *
- * ### Safe for Concurrent Use
+ * ### Safe for concurrent use
  *
  * All methods and properties of [ConnectorConfig] are thread-safe and may be safely called and/or
  * accessed concurrently from multiple threads and/or coroutines.
  *
  * @property connector The ID of the Firebase Data Connect "connector".
- * @property location The location where the connector is located (e.g. `"us-central1"`).
+ * @property location The location where the connector is located (for example, `"us-central1"`).
  * @property serviceId The ID of the Firebase Data Connect service.
  */
 public class ConnectorConfig(

firebase-dataconnect/src/main/kotlin/com/google/firebase/dataconnect/DataConnectOperationFailureResponse.kt

@@ -33,15 +33,16 @@ public interface DataConnectOperationFailureResponse<Data> {
    * * [Double]
    * * [List] containing any of the types in this list of types
    * * [Map] with [String] keys and values of the types in this list of types
-   *
-   * Consider using [toJson] to get a higher-level object.
    */
+  // TODO(b/446167496) Add a link to [toJson] in the kdoc comments above when the toJson extension
+  //  function is implemented.
   public val rawData: Map<String, Any?>?
 
   /**
    * The list of errors provided by the backend in the response message; may be empty.
    *
-   * See https://spec.graphql.org/draft/#sec-Errors for details.
+   * See [https://spec.graphql.org/draft/#sec-Errors](https://spec.graphql.org/draft/#sec-Errors)
+   * for details.
    */
   public val errors: List<ErrorInfo>
 
@@ -69,7 +70,8 @@ public interface DataConnectOperationFailureResponse<Data> {
   /**
    * Information about the error, as provided in the response payload from the backend.
    *
-   * See https://spec.graphql.org/draft/#sec-Errors for details.
+   * See [https://spec.graphql.org/draft/#sec-Errors](https://spec.graphql.org/draft/#sec-Errors)
+   * for details.
    */
   public interface ErrorInfo {
     /** The error's message. */

firebase-dataconnect/src/main/kotlin/com/google/firebase/dataconnect/DataConnectSettings.kt

@@ -21,12 +21,12 @@ import java.util.Objects
 /**
  * Settings that control the behavior of [FirebaseDataConnect] instances.
  *
- * ### Safe for Concurrent Use
+ * ### Safe for concurrent use
  *
  * All methods and properties of [DataConnectSettings] are thread-safe and may be safely called
  * and/or accessed concurrently from multiple threads and/or coroutines.
  *
- * @property host The host of the Firebase Data Connect service to which to connect (e.g.
+ * @property host The host of the Firebase Data Connect service to which to connect (for example,
  * `"myproxy.foo.com"`, `"myproxy.foo.com:9987"`).
  * @property sslEnabled Whether to use SSL for the connection; if `true`, then the connection will
  * be encrypted using SSL and, if false, the connection will _not_ be encrypted and all network