Add database@exp API docs (#4738)

Author: schmidt-sebastian

packages/database/src/api/Database.ts

@@ -69,7 +69,7 @@ export class Database implements FirebaseService, Compat<ExpDatabase> {
    * location.
    * @throws If a Reference is provided, throws if it does not belong to the
    * same project.
-   * @return Firebase reference.
+   * @returns Firebase reference.
    */
   ref(path?: string): Reference;
   ref(path?: Reference): Reference;
@@ -88,7 +88,7 @@ export class Database implements FirebaseService, Compat<ExpDatabase> {
    * Returns a reference to the root or the path specified in url.
    * We throw a exception if the url is not in the same domain as the
    * current repo.
-   * @return Firebase reference.
+   * @returns Firebase reference.
    */
   refFromURL(url: string): Reference {
     const apiName = 'database.refFromURL';

packages/database/src/api/Reference.ts

@@ -85,7 +85,7 @@ export class DataSnapshot implements Compat<ExpDataSnapshot> {
    * Retrieves the snapshot contents as JSON.  Returns null if the snapshot is
    * empty.
    *
-   * @return JSON representation of the DataSnapshot contents, or null if empty.
+   * @returns JSON representation of the DataSnapshot contents, or null if empty.
    */
   val(): unknown {
     validateArgCount('DataSnapshot.val', 0, 0, arguments.length);
@@ -95,7 +95,7 @@ export class DataSnapshot implements Compat<ExpDataSnapshot> {
   /**
    * Returns the snapshot contents as JSON, including priorities of node.  Suitable for exporting
    * the entire node contents.
-   * @return JSON representation of the DataSnapshot contents, or null if empty.
+   * @returns JSON representation of the DataSnapshot contents, or null if empty.
    */
   exportVal(): unknown {
     validateArgCount('DataSnapshot.exportVal', 0, 0, arguments.length);
@@ -113,7 +113,7 @@ export class DataSnapshot implements Compat<ExpDataSnapshot> {
   /**
    * Returns whether the snapshot contains a non-null value.
    *
-   * @return Whether the snapshot contains a non-null value, or is empty.
+   * @returns Whether the snapshot contains a non-null value, or is empty.
    */
   exists(): boolean {
     validateArgCount('DataSnapshot.exists', 0, 0, arguments.length);
@@ -124,7 +124,7 @@ export class DataSnapshot implements Compat<ExpDataSnapshot> {
    * Returns a DataSnapshot of the specified child node's contents.
    *
    * @param path Path to a child.
-   * @return DataSnapshot for child node.
+   * @returns DataSnapshot for child node.
    */
   child(path: string): DataSnapshot {
     validateArgCount('DataSnapshot.child', 0, 1, arguments.length);
@@ -138,7 +138,7 @@ export class DataSnapshot implements Compat<ExpDataSnapshot> {
    * Returns whether the snapshot contains a child at the specified path.
    *
    * @param path Path to a child.
-   * @return Whether the child exists.
+   * @returns Whether the child exists.
    */
   hasChild(path: string): boolean {
     validateArgCount('DataSnapshot.hasChild', 1, 1, arguments.length);
@@ -149,7 +149,7 @@ export class DataSnapshot implements Compat<ExpDataSnapshot> {
   /**
    * Returns the priority of the object, or null if no priority was set.
    *
-   * @return The priority.
+   * @returns The priority.
    */
   getPriority(): string | number | null {
     validateArgCount('DataSnapshot.getPriority', 0, 0, arguments.length);
@@ -161,7 +161,7 @@ export class DataSnapshot implements Compat<ExpDataSnapshot> {
    *
    * @param action Callback function to be called
    * for each child.
-   * @return True if forEach was canceled by action returning true for
+   * @returns True if forEach was canceled by action returning true for
    * one of the child nodes.
    */
   forEach(action: (snapshot: DataSnapshot) => boolean | void): boolean {
@@ -174,7 +174,7 @@ export class DataSnapshot implements Compat<ExpDataSnapshot> {
 
   /**
    * Returns whether this DataSnapshot has children.
-   * @return True if the DataSnapshot contains 1 or more child nodes.
+   * @returns True if the DataSnapshot contains 1 or more child nodes.
    */
   hasChildren(): boolean {
     validateArgCount('DataSnapshot.hasChildren', 0, 0, arguments.length);
@@ -187,15 +187,15 @@ export class DataSnapshot implements Compat<ExpDataSnapshot> {
 
   /**
    * Returns the number of children for this DataSnapshot.
-   * @return The number of children that this DataSnapshot contains.
+   * @returns The number of children that this DataSnapshot contains.
    */
   numChildren(): number {
     validateArgCount('DataSnapshot.numChildren', 0, 0, arguments.length);
     return this._delegate.size;
   }
 
   /**
-   * @return The Firebase reference for the location this snapshot's data came
+   * @returns The Firebase reference for the location this snapshot's data came
    * from.
    */
   getRef(): Reference {
@@ -472,7 +472,7 @@ export class Query implements Compat<QueryImpl> {
   }
 
   /**
-   * @return URL for this location.
+   * @returns URL for this location.
    */
   toString(): string {
     validateArgCount('Query.toString', 0, 0, arguments.length);
@@ -563,7 +563,7 @@ export class Reference extends Query implements Compat<ReferenceImpl> {
     );
   }
 
-  /** @return {?string} */
+  /** @returns {?string} */
   getKey(): string | null {
     validateArgCount('Reference.key', 0, 0, arguments.length);
     return this._delegate.key;
@@ -577,14 +577,14 @@ export class Reference extends Query implements Compat<ReferenceImpl> {
     return new Reference(this.database, child(this._delegate, pathString));
   }
 
-  /** @return {?Reference} */
+  /** @returns {?Reference} */
   getParent(): Reference | null {
     validateArgCount('Reference.parent', 0, 0, arguments.length);
     const parent = this._delegate.parent;
     return parent ? new Reference(this.database, parent) : null;
   }
 
-  /** @return {!Reference} */
+  /** @returns {!Reference} */
   getRoot(): Reference {
     validateArgCount('Reference.root', 0, 0, arguments.length);
     return new Reference(this.database, this._delegate.root);

packages/database/src/core/CompoundWrite.ts

@@ -87,7 +87,7 @@ export function compoundWriteAddWrites(
  *
  * @param compoundWrite The CompoundWrite to remove.
  * @param path The path at which a write and all deeper writes should be removed
- * @return The new CompoundWrite with the removed path
+ * @returns The new CompoundWrite with the removed path
  */
 export function compoundWriteRemoveWrite(
   compoundWrite: CompoundWrite,
@@ -110,7 +110,7 @@ export function compoundWriteRemoveWrite(
  *
  * @param compoundWrite The CompoundWrite to check.
  * @param path The path to check for
- * @return Whether there is a complete write at that path
+ * @returns Whether there is a complete write at that path
  */
 export function compoundWriteHasCompleteWrite(
   compoundWrite: CompoundWrite,
@@ -125,7 +125,7 @@ export function compoundWriteHasCompleteWrite(
  *
  * @param compoundWrite The CompoundWrite to get the node from.
  * @param path The path to get a complete write
- * @return The node if complete at that path, or null otherwise.
+ * @returns The node if complete at that path, or null otherwise.
  */
 export function compoundWriteGetCompleteNode(
   compoundWrite: CompoundWrite,
@@ -145,7 +145,7 @@ export function compoundWriteGetCompleteNode(
  * Returns all children that are guaranteed to be a complete overwrite.
  *
  * @param compoundWrite The CompoundWrite to get children from.
- * @return A list of all complete children.
+ * @returns A list of all complete children.
  */
 export function compoundWriteGetCompleteChildren(
   compoundWrite: CompoundWrite
@@ -192,7 +192,7 @@ export function compoundWriteChildCompoundWrite(
 
 /**
  * Returns true if this CompoundWrite is empty and therefore does not modify any nodes.
- * @return Whether this CompoundWrite is empty
+ * @returns Whether this CompoundWrite is empty
  */
 export function compoundWriteIsEmpty(compoundWrite: CompoundWrite): boolean {
   return compoundWrite.writeTree_.isEmpty();
@@ -202,7 +202,7 @@ export function compoundWriteIsEmpty(compoundWrite: CompoundWrite): boolean {
  * Applies this CompoundWrite to a node. The node is returned with all writes from this CompoundWrite applied to the
  * node
  * @param node The node to apply this CompoundWrite to
- * @return The node with all writes applied
+ * @returns The node with all writes applied
  */
 export function compoundWriteApply(
   compoundWrite: CompoundWrite,

packages/database/src/core/Repo.ts

@@ -193,7 +193,7 @@ export class Repo {
   }
 
   /**
-   * @return The URL corresponding to the root of this Firebase.
+   * @returns The URL corresponding to the root of this Firebase.
    */
   toString(): string {
     return (
@@ -319,7 +319,7 @@ export function repoStart(
 }
 
 /**
- * @return The time in milliseconds, taking the server offset into account if we have one.
+ * @returns The time in milliseconds, taking the server offset into account if we have one.
  */
 export function repoServerTime(repo: Repo): number {
   const offsetNode = repo.infoData_.getNode(new Path('.info/serverTimeOffset'));
@@ -1147,7 +1147,7 @@ function repoSendTransactionQueue(
  * is the path at which events need to be raised for.
  *
  * @param changedPath The path in mergedData that changed.
- * @return The rootmost path that was affected by rerunning transactions.
+ * @returns The rootmost path that was affected by rerunning transactions.
  */
 function repoRerunTransactions(repo: Repo, changedPath: Path): Path {
   const rootMostTransactionNode = repoGetAncestorTransactionNode(
@@ -1329,7 +1329,7 @@ function repoRerunTransactionQueue(
  * no pending transactions on any ancestor.
  *
  * @param path The location to start at.
- * @return The rootmost node with a transaction.
+ * @returns The rootmost node with a transaction.
  */
 function repoGetAncestorTransactionNode(
   repo: Repo,
@@ -1355,7 +1355,7 @@ function repoGetAncestorTransactionNode(
  * transactionNode.
  *
  * @param transactionNode
- * @return The generated queue.
+ * @returns The generated queue.
  */
 function repoBuildTransactionQueue(
   repo: Repo,

packages/database/src/core/SparseSnapshotTree.ts

@@ -39,7 +39,7 @@ export function newSparseSnapshotTree(): SparseSnapshotTree {
  * Only seems to be used in tests.
  *
  * @param path Path to look up snapshot for.
- * @return The retrieved node, or null.
+ * @returns The retrieved node, or null.
  */
 export function sparseSnapshotTreeFind(
   sparseSnapshotTree: SparseSnapshotTree,
@@ -94,7 +94,7 @@ export function sparseSnapshotTreeRemember(
  * Purge the data at path from the cache.
  *
  * @param path Path to look up snapshot for.
- * @return True if this node should now be removed.
+ * @returns True if this node should now be removed.
  */
 export function sparseSnapshotTreeForget(
   sparseSnapshotTree: SparseSnapshotTree,

packages/database/src/core/SyncPoint.ts

@@ -119,7 +119,7 @@ export function syncPointApplyOperation(
  * @param writesCache
  * @param serverCache
  * @param serverCacheComplete
- * @return Events to raise.
+ * @returns Events to raise.
  */
 export function syncPointGetView(
   syncPoint: SyncPoint,
@@ -166,7 +166,7 @@ export function syncPointGetView(
  * @param writesCache
  * @param serverCache Complete server cache, if we have it.
  * @param serverCacheComplete
- * @return Events to raise.
+ * @returns Events to raise.
  */
 export function syncPointAddEventRegistration(
   syncPoint: SyncPoint,
@@ -199,7 +199,7 @@ export function syncPointAddEventRegistration(
  *
  * @param eventRegistration If null, remove all callbacks.
  * @param cancelError If a cancelError is provided, appropriate cancel events will be returned.
- * @return removed queries and any cancel events
+ * @returns removed queries and any cancel events
  */
 export function syncPointRemoveEventRegistration(
   syncPoint: SyncPoint,
@@ -266,7 +266,7 @@ export function syncPointGetQueryViews(syncPoint: SyncPoint): View[] {
 
 /**
  * @param path The path to the desired complete snapshot
- * @return A complete cache, if it exists
+ * @returns A complete cache, if it exists
  */
 export function syncPointGetCompleteServerCache(
   syncPoint: SyncPoint,