Updated comments

Author: maneesht

packages/data-connect/src/api.browser.ts

@@ -28,20 +28,25 @@ import { OpResult, SerializedRef } from './api/Reference';
 import { DataConnectError, Code } from './core/error';
 
 /**
- *
- * @public
- * @param queryRef
- * @param onResult
- * @param onErr
- * @param initialCache
- * @returns
+ * Subscribe to a `QueryRef`
+ * @param queryRefOrSerializedResult query ref or serialized result.
+ * @param observer observer object to use for subscribing.
+ * @returns `SubscriptionOptions`
  */
 export function subscribe<Data, Variables>(
   queryRefOrSerializedResult:
     | QueryRef<Data, Variables>
     | SerializedRef<Data, Variables>,
   observer: SubscriptionOptions<Data, Variables>
 ): QueryUnsubscribe;
+/**
+ * Subscribe to a `QueryRef`
+ * @param queryRefOrSerializedResult query ref or serialized result.
+ * @param onNext Callback to call when result comes back.
+ * @param onError Callback to call when error gets thrown.
+ * @param onComplete Called when subscription completes.
+ * @returns `SubscriptionOptions`
+ */
 export function subscribe<Data, Variables>(
   queryRefOrSerializedResult:
     | QueryRef<Data, Variables>
@@ -50,6 +55,14 @@ export function subscribe<Data, Variables>(
   onError?: OnErrorSubscription,
   onComplete?: OnCompleteSubscription
 ): QueryUnsubscribe;
+/**
+ * Subscribe to a `QueryRef`
+ * @param queryRefOrSerializedResult query ref or serialized result.
+ * @param observerOrOnNext observer object or next function.
+ * @param onError Callback to call when error gets thrown.
+ * @param onComplete Called when subscription completes.
+ * @returns `SubscriptionOptions`
+ */
 export function subscribe<Data, Variables>(
   queryRefOrSerializedResult:
     | QueryRef<Data, Variables>

packages/data-connect/src/api/DataConnect.ts

@@ -37,12 +37,18 @@ import { RESTTransport } from '../network/transport/rest';
 import { MutationManager } from './Mutation';
 
 
+/**
+ * Connector Config for calling Data Connect backend.
+ */
 export interface ConnectorConfig {
   location: string;
   connector: string;
   service: string;
 }
 
+/**
+ * Options to connect to emulator
+ */
 export interface TransportOptions {
   host: string;
   sslEnabled?: boolean;
@@ -65,10 +71,16 @@ export function parseOptions(fullHost: string): TransportOptions {
   const port = Number(portAsString);
   return { host, port, sslEnabled: isSecure };
 }
+/**
+ * DataConnectOptions including project id
+ */
 export interface DataConnectOptions extends ConnectorConfig {
   projectId: string;
 }
 
+/**
+ * Class representing Firebase Data Connect
+ */
 export class DataConnect {
   _queryManager!: QueryManager;
   _mutationManager!: MutationManager;
@@ -155,6 +167,13 @@ export class DataConnect {
   }
 }
 
+/**
+ * Connect to the DataConnect Emulator
+ * @param dc Data Connect instance
+ * @param host host of emulator server
+ * @param port port of emulator server
+ * @param sslEnabled use https
+ */
 export function connectDataConnectEmulator(
   dc: DataConnect,
   host: string,
@@ -164,7 +183,16 @@ export function connectDataConnectEmulator(
   dc.enableEmulator({ host, port, sslEnabled });
 }
 
+/**
+ * Initialize DataConnect instance
+ * @param options ConnectorConfig
+ */
 export function getDataConnect(options: ConnectorConfig): DataConnect;
+/**
+ * Initialize DataConnect instance
+ * @param app FirebaseApp to initialize to.
+ * @param options ConnectorConfig
+ */
 export function getDataConnect(
   app: FirebaseApp,
   options: ConnectorConfig
@@ -208,6 +236,11 @@ export function getDataConnect(
   });
 }
 
+/**
+ * Delete DataConnect instance
+ * @param dataConnect DataConnect instance
+ * @returns 
+ */
 export function terminate(dataConnect: DataConnect): Promise<void> {
   return dataConnect._delete();
   // TODO(mtewani): Stop pending tasks

packages/data-connect/src/api/Mutation.ts

@@ -30,30 +30,51 @@ export interface MutationRef<Data, Variables>
   refType: typeof MUTATION_STR;
 }
 
+/**
+ * Creates a `MutationRef`
+ * @param dcInstance Data Connect instance
+ * @param mutationName name of mutation
+ */
 export function mutationRef<Data>(
   dcInstance: DataConnect,
-  queryName: string
+  mutationName: string
 ): MutationRef<Data, undefined>;
+/**
+ * 
+ * @param dcInstance Data Connect instance
+ * @param mutationName name of mutation
+ * @param variables variables to send with mutation
+ */
 export function mutationRef<Data, Variables>(
   dcInstance: DataConnect,
   mutationName: string,
   variables: Variables
 ): MutationRef<Data, Variables>;
+/**
+ * 
+ * @param dcInstance Data Connect instance
+ * @param mutationName name of mutation
+ * @param variables variables to send with mutation
+ * @returns `MutationRef`
+ */
 export function mutationRef<Data, Variables>(
   dcInstance: DataConnect,
-  queryName: string,
+  mutationName: string,
   variables?: Variables
 ): MutationRef<Data, Variables> {
   dcInstance.setInitialized();
   const ref: MutationRef<Data, Variables> = {
     dataConnect: dcInstance,
-    name: queryName,
+    name: mutationName,
     refType: MUTATION_STR,
     variables: variables as Variables
   };
   return ref;
 }
 
+/**
+ * @internal
+ */
 export class MutationManager {
   private _inflight: Array<PromiseLike<unknown>> = [];
   constructor(private _transport: DataConnectTransport) {}
@@ -81,15 +102,26 @@ export class MutationManager {
   }
 }
 
+/**
+ * Mutation Result from `executeMutation`
+ */
 export interface MutationResult<Data, Variables>
   extends DataConnectResult<Data, Variables> {
   ref: MutationRef<Data, Variables>;
 }
+/**
+ * Mutation return value from `executeMutation`
+ */
 export interface MutationPromise<Data, Variables>
   extends PromiseLike<MutationResult<Data, Variables>> {
   // reserved for special actions like cancellation
 }
 
+/**
+ * Execute Mutation
+ * @param mutationRef mutation to execute
+ * @returns `MutationRef`
+ */
 export function executeMutation<Data, Variables>(
   mutationRef: MutationRef<Data, Variables>
 ): MutationPromise<Data, Variables> {

packages/data-connect/src/api/Reference.ts

@@ -42,11 +42,17 @@ export interface DataConnectResult<Data, Variables> extends OpResult<Data> {
   // future metadata
 }
 
+/**
+ * Serialized RefInfo as a result of `QueryResult.toJSON().refInfo`
+ */
 export interface RefInfo<Variables> {
   name: string;
   variables: Variables;
   connectorConfig: DataConnectOptions;
 }
+/**
+ * Serialized Ref as a result of `QueryResult.toJSON()`
+ */
 export interface SerializedRef<Data, Variables> extends OpResult<Data> {
   refInfo: RefInfo<Variables>;
 }

packages/data-connect/src/api/query.ts

@@ -25,45 +25,93 @@ import {
   SerializedRef
 } from './Reference';
 
+/**
+ * Signature for `OnResultSubscription` for `subscribe`
+ */
 export type OnResultSubscription<Data, Variables> = (
   res: QueryResult<Data, Variables>
 ) => void;
+/**
+ * Signature for `OnErrorSubscription` for `subscribe`
+ */
 export type OnErrorSubscription = (err?: DataConnectError) => void;
+/**
+ * Signature for unsubscribe from `subscribe`
+ */
 export type QueryUnsubscribe = () => void;
+/**
+ * Representation of user provided subscription options.
+ */
 export interface DataConnectSubscription<Data, Variables> {
   userCallback: OnResultSubscription<Data, Variables>;
   errCallback?: (e?: DataConnectError) => void;
   unsubscribe: () => void;
 }
+
+/**
+ * QueryRef object
+ */
 export interface QueryRef<Data, Variables>
   extends OperationRef<Data, Variables> {
   refType: typeof QUERY_STR;
 }
+/**
+ * Result of `executeQuery`
+ */
 export interface QueryResult<Data, Variables>
   extends DataConnectResult<Data, Variables> {
   ref: QueryRef<Data, Variables>;
   toJSON: () => SerializedRef<Data, Variables>;
 }
+/**
+ * Promise returned from `executeQuery`
+ */
 export interface QueryPromise<Data, Variables>
   extends PromiseLike<QueryResult<Data, Variables>> {
   // reserved for special actions like cancellation
 }
 
+/**
+ * Execute Query
+ * @param queryRef query to execute.
+ * @returns `QueryPromise`
+ */
 export function executeQuery<Data, Variables>(
   queryRef: QueryRef<Data, Variables>
 ): QueryPromise<Data, Variables> {
   return queryRef.dataConnect._queryManager.executeQuery(queryRef);
 }
 
+/**
+ * Execute Query
+ * @param dcInstance Data Connect instance to use.
+ * @param queryName Query to execute
+ * @returns `QueryRef`
+ */
 export function queryRef<Data>(
   dcInstance: DataConnect,
   queryName: string
 ): QueryRef<Data, undefined>;
+/**
+ * Execute Query
+ * @param dcInstance Data Connect instance to use.
+ * @param queryName Query to execute
+ * @param variables Variables to execute with
+ * @returns `QueryRef`
+ */
 export function queryRef<Data, Variables>(
   dcInstance: DataConnect,
   queryName: string,
   variables: Variables
 ): QueryRef<Data, Variables>;
+/**
+ * Execute Query
+ * @param dcInstance Data Connect instance to use.
+ * @param queryName Query to execute
+ * @param variables Variables to execute with
+ * @param initialCache initial cache to use for client hydration
+ * @returns `QueryRef`
+ */
 export function queryRef<Data, Variables>(
   dcInstance: DataConnect,
   queryName: string,
@@ -79,6 +127,11 @@ export function queryRef<Data, Variables>(
     variables: variables as Variables
   };
 }
+/**
+ * Converts serialized ref to query ref
+ * @param serializedRef ref to convert to `QueryRef`
+ * @returns `QueryRef`
+ */
 export function toQueryRef<Data, Variables>(
   serializedRef: SerializedRef<Data, Variables>
 ) {
@@ -87,7 +140,13 @@ export function toQueryRef<Data, Variables>(
   } = serializedRef;
   return queryRef(getDataConnect(connectorConfig), name, variables);
 }
+/**
+ * `OnCompleteSubscription`
+ */
 export type OnCompleteSubscription = () => void;
+/**
+ * Representation of full observer options in `subscribe`
+ */
 export interface SubscriptionOptions<Data, Variables> {
   onNext?: OnResultSubscription<Data, Variables>;
   onErr?: OnErrorSubscription;