From 69dc7da844672249a86b9b0584a0e5932f5da9b8 Mon Sep 17 00:00:00 2001
From: RomanTsukanov <RomanTsukanov@users.noreply.github.com>
Date: Fri, 30 Jun 2023 15:19:24 +0400
Subject: [PATCH] Update triggers, actions, and Service-related API
 descriptions (#6453)

* Update triggers, actions, and Service-related API descriptions

* Revert some changes

* Update src/survey-events-api.ts

Co-authored-by: annnke <anna.bakulina@devexpress.com>

---------

Co-authored-by: annnke <anna.bakulina@devexpress.com>
---
 src/survey-events-api.ts | 30 ++++++++----
 src/survey.ts            | 98 ++++++++++++++++++++++------------------
 2 files changed, 76 insertions(+), 52 deletions(-)

diff --git a/src/survey-events-api.ts b/src/survey-events-api.ts
index f1d94b29ea..c35070e524 100644
--- a/src/survey-events-api.ts
+++ b/src/survey-events-api.ts
@@ -439,32 +439,46 @@ export interface TextRenderAsEvent extends TextProcessingEvent {
 
 export interface SendResultEvent {
   /**
-   * a response from the service
+   * A server [response](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/response).
    */
   response: any;
   request: any;
   /**
-   * it is `true` if the results has been sent to the service successfully
+   * A Boolean value that indicates whether survey results have been saved successfully.
    */
   success: boolean;
 }
 export interface GetResultEvent {
   /**
-   * the server response
+   * A server [response](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/response).
    */
   response: any;
   /**
-   * an array of objects `{name, value}`, where `name` is a unique value/answer to the question and `value` is a number/count of such answers
+   * A Boolean value that indicates whether survey results have been retrieved successfully.
    */
-  dataList: Array<any>;
+  success: boolean;
   /**
-   * the object `{AnswersCount, QuestionResult : {} }`. `AnswersCount` is the number of posted survey results. `QuestionResult` is an object with all possible unique answers to the question and number of these answers
+   * An object with the following structure:
+   *
+   * ```js
+   * {
+   *   AnswersCount: Number, // A total number of posted answers to the question
+   *   QuestionResult: Object // All unique answers to the question and their number
+   * }
+   * ```
    */
   data: any;
   /**
-   * it is `true` if the results were got from the service successfully
+   * An array of objects with the following structure:
+   *
+   * ```js
+   * {
+   *   name: String, // A unique answer to the question
+   *   value: Number // The number of user responses with this answer
+   * }
+   * ```
    */
-  success: boolean;
+  dataList: Array<any>;
 }
 
 export interface LoadFilesEvent extends FileQuestionEventMixin {
diff --git a/src/survey.ts b/src/survey.ts
index a752795c8b..ca570d1131 100644
--- a/src/survey.ts
+++ b/src/survey.ts
@@ -121,11 +121,11 @@ export class SurveyModel extends SurveyElementCore
 
   //#region Event declarations
   /**
-   * An event that is raised after a trigger is executed.
+   * An event that is raised after a [trigger](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#triggers) is executed.
    *
    * For information on event handler parameters, refer to descriptions within the interface.
    *
-   * For more information about triggers, refer to the following help topic: [Conditional Survey Logic (Triggers)](https://surveyjs.io/form-library/documentation/design-survey/conditional-logic#conditional-survey-logic-triggers).
+   * [Conditional Survey Logic (Triggers)](https://surveyjs.io/form-library/documentation/design-survey/conditional-logic#conditional-survey-logic-triggers (linkStyle)).
    * @see triggers
    * @see runTriggers
    */
@@ -170,11 +170,11 @@ export class SurveyModel extends SurveyElementCore
    */
   public onStarted: EventBase<SurveyModel, {}> = this.addEvent<SurveyModel, {}>();
   /**
-   * Use this event to save incomplete survey results. Enable the [`sendResultOnPageNext`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#sendResultOnPageNext) property for this event to occur.
+   * An event that is raised to save incomplete survey results. Enable the [`sendResultOnPageNext`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#sendResultOnPageNext) property for this event to occur.
    *
    * For information on event handler parameters, refer to descriptions within the interface.
    *
-   * Refer to the following help topic for more information on the use case: [Continue an Incomplete Survey](https://surveyjs.io/form-library/documentation/handle-survey-results-continue-incomplete).
+   * [Continue an Incomplete Survey](https://surveyjs.io/form-library/documentation/handle-survey-results-continue-incomplete (linkStyle)).
    */
   public onPartialSend: EventBase<SurveyModel, {}> = this.addEvent<SurveyModel, {}>();
   /**
@@ -400,11 +400,11 @@ export class SurveyModel extends SurveyElementCore
    */
   public onTextRenderAs: EventBase<SurveyModel, TextRenderAsEvent> = this.addEvent<SurveyModel, TextRenderAsEvent>();
   /**
-   * The event fires when it gets response from the [api.surveyjs.io](https://api.surveyjs.io) service on saving survey results. Use it to find out if the results have been saved successfully.
+   * An event that is raised after a request to save survey results on [SurveyJS Service](https://api.surveyjs.io/) has been completed. Use this event to find out if the results have been saved successfully.
    */
   public onSendResult: EventBase<SurveyModel, SendResultEvent> = this.addEvent<SurveyModel, SendResultEvent>();
   /**
-   * Use it to get results after calling the `getResult` method. It returns a simple analytics from [api.surveyjs.io](https://api.surveyjs.io) service.
+   * An event that is raised when the [`getResult(resultId, questionName)`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#getResult) method is called. Use this event to obtain answers to an individual question from [SurveyJS Service](https://api.surveyjs.io/).
    * @see getResult
    */
   public onGetResult: EventBase<SurveyModel, GetResultEvent> = this.addEvent<SurveyModel, GetResultEvent>();
@@ -728,27 +728,25 @@ export class SurveyModel extends SurveyElementCore
   public onLocaleChangedEvent: EventBase<SurveyModel, {}> = this.addEvent<SurveyModel, {}>();
 
   /**
-   * Use this event to create/customize actions to be displayed in a question's title.
+   * An event that allows you to add, delete, or modify actions in a question title.
    *
    * For information on event handler parameters, refer to descriptions within the interface.
    *
    * [View Demo](https://surveyjs.io/form-library/examples/survey-titleactions/ (linkStyle))
-   * @see IAction
-   * @see Question
   */
   public onGetQuestionTitleActions: EventBase<SurveyModel, GetQuestionTitleActionsEvent> = this.addEvent<SurveyModel, GetQuestionTitleActionsEvent>();
 
   /**
-   * Use this event to create/customize actions to be displayed in a panel's title.
-   * @see IAction
-   * @see PanelModel
+   * An event that allows you to add, delete, or modify actions in a panel title.
    */
   public onGetPanelTitleActions: EventBase<SurveyModel, GetPanelTitleActionsEvent> = this.addEvent<SurveyModel, GetPanelTitleActionsEvent>();
 
   /**
-   * Use this event to create/customize actions to be displayed in a page's title.
-   * @see IAction
-   * @see PageModel
+   * An event that allows you to add, delete, or modify actions in a page title.
+   *
+   * For information on event handler parameters, refer to descriptions within the interface.
+   *
+   * [View Demo](https://surveyjs.io/form-library/examples/modify-titles-of-survey-elements/ (linkStyle))
    */
   public onGetPageTitleActions: EventBase<SurveyModel, GetPageTitleActionsEvent> = this.addEvent<SurveyModel, GetPageTitleActionsEvent>();
 
@@ -1147,8 +1145,11 @@ export class SurveyModel extends SurveyElementCore
     }
   }
   /**
-   * Gets or sets a list of triggers in the survey.
-   * @see SurveyTrigger
+   * A list of triggers in the survey.
+   *
+   * [Conditional Survey Logic (Triggers)](https://surveyjs.io/form-library/documentation/design-survey/conditional-logic#conditional-survey-logic-triggers (linkStyle))
+   * @see runTriggers
+   * @see onTriggerExecuted
    */
   public get triggers(): Array<SurveyTrigger> {
     return this.getPropertyValue("triggers");
@@ -1166,7 +1167,7 @@ export class SurveyModel extends SurveyElementCore
     this.setPropertyValue("calculatedValues", val);
   }
   /**
-   * The identifier of a survey JSON schema to load from the [SurveyJS Service](https://api.surveyjs.io).
+   * The identifier of a survey JSON schema to load from [SurveyJS Service](https://api.surveyjs.io).
    *
    * Refer to the following help topic for more information: [Store Survey Results in the SurveyJS Service](https://surveyjs.io/form-library/documentation/handle-survey-results-store#store-survey-results-in-the-surveyjs-service).
    * @see loadSurveyFromService
@@ -1179,7 +1180,7 @@ export class SurveyModel extends SurveyElementCore
     this.setPropertyValue("surveyId", val);
   }
   /**
-   * An identifier used to save survey results to the [SurveyJS Service](https://api.surveyjs.io).
+   * An identifier used to save survey results to [SurveyJS Service](https://api.surveyjs.io).
    *
    * Refer to the following help topic for more information: [Store Survey Results in the SurveyJS Service](https://surveyjs.io/form-library/documentation/handle-survey-results-store#store-survey-results-in-the-surveyjs-service).
    * @see onComplete
@@ -1194,7 +1195,7 @@ export class SurveyModel extends SurveyElementCore
   /**
    * A user identifier (e-mail or other unique ID).
    *
-   * If your application works with the [SurveyJS Service](https://api.surveyjs.io), the ID ensures that users do not pass the same survey twice. On the second run, they will see the [Completed Before page](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#completedBeforeHtml).
+   * If your application works with [SurveyJS Service](https://api.surveyjs.io), the ID ensures that users do not pass the same survey twice. On the second run, they will see the [Completed Before page](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#completedBeforeHtml).
    * @see cookieName
    */
   public get clientId(): string {
@@ -1216,9 +1217,9 @@ export class SurveyModel extends SurveyElementCore
     this.setPropertyValue("cookieName", val);
   }
   /**
-   * Specifies whether to save survey results when respondents swtich between pages. Handle the [`onPartialSend`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onPartialSend) event to implement the save operation.
+   * Specifies whether to save survey results when respondents switch between pages. Handle the [`onPartialSend`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onPartialSend) event to implement the save operation.
    *
-   * Refer to the following help topic for more information on the use case: [Continue an Incomplete Survey](https://surveyjs.io/form-library/documentation/handle-survey-results-continue-incomplete).
+   * [Continue an Incomplete Survey](https://surveyjs.io/form-library/documentation/handle-survey-results-continue-incomplete (linkStyle)).
    */
   public get sendResultOnPageNext(): boolean {
     return this.getPropertyValue("sendResultOnPageNext");
@@ -1660,8 +1661,13 @@ export class SurveyModel extends SurveyElementCore
     this.setPropertyValue("keepIncorrectValues", val);
   }
   /**
-   * Gets or sets the survey locale. The default value it is empty, this means the 'en' locale is used.
-   * You can set it to 'de' - German, 'fr' - French and so on. The library has built-in localization for several languages. The library has a multi-language support as well.
+   * Specifies the survey's locale.
+   *
+   * Default value: `""` (a default locale is used)
+   *
+   * [Localization & Globalization help topic](https://surveyjs.io/form-library/documentation/survey-localization (linkStyle))
+   *
+   * [Survey Localization demo](https://surveyjs.io/form-library/examples/survey-localization/ (linkStyle))
    */
   public get locale(): string {
     return this.getPropertyValue("locale", surveyLocalization.currentLocale);
@@ -1678,7 +1684,11 @@ export class SurveyModel extends SurveyElementCore
     this.onLocaleChangedEvent.fire(this, this.locale);
   }
   /**
-   * Returns an array of locales that are used in the survey's translation.
+   * Returns an array of locales whose translations are used in the survey.
+   *
+   * [Localization & Globalization help topic](https://surveyjs.io/form-library/documentation/survey-localization (linkStyle))
+   *
+   * [Survey Localization demo](https://surveyjs.io/form-library/examples/survey-localization/ (linkStyle))
    */
   public getUsedLocales(): Array<string> {
     var locs = new Array<string>();
@@ -2067,7 +2077,10 @@ export class SurveyModel extends SurveyElementCore
     return new ConditionRunner(expression).run(values, properties);
   }
   /**
-   * Run all triggers that performs on value changed and not on moving to the next page.
+   * Executes [all triggers](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#triggers), except ["complete"](https://surveyjs.io/form-library/documentation/design-survey/conditional-logic#complete).
+   *
+   * [Conditional Survey Logic (Triggers)](https://surveyjs.io/form-library/documentation/design-survey/conditional-logic#conditional-survey-logic-triggers (linkStyle))
+   * @see onTriggerExecuted
    */
   public runTriggers(): void {
     this.checkTriggers(this.getFilteredValues(), false);
@@ -2108,7 +2121,7 @@ export class SurveyModel extends SurveyElementCore
     return this.getLocalizableString("completedBeforeHtml");
   }
   /**
-   * HTML content displayed while a survey JSON schema is being loaded from the [SurveyJS Service](https://api.surveyjs.io).
+   * HTML content displayed while a survey JSON schema is being loaded from [SurveyJS Service](https://api.surveyjs.io).
    * @see surveyId
    * @see processedLoadingHtml
    */
@@ -4094,7 +4107,7 @@ export class SurveyModel extends SurveyElementCore
    * 1. Switches the survey [`state`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#state) to `"completed"`.
    * 1. Raises the [`onComplete`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onComplete) event.
    * 1. Navigates the user to a URL specified by the [`navigateToUrl`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#navigateToUrl) or [`navigateToUrlOnCondition`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#navigateToUrlOnCondition) property.
-   * 1. Calls the [`sendResult()`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#sendResult) method if Form Library works with the [SurveyJS Service](https://api.surveyjs.io/).
+   * 1. Calls the [`sendResult()`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#sendResult) method if Form Library works with [SurveyJS Service](https://api.surveyjs.io/).
    *
    * The `doComplete()` method completes the survey regardless of validation errors and the current page. If you need to ensure that survey results are valid and full, call the [`completeLastPage()`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#completeLastPage) method instead.
    *
@@ -5437,20 +5450,18 @@ export class SurveyModel extends SurveyElementCore
     }
   }
   /**
-   * Sends a survey result to the [api.surveyjs.io](https://api.surveyjs.io) service.
-   * @param postId [api.surveyjs.io](https://api.surveyjs.io) service postId
-   * @param clientId Typically a customer e-mail or an identifier
-   * @param isPartialCompleted Set it to `true` if the survey is not completed yet and the results are intermediate
-   * @see surveyPostId
-   * @see clientId
+   * Posts a survey result to [SurveyJS Service](https://api.surveyjs.io/).
+   * @param postId An identifier used to save survey results. You can find it on the [My Surveys](https://surveyjs.io/service/mysurveys) page. If you do not specify this parameter, the survey uses the [`surveyPostId`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#surveyPostId) property value.
+   * @param clientId A respondent identifier (e-mail or other unique ID). This ID ensures that the respondent does not pass the same survey twice.
+   * @param isPartial Pass `true` to save partial survey results (see [Continue an Incomplete Survey](https://surveyjs.io/form-library/documentation/handle-survey-results-continue-incomplete)).
    */
   public sendResult(
     postId: string = null,
     clientId: string = null,
-    isPartialCompleted: boolean = false
+    isPartial: boolean = false
   ) {
     if (!this.isEditMode) return;
-    if (isPartialCompleted && this.onPartialSend) {
+    if (isPartial && this.onPartialSend) {
       this.onPartialSend.fire(this, null);
     }
 
@@ -5461,7 +5472,7 @@ export class SurveyModel extends SurveyElementCore
     if (clientId) {
       this.clientId = clientId;
     }
-    if (isPartialCompleted && !this.clientId) return;
+    if (isPartial && !this.clientId) return;
     var self = this;
     if (this.surveyShowDataSaving) {
       this.setCompletedState("saving", "");
@@ -5484,18 +5495,17 @@ export class SurveyModel extends SurveyElementCore
         });
       },
       this.clientId,
-      isPartialCompleted
+      isPartial
     );
   }
   /**
-   * Calls the [api.surveyjs.io](https://api.surveyjs.io) service and, on callback, fires the `onGetResult` event with all answers that your users made for a question.
-   * @param resultId [api.surveyjs.io](https://api.surveyjs.io) service resultId
-   * @param name The question name
-   * @see onGetResult
+   * Requests [SurveyJS Service](https://api.surveyjs.io/) to retrieve all answers to a specified question. Handle the [`onGetResult`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onGetResult) event to access the answers.
+   * @param resultId A result ID that identifies the required survey. You can find it on the [My Surveys](https://surveyjs.io/service/mysurveys) page.
+   * @param questionName A question name.
    */
-  public getResult(resultId: string, name: string) {
+  public getResult(resultId: string, questionName: string) {
     var self = this;
-    this.createSurveyService().getResult(resultId, name, function (
+    this.createSurveyService().getResult(resultId, questionName, function (
       success: boolean,
       data: any,
       dataList: any[],