Extensions TSDoc edits (#1982)

Author: kevinthecheung

src/extensions/extensions-api.ts

@@ -16,14 +16,29 @@
  */
 
 /**
- * SettableProcessingState represents all the Processing states that can be set on an ExtensionInstance's runtimeData.
+ * `SettableProcessingState` represents all the processing states that can be set
+ * on an Extension instance's runtime data.
  * 
- * - NONE: No relevant lifecycle event work has been done. Set this to clear out old statuses.
- * - PROCESSING_COMPLETE: Lifecycle event work completed with no errors.
- * - PROCESSING_WARNING: Lifecycle event work succeeded partially,
- *                        or something happened that the user should be warned about.
- * - PROCESSING_FAILED: Lifecycle event work failed completely,
- *                        but the instance will still work correctly going forward.
- * - If the extension instance is in a broken state due to the errors, instead set FatalError.
+ * @remarks
+ * You can set the following states:
+ * 
+ * - `NONE`: No relevant lifecycle event work has been done.
+ *   Set this to clear out old statuses.
+ * 
+ * - `PROCESSING_COMPLETE`: Lifecycle event work completed with no errors.
+ * 
+ * - `PROCESSING_WARNING`: Lifecycle event work succeeded partially, or
+ *   something happened that the user should be warned about.
+ * 
+ * - `PROCESSING_FAILED`: Lifecycle event work failed completely, but the
+ *   instance will still work correctly going forward.
+ * 
+ * If the extension instance is in a broken state due to errors, instead call
+ * {@link Runtime.setFatalError}.
+ * 
+ * The "processing" state gets set automatically when a lifecycle event handler
+ * starts; you can't set it explicitly.
+ * To report the ongoing status of an extension's function, use `console.log`
+ * or the Cloud Functions logger SDK.
  */
 export type SettableProcessingState = 'NONE' | 'PROCESSING_COMPLETE' | 'PROCESSING_WARNING' | 'PROCESSING_FAILED';

src/extensions/extensions.ts

@@ -37,6 +37,7 @@ export class Extensions {
   /**
    * The runtime() method returns a new Runtime, which provides methods to modify an extension instance's runtime data.
    *
+   * @remarks
    * This method will throw an error if called outside an Extensions environment.
    * 
    * @returns A new {@link Runtime} object.
@@ -78,9 +79,14 @@ export class Runtime {
   /**
    * Sets the processing state of an extension instance.
    *
-   * Use this method to report the results of a lifecycle event handler. If the 
-   * lifecycle event failed & the extension instance will no longer work 
-   * correctly, use `setFatalError` instead.
+   * @remarks
+   * Use this method to report the results of a lifecycle event handler.
+   * 
+   * If the lifecycle event failed & the extension instance will no longer work
+   * correctly, use {@link Runtime.setFatalError} instead.
+   * 
+   * To report the status of function calls other than lifecycle event handlers,
+   * use `console.log` or the Cloud Functions logger SDK.
    * 
    * @param state - The state to set the instance to.
    * @param detailMessage - A message explaining the results of the lifecycle function.
@@ -101,6 +107,7 @@ export class Runtime {
   /**
    * Reports a fatal error while running a lifecycle event handler.
    *
+   * @remarks
    * Call this method when a lifecycle event handler fails in a way that makes 
    * the Instance inoperable.
    * If the lifecycle event failed but the instance will still work as expected,