Update pubsub docs (#1106)

* Update pubsub docs

Author: TheIronDev

src/providers/pubsub.ts

@@ -39,8 +39,8 @@ export const service = 'pubsub.googleapis.com';
  * Registers a Cloud Function triggered when a Google Cloud Pub/Sub message
  * is sent to a specified topic.
  *
- * @param topic The Pub/Sub topic to watch for message events.
- * @return Pub/Sub topic builder interface.
+ * @param topic - The Pub/Sub topic to watch for message events.
+ * @returns Pub/Sub topic builder interface.
  */
 export function topic(topic: string) {
   return _topicWithOptions(topic, {});
@@ -79,7 +79,7 @@ export class TopicBuilder {
    * Event handler that fires every time a Cloud Pub/Sub message is
    * published.
    *
-   * @param handler Event handler that runs every time a Cloud Pub/Sub message
+   * @param handler - Event handler that runs every time a Cloud Pub/Sub message
    *   is published.
    * @return A Cloud Function that you can export and deploy.
    */
@@ -101,7 +101,7 @@ export class TopicBuilder {
 /**
  * Registers a Cloud Function to run at specified times.
  *
- * @param schedule The schedule, in Unix Crontab or AppEngine syntax.
+ * @param schedule - The schedule, in Unix Crontab or AppEngine syntax.
  * @return ScheduleBuilder interface.
  */
 export function schedule(schedule: string): ScheduleBuilder {
@@ -156,7 +156,7 @@ export class ScheduleBuilder {
    * Event handler for scheduled functions. Triggered whenever the associated
    * scheduler job sends a Pub/Sub message.
    *
-   * @param handler Handler that fires whenever the associated
+   * @param handler - Handler that fires whenever the associated
    *   scheduler job sends a Pub/Sub message.
    * @return A Cloud Function that you can export and deploy.
    */
@@ -177,7 +177,7 @@ export class ScheduleBuilder {
 /**
  * Interface representing a Google Cloud Pub/Sub message.
  *
- * @param data Payload of a Pub/Sub message.
+ * @param data - Payload of a Pub/Sub message.
  */
 export class Message {
   /**

src/v2/providers/pubsub.ts

@@ -3,10 +3,27 @@ import { ManifestEndpoint } from '../../runtime/manifest';
 import { CloudEvent, CloudFunction } from '../core';
 import * as options from '../options';
 
+/**
+ * A PubSub Topic is:
+ * <ul>
+ *   <li>A resource that you can publish messages to and then consume those messages via subscriptions.
+ *   <li>An isolated data stream for Pub/Sub messages.
+ *   <li>Messages are published to a topic.
+ *   <li>Messages are listened to via a subscription.
+ *   <li>Each subscription listens to the messages published to exactly one topic.
+ */
+export type PubSubTopic = string;
+
+/**
+ * Resource that listens to the messages published by exactly one topic.
+ */
+export type PubSubSubscription = string;
+
 /**
  * Interface representing a Google Cloud Pub/Sub message.
  *
- * @param data Payload of a Pub/Sub message.
+ * @param data - Payload of a Pub/Sub message.
+ * @typeParam T - Type representing `Message.data`'s JSON format
  */
 export class Message<T> {
   /**
@@ -68,7 +85,7 @@ export class Message<T> {
   /**
    * Returns a JSON-serializable representation of this object.
    *
-   * @return A JSON-serializable representation of this object.
+   * @returns A JSON-serializable representation of this object.
    */
   toJSON(): any {
     const json: Record<string, any> = {
@@ -86,29 +103,51 @@ export class Message<T> {
   }
 }
 
-/** The interface published in a Pub/Sub publish subscription. */
+/**
+ * The interface published in a Pub/Sub publish subscription.
+ * @typeParam T - Type representing `Message.data`'s JSON format
+ */
 export interface MessagePublishedData<T = any> {
+  /**  Google Cloud Pub/Sub message. */
   readonly message: Message<T>;
-  readonly subscription: string;
+  /** A subscription resource. */
+  readonly subscription: PubSubSubscription;
 }
 
 /** PubSubOptions extend EventHandlerOptions but must include a topic. */
 export interface PubSubOptions extends options.EventHandlerOptions {
-  topic: string;
+  /** The Pub/Sub topic to watch for message events */
+  topic: PubSubTopic;
 }
 
-/** Handle a message being published to a Pub/Sub topic. */
+/**
+ * Handle a message being published to a Pub/Sub topic.
+ * @param topic - The Pub/Sub topic to watch for message events.
+ * @param handler - runs every time a Cloud Pub/Sub message is published
+ * @typeParam T - Type representing `Message.data`'s JSON format
+ */
 export function onMessagePublished<T = any>(
-  topic: string,
+  topic: PubSubTopic,
   handler: (event: CloudEvent<MessagePublishedData<T>>) => any | Promise<any>
 ): CloudFunction<CloudEvent<MessagePublishedData<T>>>;
 
-/** Handle a message being published to a Pub/Sub topic. */
+/**
+ * Handle a message being published to a Pub/Sub topic.
+ * @param options - Option containing information (topic) for event
+ * @param handler - runs every time a Cloud Pub/Sub message is published
+ * @typeParam T - Type representing `Message.data`'s JSON format
+ */
 export function onMessagePublished<T = any>(
   options: PubSubOptions,
   handler: (event: CloudEvent<MessagePublishedData<T>>) => any | Promise<any>
 ): CloudFunction<CloudEvent<MessagePublishedData<T>>>;
 
+/**
+ * Handle a message being published to a Pub/Sub topic.
+ * @param topicOrOptions - A string representing the PubSub topic or an option (which contains the topic)
+ * @param handler - runs every time a Cloud Pub/Sub message is published
+ * @typeParam T - Type representing `Message.data`'s JSON format
+ */
 export function onMessagePublished<T = any>(
   topicOrOptions: string | PubSubOptions,
   handler: (event: CloudEvent<MessagePublishedData<T>>) => any | Promise<any>
@@ -127,7 +166,7 @@ export function onMessagePublished<T = any>(
   const func = (raw: CloudEvent<unknown>) => {
     const messagePublishedData = raw.data as {
       message: unknown;
-      subscription: string;
+      subscription: PubSubSubscription;
     };
     messagePublishedData.message = new Message(messagePublishedData.message);
     return handler(raw as CloudEvent<MessagePublishedData<T>>);