From 7dd4ff91c1a995e0e35b7e88accbf1c975d6574a Mon Sep 17 00:00:00 2001 From: Kevin Cheung Date: Thu, 17 Nov 2022 10:10:12 -0800 Subject: [PATCH 1/6] TSDoc formatting --- src/extensions/extensions-api.ts | 12 ++++++++++-- src/extensions/extensions.ts | 3 +++ 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/src/extensions/extensions-api.ts b/src/extensions/extensions-api.ts index b5ef4fcb56..f4a3e61a99 100644 --- a/src/extensions/extensions-api.ts +++ b/src/extensions/extensions-api.ts @@ -16,14 +16,22 @@ */ /** - * 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 ExtensionInstance's runtimeData. * + * @remarks * - 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. + * + * - If the extension instance is in a broken state due to errors, instead set FatalError. + * + * - To report ongoing (non-final) status, use `console.log` or the Cloud Functions logger SDK. */ export type SettableProcessingState = 'NONE' | 'PROCESSING_COMPLETE' | 'PROCESSING_WARNING' | 'PROCESSING_FAILED'; diff --git a/src/extensions/extensions.ts b/src/extensions/extensions.ts index c4f6485539..880d40d19e 100644 --- a/src/extensions/extensions.ts +++ b/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,6 +79,7 @@ export class Runtime { /** * Sets the processing state of an extension instance. * + * @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 `setFatalError` instead. @@ -101,6 +103,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, From aeb87012080e17812015b618851589ad6f7e40a2 Mon Sep 17 00:00:00 2001 From: Kevin Cheung Date: Thu, 17 Nov 2022 10:17:01 -0800 Subject: [PATCH 2/6] Typo --- src/extensions/extensions-api.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/extensions/extensions-api.ts b/src/extensions/extensions-api.ts index f4a3e61a99..12cd25938f 100644 --- a/src/extensions/extensions-api.ts +++ b/src/extensions/extensions-api.ts @@ -17,7 +17,7 @@ /** * SettableProcessingState represents all the Processing states that can be set - * on an ExtensionInstance's runtimeData. + * on an Extension instance's runtimeData. * * @remarks * - NONE: No relevant lifecycle event work has been done. Set this to clear out old statuses. From 0897b2a00d2bd2046384c3273546c6ace095e265 Mon Sep 17 00:00:00 2001 From: Kevin Cheung Date: Thu, 17 Nov 2022 10:19:37 -0800 Subject: [PATCH 3/6] p --- src/extensions/extensions-api.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/extensions/extensions-api.ts b/src/extensions/extensions-api.ts index 12cd25938f..800a9a5d8a 100644 --- a/src/extensions/extensions-api.ts +++ b/src/extensions/extensions-api.ts @@ -16,7 +16,7 @@ */ /** - * SettableProcessingState represents all the Processing states that can be set + * SettableProcessingState represents all the processing states that can be set * on an Extension instance's runtimeData. * * @remarks From 019bea4a28249f924df24b9c9194ef1010baf27a Mon Sep 17 00:00:00 2001 From: Kevin Cheung Date: Thu, 17 Nov 2022 11:03:47 -0800 Subject: [PATCH 4/6] Edits --- src/extensions/extensions-api.ts | 25 +++++++++++++++---------- src/extensions/extensions.ts | 10 +++++++--- 2 files changed, 22 insertions(+), 13 deletions(-) diff --git a/src/extensions/extensions-api.ts b/src/extensions/extensions-api.ts index 800a9a5d8a..34ceb5e4e2 100644 --- a/src/extensions/extensions-api.ts +++ b/src/extensions/extensions-api.ts @@ -16,22 +16,27 @@ */ /** - * SettableProcessingState represents all the processing states that can be set - * on an Extension instance's runtimeData. + * `SettableProcessingState` represents all the processing states that can be set + * on an Extension instance's runtime data. * * @remarks - * - NONE: No relevant lifecycle event work has been done. Set this to clear out old statuses. + * You can set the following states: * - * - PROCESSING_COMPLETE: Lifecycle event work completed with no errors. + * - `NONE`: No relevant lifecycle event work has been done. + * Set this to clear out old statuses. * - * - PROCESSING_WARNING: Lifecycle event work succeeded partially, - * or something happened that the user should be warned about. + * - `PROCESSING_COMPLETE`: Lifecycle event work completed with no errors. * - * - PROCESSING_FAILED: Lifecycle event work failed completely, - * but the instance will still work correctly going forward. + * - `PROCESSING_WARNING`: Lifecycle event work succeeded partially, or + * something happened that the user should be warned about. * - * - If the extension instance is in a broken state due to errors, instead set FatalError. + * - `PROCESSING_FAILED`: Lifecycle event work failed completely, but the + * instance will still work correctly going forward. * - * - To report ongoing (non-final) status, use `console.log` or the Cloud Functions logger SDK. + * If the extension instance is in a broken state due to errors, instead call + * {@link Runtime.setFatalError}. + * + * There is no "processing in progress" state. 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'; diff --git a/src/extensions/extensions.ts b/src/extensions/extensions.ts index 880d40d19e..e16f893aa0 100644 --- a/src/extensions/extensions.ts +++ b/src/extensions/extensions.ts @@ -80,9 +80,13 @@ export class Runtime { * Sets the processing state of an extension instance. * * @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 `setFatalError` instead. + * 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. From b4f01aef7ea9c4e08cc1d7b09d68575e988bee13 Mon Sep 17 00:00:00 2001 From: Kevin Cheung Date: Thu, 17 Nov 2022 11:17:07 -0800 Subject: [PATCH 5/6] Edit --- src/extensions/extensions-api.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/extensions/extensions-api.ts b/src/extensions/extensions-api.ts index 34ceb5e4e2..72db116bb0 100644 --- a/src/extensions/extensions-api.ts +++ b/src/extensions/extensions-api.ts @@ -36,7 +36,9 @@ * If the extension instance is in a broken state due to errors, instead call * {@link Runtime.setFatalError}. * - * There is no "processing in progress" state. To report the ongoing status of - * an extension's function, use `console.log` or the Cloud Functions logger SDK. + * The "processing" state gets set automatically when a lifecycle event handler + * runs; 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'; From e2de65cdc36492f119925085102c97467c351c40 Mon Sep 17 00:00:00 2001 From: Kevin Cheung Date: Thu, 17 Nov 2022 11:20:07 -0800 Subject: [PATCH 6/6] Tweak --- src/extensions/extensions-api.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/extensions/extensions-api.ts b/src/extensions/extensions-api.ts index 72db116bb0..ce0c18f89d 100644 --- a/src/extensions/extensions-api.ts +++ b/src/extensions/extensions-api.ts @@ -37,7 +37,7 @@ * {@link Runtime.setFatalError}. * * The "processing" state gets set automatically when a lifecycle event handler - * runs; you can't set it explicitly. + * 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. */