Add JSDoc for bundles #4155

wu-hui · 2020-12-03T15:27:56Z

No description provided.

changeset-bot · 2020-12-03T15:27:59Z

⚠️ No Changeset found

Latest commit: 29e76c9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

google-oss-bot · 2020-12-03T15:50:48Z

Size Analysis Report

Affected Products

No changes between base commit (cc8dd9c) and head commit (29f957a).

Test Logs

Base (cc8dd9cd): https://github.com/firebase/firebase-js-sdk/actions/runs/398560160
Head (29f957ae): https://github.com/firebase/firebase-js-sdk/actions/runs/401249630

packages/firebase/index.d.ts

schmidt-sebastian · 2020-12-03T18:15:02Z

packages/firebase/index.d.ts

  export interface LoadBundleTaskProgress {
+    /** How many documents have been loaded. */


I noticed that you removed these in the other PR. You should leave the comments in both places as firestore-exp builds its d.ts file from source.

Yeah, that was a bad merge i think. Will keep the comments.

markarndt · 2020-12-03T19:19:40Z

Few edits sprinkled in above....

Co-authored-by: Sebastian Schmidt <mrschmidt@google.com>

schmidt-sebastian · 2020-12-03T22:11:53Z

packages/firebase/index.d.ts

+    /**
+     * Registers functions to listen to bundle loading progresses.
+     * @param next Called there is a progress update from bundle loading, typically whenever
+     *        a Firestore document is loaded it will generate a progress update.


Please fix indent to match the rest of this file.

markarndt · 2020-12-03T18:52:01Z

packages/firebase/index.d.ts

+    /**
+     * Loads a Firestore bundle into the local cache.
+     *
+     * @param bundleData An object representing the bundle to be load, could be a `ArrayBuffer`,


"...representing the bundle to be loaded. Valid objects are ArrayBuffer, ReadableStream<Uint8Array> or string."

markarndt · 2020-12-03T18:53:53Z

packages/firebase/index.d.ts

+     *        a `ReadableStream<Uint8Array>` or a `string`.
+     *
+     * @return A `LoadBundleTask` object, which notifies callers with progress update, completion
+     *        or error event. It can be used as a `Promise<LoadBundleTaskProgress>`.


"...notifies callers with progress updates, and completion or error events."

markarndt · 2020-12-03T18:57:10Z

packages/firebase/index.d.ts

    ): LoadBundleTask;

+    /**
+     * Reads a Firestore query from local cache that is associated to a given name.


"Reads a Firestore named query from local cache."

Here it actually reads a Query object, I added back ticks to make it clear.

markarndt · 2020-12-03T19:07:14Z

packages/firebase/index.d.ts

+    /**
+     * Reads a Firestore query from local cache that is associated to a given name.
+     *
+     * The named queries are from bundles, and saved as a result of `loadBundle`. `namedQuery`


Something like:
"Named queries are a feature of Firestore bundles. Named queries and related data are packaged into a binary bundle on the server side, the bundle is fetched by the client over the network, and the bundle is loaded to local cache using the loadBundle method. Once in local cache, use this method to extract a query from the bundle by name. Once extracted, the named query is simply a Firestore Query object."

Done..more or less similar.

markarndt · 2020-12-03T19:08:18Z

packages/firebase/index.d.ts

@@ -8303,31 +8319,71 @@ declare namespace firebase.firestore {
    INTERNAL: { delete: () => Promise<void> };
  }

+  /**
+   * Represents the task of loading a Firestore bundle. It provides progress of the bundle


"...provides progress of bundle loading, as well as task completion and error events."

markarndt · 2020-12-03T19:08:44Z

packages/firebase/index.d.ts

  export interface LoadBundleTask {
+    /**
+     * Registers functions to listen to bundle loading progresses.


"...to listen to bundle loading progress events."

markarndt · 2020-12-03T19:10:08Z

packages/firebase/index.d.ts

  export interface LoadBundleTask {
+    /**
+     * Registers functions to listen to bundle loading progresses.
+     * @param next Called there is a progress update from bundle loading, typically whenever


"Called when there is a.... Typically, next calls occur each time a Firestore document is loaded from the bundle."

markarndt · 2020-12-03T19:12:58Z

packages/firebase/index.d.ts

+     * Registers functions to listen to bundle loading progresses.
+     * @param next Called there is a progress update from bundle loading, typically whenever
+     *        a Firestore document is loaded it will generate a progress update.
+     * @param error Called when there is an error occurred from loading the bundle. The task


"Called when an error occurs during bundle loading...."

Hmm, if there are important edge cases in "there should be no more updates after this" then let's add?

Done. Not sure what you mean by second statement.

markarndt · 2020-12-03T19:15:32Z

packages/firebase/index.d.ts

+    /**
+     * Implements a `Promise<LoadBundleTaskProgress>` interface.
+     *
+     * @param onFulfilled It is called with the compeltion `LoadBundleTaskProgress` when the


Remove "It is..." in both params and start with "Called..."

Are there status codes for LoadBundleTaskProgress termination?

For unFulfilled: "Called on completion of LoadBundleTaskProgress when completion status is XXX."
For unRejected: "Called on completion of LoadBundleTaskProgress when completion status is XXX."

There is no status code.

markarndt · 2020-12-03T19:16:05Z

packages/firebase/index.d.ts

+    /**
+     * Implements a `Promise<LoadBundleTaskProgress>` interface.
+     *
+     * @param onRejected It is called when there is an error occurred from loading the bundle.


See above...

Done, but without mentioning status code.

markarndt · 2020-12-04T17:40:33Z

packages/firebase/index.d.ts

+     * Loads a Firestore bundle into the local cache.
+     *
+     * @param bundleData
+     *   An object representing the bundle to be load. Valid objects are `ArrayBuffer`,


"...bundle to be loaded. Valid..."

markarndt · 2020-12-04T17:40:55Z

packages/firebase/index.d.ts

+     *   `ReadableStream<Uint8Array>` or `string`.
+     *
+     * @return
+     *   A `LoadBundleTask` object, which notifies callers with progress update, and completion


"...with progress updates, and..."

markarndt · 2020-12-04T17:41:47Z

packages/firebase/index.d.ts

+    /**
+     * Registers functions to listen to bundle loading progress events.
+     * @param next
+     *   Called when there is a progress update from bundle loading, typically `next` calls occur


...from bundle loading. Typically, next calls..."

markarndt · 2020-12-04T17:42:53Z

packages/firebase/index.d.ts

+     * Implements the `Promise<LoadBundleTaskProgress>.then` interface.
+     *
+     * @param onFulfilled
+     *   Called on the completion with a `LoadBundleTaskProgress` update when the


This one was a little unclear. Maybe this edit will help, but please clarify "the completion of" what? Completion of the progress update?

"Called on completion of a LoadBundleTaskProgress update when..."

markarndt · 2020-12-04T17:52:21Z

packages/firebase/index.d.ts

    ): LoadBundleTask;

+    /**
+     * Reads a Firestore `Query` from local cache that is associated to a given name.


"Reads a Firestore Query from local cache, identified by name."

"Bundles can contain named queries. These named queries are packaged..."

markarndt

Great.

* Add bundles to d.ts and rearrange bundles source code for building it as a separate module (#4120) * Add bundles to d.ts and rearrange bundles source code for building it as a separate module. * Roll bundle with prebuilt (#4128) Build firestore sdks with prebuilt to support bundle as a prototype patched feature. * Add JSDoc for bundles (#4155) Add JSDoc for bundles. * Create changeset * Update old-lobsters-pull.md * A few fixes for Firestore bundle sdk builds (#4177) * Actually creates firebase/firestore/bundle package.json * Fix standard node/browser builds for bundles * Make it release from remote branch. * Add bundle to firebase complete build and fix missing proto for memory build. * Make rollup.config.js more organized. * Revert "Make it release from remote branch." This reverts commit 2c91fd1. * 2017 -> 2020 * Update comment. * Address comments * Update .changeset/old-lobsters-pull.md Co-authored-by: Sebastian Schmidt <mrschmidt@google.com> * Update .changeset/old-lobsters-pull.md Co-authored-by: Sebastian Schmidt <mrschmidt@google.com> * Add toc. * Remove webpack change. Co-authored-by: Sebastian Schmidt <mrschmidt@google.com>

Add JSDoc for bundles

5c653d1

wu-hui requested a review from schmidt-sebastian December 3, 2020 15:28

wu-hui assigned schmidt-sebastian Dec 3, 2020

wu-hui requested a review from markarndt December 3, 2020 15:28

wu-hui assigned markarndt Dec 3, 2020

schmidt-sebastian reviewed Dec 3, 2020

View reviewed changes

schmidt-sebastian assigned wu-hui and unassigned schmidt-sebastian and markarndt Dec 3, 2020

wu-hui and others added 5 commits December 3, 2020 16:58

Update packages/firebase/index.d.ts

2b34954

Co-authored-by: Sebastian Schmidt <mrschmidt@google.com>

Update packages/firebase/index.d.ts

399f2a7

Co-authored-by: Sebastian Schmidt <mrschmidt@google.com>

Update packages/firebase/index.d.ts

ff81706

Co-authored-by: Sebastian Schmidt <mrschmidt@google.com>

Update packages/firebase/index.d.ts

7ab05ee

Co-authored-by: Sebastian Schmidt <mrschmidt@google.com>

Better JSDoc

21f5cdf

schmidt-sebastian reviewed Dec 3, 2020

View reviewed changes

schmidt-sebastian approved these changes Dec 3, 2020

View reviewed changes

Fix indention.

1456277

markarndt reviewed Dec 4, 2020

View reviewed changes

Addressing more nits.

eebb68b

wu-hui assigned markarndt and unassigned wu-hui Dec 4, 2020

markarndt approved these changes Dec 4, 2020

View reviewed changes

Addessing even more comments.

29e76c9

markarndt approved these changes Dec 4, 2020

View reviewed changes

wu-hui merged commit 705b30f into wuandy/ReleaseBundles Dec 4, 2020

firebase locked and limited conversation to collaborators Jan 4, 2021

		export interface LoadBundleTaskProgress {
		/** How many documents have been loaded. */

Add JSDoc for bundles #4155

Add JSDoc for bundles #4155

Conversation

wu-hui commented Dec 3, 2020

changeset-bot bot commented Dec 3, 2020 • edited Loading

⚠️ No Changeset found

google-oss-bot commented Dec 3, 2020 • edited Loading

Size Analysis Report

Affected Products

Test Logs

Choose a reason for hiding this comment

Choose a reason for hiding this comment

markarndt commented Dec 3, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

markarndt left a comment

Choose a reason for hiding this comment

changeset-bot bot commented Dec 3, 2020 •

edited

Loading

google-oss-bot commented Dec 3, 2020 •

edited

Loading