Start fixing up annotations and generate API report

Author: hsubox76

common/api-review/storage.api.md

@@ -0,0 +1,60 @@
+## API Report File for "@firebase/storage"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { FirebaseApp } from '@firebase/app-types';
+import { FirebaseAuthInternalName } from '@firebase/auth-interop-types';
+import { FirebaseError } from '@firebase/util';
+import { _FirebaseService } from '@firebase/app-types';
+import { Provider } from '@firebase/component';
+import * as types from '@firebase/storage-types';
+
+// Warning: (ae-forgotten-export) The symbol "Reference" needs to be exported by the entry point index.d.ts
+//
+// @public
+export function deleteObject(ref: Reference): Promise<void>;
+
+// @public
+export function getDownloadURL(ref: Reference): Promise<string>;
+
+// Warning: (ae-forgotten-export) The symbol "Metadata" needs to be exported by the entry point index.d.ts
+//
+// @public
+export function getMetadata(ref: Reference): Promise<Metadata>;
+
+// Warning: (ae-forgotten-export) The symbol "ListOptions" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "ListResult" needs to be exported by the entry point index.d.ts
+//
+// @public
+export function list(ref: Reference, options?: ListOptions | null): Promise<ListResult>;
+
+// @public
+export function listAll(ref: Reference): Promise<ListResult>;
+
+// Warning: (ae-forgotten-export) The symbol "StorageService" needs to be exported by the entry point index.d.ts
+//
+// @public
+export function ref(storage: StorageService, url?: string): Reference;
+
+// @public
+export function ref(storageOrRef: StorageService | Reference, path?: string): Reference;
+
+// @public
+export function updateMetadata(ref: Reference, metadata: Metadata): Promise<Metadata>;
+
+// Warning: (ae-forgotten-export) The symbol "UploadTask" needs to be exported by the entry point index.d.ts
+//
+// @public
+export function uploadBytesResumable(ref: Reference, data: Blob | Uint8Array | ArrayBuffer, metadata?: Metadata | null): UploadTask;
+
+// Warning: (ae-forgotten-export) The symbol "StringFormat" needs to be exported by the entry point index.d.ts
+//
+// @public
+export function uploadString(ref: Reference, value: string, format?: StringFormat, metadata?: Metadata): UploadTask;
+
+
+// (No @packageDocumentation comment for this package)
+
+```

packages/storage/exp/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@firebase/storage/exp",
   "description": "A tree-shakeable version of the Storage SDK",
-  "main": "../dist/exp/index.browser.cjs.js",
-  "module": "../dist/exp/index.browser.esm2017.js",
-  "browser": "../dist/exp/index.browser.esm2017.js",
-  "typings": "./dist/exp/index.d.ts",
+  "main": "./dist/index.browser.cjs.js",
+  "module": "./dist/index.browser.esm2017.js",
+  "browser": "./dist/index.browser.esm2017.js",
+  "typings": "./dist/index.d.ts",
   "private": true,
   "dependencies": {
     "@firebase/app-exp": "0.0.800"

packages/storage/package.json

@@ -7,7 +7,8 @@
   "module": "dist/index.esm.js",
   "esm2017": "dist/index.esm2017.js",
   "files": [
-    "dist"
+    "dist",
+    "exp/dist"
   ],
   "scripts": {
     "lint": "eslint -c .eslintrc.js '**/*.ts' --ignore-path '../../.gitignore'",

packages/storage/src/implementation/blob.ts

@@ -25,7 +25,7 @@ import { StringFormat, dataFromString } from './string';
 import * as type from './type';
 
 /**
- * @param opt_elideCopy If true, doesn't copy mutable input data
+ * @param opt_elideCopy - If true, doesn't copy mutable input data
  *     (e.g. Uint8Arrays). Pass true only if you know the objects will not be
  *     modified after this blob's construction.
  */

packages/storage/src/implementation/error.ts

@@ -53,9 +53,6 @@ export class FirebaseStorageError extends FirebaseError {
 
 export const errors = {};
 
-/**
- * @enum {string}
- */
 export type Code = string;
 export const Code = {
   // Shared between all platforms
@@ -288,7 +285,7 @@ export function appDeleted(): FirebaseStorageError {
 }
 
 /**
- * @param name The name of the operation that was invalid.
+ * @param name - The name of the operation that was invalid.
  */
 export function invalidRootOperation(name: string): FirebaseStorageError {
   return new FirebaseStorageError(
@@ -301,8 +298,8 @@ export function invalidRootOperation(name: string): FirebaseStorageError {
 }
 
 /**
- * @param format The format that was not valid.
- * @param message A message describing the format violation.
+ * @param format - The format that was not valid.
+ * @param message - A message describing the format violation.
  */
 export function invalidFormat(
   format: string,
@@ -315,7 +312,7 @@ export function invalidFormat(
 }
 
 /**
- * @param message A message describing the internal error.
+ * @param message - A message describing the internal error.
  */
 export function internalError(message: string): FirebaseStorageError {
   throw new FirebaseStorageError(

packages/storage/src/implementation/location.ts

@@ -19,9 +19,13 @@
  * @fileoverview Functionality related to the parsing/composition of bucket/
  * object location.
  */
+
 import { invalidDefaultBucket, invalidUrl } from './error';
 import { DEFAULT_HOST } from './constants';
 
+/**
+ * @public
+ */
 export class Location {
   private path_: string;
 

packages/storage/src/implementation/request.ts

@@ -43,7 +43,7 @@ export interface Request<T> {
    * appropriate value (if the request is finished before you call this method,
    * but the promise has not yet been resolved), so don't just assume it will be
    * rejected if you call this function.
-   * @param appDelete True if the cancelation came from the app being deleted.
+   * @param appDelete - True if the cancelation came from the app being deleted.
    */
   cancel(appDelete?: boolean): void;
 }
@@ -157,7 +157,7 @@ class NetworkRequest<T> implements Request<T> {
     }
 
     /**
-     * @param requestWentThrough True if the request eventually went
+     * @param requestWentThrough - True if the request eventually went
      *     through, false if it hit the retry limit or was canceled.
      */
     function backoffDone(
@@ -241,7 +241,7 @@ class NetworkRequest<T> implements Request<T> {
 
 /**
  * A collection of information about the result of a network request.
- * @param opt_canceled Defaults to false.
+ * @param opt_canceled - Defaults to false.
  */
 export class RequestEndStatus {
   /**

packages/storage/src/implementation/string.ts

@@ -18,7 +18,7 @@
 import { unknown, invalidFormat } from './error';
 
 /**
- * @enum {string}
+ * An enumeration of the possible string formats for upload.
  */
 export type StringFormat = string;
 export const StringFormat = {
@@ -28,6 +28,9 @@ export const StringFormat = {
   DATA_URL: 'data_url'
 };
 
+/**
+ * @internal
+ */
 export class StringData {
   contentType: string | null;
 

packages/storage/src/implementation/taskenums.ts

@@ -21,7 +21,6 @@
 
 /**
  * Enum for task events.
- * @enum {string}
  */
 export type TaskEvent = string;
 export const TaskEvent = {
@@ -31,7 +30,6 @@ export const TaskEvent = {
 
 /**
  * Internal enum for task state.
- * @enum {string}
  */
 export type InternalTaskState = string;
 export const InternalTaskState = {
@@ -46,7 +44,6 @@ export const InternalTaskState = {
 
 /**
  * External (API-surfaced) enum for task state.
- * @enum {string}
  */
 export type TaskState = string;
 export const TaskState = {

packages/storage/src/implementation/xhrio.ts

@@ -20,6 +20,9 @@
  * goog.net.XhrIo-like interface.
  */
 
+/**
+ * XHR headers
+ */
 export interface Headers {
   [name: string]: string | number;
 }
@@ -50,9 +53,6 @@ export interface XhrIo {
   removeUploadProgressListener(listener: (p1: ProgressEvent) => void): void;
 }
 
-/**
- * @enum{number}
- */
 export enum ErrorCode {
   NO_ERROR = 0,
   NETWORK_ERROR = 1,

packages/storage/src/list.ts

@@ -21,8 +21,15 @@ import { Reference } from './reference';
 /**
  * @fileoverview Documentation for ListOptions and ListResult format.
  */
+
+/**
+ * The options `list()` accepts.
+ */
 export interface ListOptions extends types.ListOptions {}
 
+/**
+ * Result returned by list().
+ */
 export interface ListResult {
   prefixes: Reference[];
   items: Reference[];

packages/storage/src/metadata.ts

@@ -21,6 +21,10 @@ import { Reference } from './reference';
 /**
  * @fileoverview Documentation for the metadata format.
  */
+
+/**
+ * The full set of object metadata, including read-only properties.
+ */
 interface Metadata extends types.FullMetadata {
   type: string | undefined;
   md5Hash: string | undefined;

packages/storage/src/reference.ts

@@ -18,6 +18,7 @@
 /**
  * @fileoverview Defines the Firebase Storage Reference class.
  */
+
 import { FbsBlob } from './implementation/blob';
 import { Location } from './implementation/location';
 import { getMappings } from './implementation/metadata';
@@ -296,7 +297,7 @@ export async function getMetadata(ref: Reference): Promise<Metadata> {
  *     setting a value to null will remove the metadata.
  * @returns A promise that resolves
  *     with the new metadata for this object.
- *     @see firebaseStorage.Reference.prototype.getMetadata
+ *     See `firebaseStorage.Reference.prototype.getMetadata`
  */
 export async function updateMetadata(
   ref: Reference,

packages/storage/src/service.ts

@@ -79,18 +79,25 @@ function refFromPath(
   }
 }
 
+/**
+ * Returns a storage Reference for the given url.
+ * @param storage - `Storage` instance.
+ * @param url - URL. If empty, returns root reference.
+ * @public
+ */
 export function ref(storage: StorageService, url?: string): Reference;
-export function ref(
-  storageOrRef: StorageService | Reference,
-  path?: string
-): Reference;
 /**
- * Returns a storage Reference for the given url, or given path in the
+ * Returns a storage Reference for the given path in the
  * default bucket.
- * @param serviceOrRef - `Storage` instance or storage `Reference`.
- * @param pathOrUrlStorage - path, or URL. If empty, returns root reference (if Storage
+ * @param storageOrRef - `Storage` service or storage `Reference`.
+ * @param pathOrUrlStorage - path. If empty, returns root reference (if Storage
  * instance provided) or returns same reference (if Reference provided).
+ * @public
  */
+export function ref(
+  storageOrRef: StorageService | Reference,
+  path?: string
+): Reference;
 export function ref(
   serviceOrRef: StorageService | Reference,
   pathOrUrl?: string
@@ -118,7 +125,7 @@ function extractBucket(config?: FirebaseOptions): Location | null {
 
 /**
  * A service that provides Firebase Storage Reference instances.
- * @param opt_url gs:// url to a custom Storage Bucket
+ * @param opt_url - gs:// url to a custom Storage Bucket
  */
 export class StorageService implements _FirebaseService {
   /**
@@ -216,8 +223,8 @@ export class StorageService implements _FirebaseService {
 
   /**
    * @internal
-   * @param requestInfo
-   * @param authToken
+   * @param requestInfo - HTTP RequestInfo object
+   * @param authToken - Firebase auth token
    */
   makeRequest<T>(
     requestInfo: RequestInfo<T>,

packages/storage/src/task.ts

@@ -81,9 +81,9 @@ export class UploadTask {
   private _promise: Promise<UploadTaskSnapshot>;
 
   /**
-   * @param ref The firebaseStorage.Reference object this task came
+   * @param ref - The firebaseStorage.Reference object this task came
    *     from, untyped to avoid cyclic dependencies.
-   * @param blob The blob to upload.
+   * @param blob - The blob to upload.
    */
   constructor(ref: Reference, blob: FbsBlob, metadata: Metadata | null = null) {
     this._ref = ref;
@@ -443,7 +443,7 @@ export class UploadTask {
 
   /**
    * Adds a callback for an event.
-   * @param type The type of event to listen for.
+   * @param type - The type of event to listen for.
    */
   on(
     type: TaskEvent,
@@ -463,8 +463,8 @@ export class UploadTask {
   /**
    * This object behaves like a Promise, and resolves with its snapshot data
    * when the upload completes.
-   * @param onFulfilled The fulfillment callback. Promise chaining works as normal.
-   * @param onRejected The rejection callback.
+   * @param onFulfilled - The fulfillment callback. Promise chaining works as normal.
+   * @param onRejected - The rejection callback.
    */
   then<U>(
     onFulfilled?: ((value: UploadTaskSnapshot) => U | Promise<U>) | null,
@@ -570,7 +570,7 @@ export class UploadTask {
 
   /**
    * Resumes a paused task. Has no effect on a currently running or failed task.
-   * @return True if the operation took effect, false if ignored.
+   * @returns True if the operation took effect, false if ignored.
    */
   resume(): boolean {
     const valid =
@@ -584,7 +584,7 @@ export class UploadTask {
 
   /**
    * Pauses a currently running task. Has no effect on a paused or failed task.
-   * @return True if the operation took effect, false if ignored.
+   * @returns True if the operation took effect, false if ignored.
    */
   pause(): boolean {
     const valid = this._state === InternalTaskState.RUNNING;
@@ -597,7 +597,7 @@ export class UploadTask {
   /**
    * Cancels a currently running or paused task. Has no effect on a complete or
    * failed task.
-   * @return True if the operation took effect, false if ignored.
+   * @returns True if the operation took effect, false if ignored.
    */
   cancel(): boolean {
     const valid =