Update docs for v2 storage (#1104)

* Update docs for v2 storage

Author: TheIronDev

src/v2/providers/storage.ts

@@ -192,107 +192,257 @@ export const metadataUpdatedEvent =
 
 /** StorageOptions extend EventHandlerOptions with a bucket name  */
 export interface StorageOptions extends options.EventHandlerOptions {
+  /** The name of the bucket containing this object. */
   bucket?: string;
 }
 
-/** Handle a storage object archived */
+/**
+ * Event handler sent only when a bucket has enabled object versioning.
+ * This event indicates that the live version of an object has become an
+ * archived version, either because it was archived or because it was
+ * overwritten by the upload of an object of the same name.
+ *
+ * @param handler - Event handler which is run every time a Google Cloud Storage archival occurs.
+ */
 export function onObjectArchived(
   handler: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent>;
 
+/**
+ * Event handler sent only when a bucket has enabled object versioning.
+ * This event indicates that the live version of an object has become an
+ * archived version, either because it was archived or because it was
+ * overwritten by the upload of an object of the same name.
+ *
+ * @param bucket - The name of the bucket containing this object.
+ * @param handler - Event handler which is run every time a Google Cloud Storage archival occurs.
+ */
 export function onObjectArchived(
   bucket: string,
   handler: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent>;
 
+/**
+ * Event handler sent only when a bucket has enabled object versioning.
+ * This event indicates that the live version of an object has become an
+ * archived version, either because it was archived or because it was
+ * overwritten by the upload of an object of the same name.
+ *
+ * @param opts - Options that can be set on an individual event-handling function.
+ * @param handler - Event handler which is run every time a Google Cloud Storage archival occurs.
+ */
 export function onObjectArchived(
   opts: StorageOptions,
   handler: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent>;
 
+/**
+ * Event handler sent only when a bucket has enabled object versioning.
+ * This event indicates that the live version of an object has become an
+ * archived version, either because it was archived or because it was
+ * overwritten by the upload of an object of the same name.
+ *
+ * @param bucketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used.
+ * @param handler - Event handler which is run every time a Google Cloud Storage archival occurs.
+ */
 export function onObjectArchived(
-  buketOrOptsOrHandler:
+  bucketOrOptsOrHandler:
     | string
     | StorageOptions
     | ((event: StorageEvent) => any | Promise<any>),
   handler?: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent> {
-  return onOperation(archivedEvent, buketOrOptsOrHandler, handler);
+  return onOperation(archivedEvent, bucketOrOptsOrHandler, handler);
 }
 
-/** Handle a storage object finalized */
+/**
+ * Event handler which fires every time a Google Cloud Storage object
+ * creation occurs.
+ *
+ * Sent when a new object (or a new generation of an existing object)
+ * is successfully created in the bucket. This includes copying or rewriting
+ * an existing object. A failed upload does not trigger this event.
+ *
+ * @param handler - Event handler which is run every time a Google Cloud Storage object creation occurs.
+ */
 export function onObjectFinalized(
   handler: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent>;
 
+/**
+ * Event handler which fires every time a Google Cloud Storage object
+ * creation occurs.
+ *
+ * Sent when a new object (or a new generation of an existing object)
+ * is successfully created in the bucket. This includes copying or rewriting
+ * an existing object. A failed upload does not trigger this event.
+ *
+ * @param bucket - The name of the bucket containing this object.
+ * @param handler - Event handler which is run every time a Google Cloud Storage object creation occurs.
+ */
 export function onObjectFinalized(
   bucket: string,
   handler: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent>;
 
+/**
+ * Event handler which fires every time a Google Cloud Storage object
+ * creation occurs.
+ *
+ * Sent when a new object (or a new generation of an existing object)
+ * is successfully created in the bucket. This includes copying or rewriting
+ * an existing object. A failed upload does not trigger this event.
+ *
+ * @param opts - Options that can be set on an individual event-handling function.
+ * @param handler - Event handler which is run every time a Google Cloud Storage object creation occurs.
+ */
 export function onObjectFinalized(
   opts: StorageOptions,
   handler: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent>;
 
+/**
+ * Event handler which fires every time a Google Cloud Storage object
+ * creation occurs.
+ *
+ * Sent when a new object (or a new generation of an existing object)
+ * is successfully created in the bucket. This includes copying or rewriting
+ * an existing object. A failed upload does not trigger this event.
+ *
+ * @param bucketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used.
+ * @param handler - Event handler which is run every time a Google Cloud Storage object creation occurs.
+ */
 export function onObjectFinalized(
-  buketOrOptsOrHandler:
+  bucketOrOptsOrHandler:
     | string
     | StorageOptions
     | ((event: StorageEvent) => any | Promise<any>),
   handler?: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent> {
-  return onOperation(finalizedEvent, buketOrOptsOrHandler, handler);
+  return onOperation(finalizedEvent, bucketOrOptsOrHandler, handler);
 }
 
-/** Handle a storage object deleted */
+/**
+ * Event handler which fires every time a Google Cloud Storage deletion occurs.
+ *
+ * Sent when an object has been permanently deleted. This includes objects
+ * that are overwritten or are deleted as part of the bucket's lifecycle
+ * configuration. For buckets with object versioning enabled, this is not
+ * sent when an object is archived, even if archival occurs
+ * via the `storage.objects.delete` method.
+ *
+ * @param handler - Event handler which is run every time a Google Cloud Storage object deletion occurs.
+ */
 export function onObjectDeleted(
   handler: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent>;
 
+/**
+ * Event handler which fires every time a Google Cloud Storage deletion occurs.
+ *
+ * Sent when an object has been permanently deleted. This includes objects
+ * that are overwritten or are deleted as part of the bucket's lifecycle
+ * configuration. For buckets with object versioning enabled, this is not
+ * sent when an object is archived, even if archival occurs
+ * via the `storage.objects.delete` method.
+ *
+ * @param bucket - The name of the bucket containing this object.
+ * @param handler - Event handler which is run every time a Google Cloud Storage object deletion occurs.
+ */
 export function onObjectDeleted(
   bucket: string,
   handler: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent>;
 
+/**
+ * Event handler which fires every time a Google Cloud Storage deletion occurs.
+ *
+ * Sent when an object has been permanently deleted. This includes objects
+ * that are overwritten or are deleted as part of the bucket's lifecycle
+ * configuration. For buckets with object versioning enabled, this is not
+ * sent when an object is archived, even if archival occurs
+ * via the `storage.objects.delete` method.
+ *
+ * @param opts - Options that can be set on an individual event-handling function.
+ * @param handler - Event handler which is run every time a Google Cloud Storage object deletion occurs.
+ */
 export function onObjectDeleted(
   opts: StorageOptions,
   handler: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent>;
 
+/**
+ * Event handler which fires every time a Google Cloud Storage deletion occurs.
+ *
+ * Sent when an object has been permanently deleted. This includes objects
+ * that are overwritten or are deleted as part of the bucket's lifecycle
+ * configuration. For buckets with object versioning enabled, this is not
+ * sent when an object is archived, even if archival occurs
+ * via the `storage.objects.delete` method.
+ *
+ * @param bucketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used.
+ * @param handler - Event handler which is run every time a Google Cloud Storage object deletion occurs.
+ */
 export function onObjectDeleted(
-  buketOrOptsOrHandler:
+  bucketOrOptsOrHandler:
     | string
     | StorageOptions
     | ((event: StorageEvent) => any | Promise<any>),
   handler?: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent> {
-  return onOperation(deletedEvent, buketOrOptsOrHandler, handler);
+  return onOperation(deletedEvent, bucketOrOptsOrHandler, handler);
 }
 
-/** Handle a storage object metadata updated */
+/**
+ * Event handler which fires every time the metadata of an existing object
+ * changes.
+ *
+ * @param bucketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used.
+ * @param handler - Event handler which is run every time a Google Cloud Storage object metadata update occurs.
+ */
 export function onObjectMetadataUpdated(
   handler: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent>;
 
+/**
+ * Event handler which fires every time the metadata of an existing object
+ * changes.
+ *
+ * @param bucket - The name of the bucket containing this object.
+ * @param handler - Event handler which is run every time a Google Cloud Storage object metadata update occurs.
+ */
 export function onObjectMetadataUpdated(
   bucket: string,
   handler: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent>;
 
+/**
+ * Event handler which fires every time the metadata of an existing object
+ * changes.
+ *
+ * @param opts - Options that can be set on an individual event-handling function.
+ * @param handler - Event handler which is run every time a Google Cloud Storage object metadata update occurs.
+ */
 export function onObjectMetadataUpdated(
   opts: StorageOptions,
   handler: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent>;
 
+/**
+ * Event handler which fires every time the metadata of an existing object
+ * changes.
+ *
+ * @param bucketOrOptsOrHandler - Options or string that may (or may not) define the bucket to be used.
+ * @param handler - Event handler which is run every time a Google Cloud Storage object metadata update occurs.
+ */
 export function onObjectMetadataUpdated(
-  buketOrOptsOrHandler:
+  bucketOrOptsOrHandler:
     | string
     | StorageOptions
     | ((event: StorageEvent) => any | Promise<any>),
   handler?: (event: StorageEvent) => any | Promise<any>
 ): CloudFunction<StorageEvent> {
-  return onOperation(metadataUpdatedEvent, buketOrOptsOrHandler, handler);
+  return onOperation(metadataUpdatedEvent, bucketOrOptsOrHandler, handler);
 }
 
 /** @internal */