Update SurveyModel doccomments (#6708)

src/settings.ts

@@ -446,12 +446,6 @@ export var settings = {
    *
    * - `caseSensitive`: `Boolean`\
    * Specifies whether to differentiate between capital and lower-case letters. Default value: `false`.
-   *
-   * - `normalizedTextCallback`: `(str: string, reason: string) => string`
-   * Use the following function { str.normalize("NFD").replace(/[\u0300-\u036f]/g, ""); }
-   * If you want to 'Brouillé' to be equal to 'Brouille'.
-   * Use the following function { return reason === "filter" ? str.normalize("NFD").replace(/[\u0300-\u036f]/g, ""): ""; }
-   * If you want to use this functionality during filtering only, for example in list.
    */
   comparator: {
     trimStrings: true,
@@ -596,13 +590,24 @@ export var settings = {
    */
   rankingDragHandleArea: "entireItem",
 
-  /**
-   * Specifies environment in which SurveyJS will exist
-   */
   environment: defaultEnvironment,
 
+  /**
+   * Allows you to hide the maximum length indicator in text input questions.
+   *
+   * If you specify a question's [`maxLength`](https://surveyjs.io/form-library/documentation/api-reference/text-entry-question-model#maxLength) property or a survey's [`maxTextLength`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#maxTextLength) property, text input questions indicate the number of entered characters and the character limit. Assign `false` to the `settings.showMaxLengthIndicator` property if you want to hide this indicator.
+   *
+   * Default value: `true`
+   */
   showMaxLengthIndicator: true,
 
+  /**
+   * An object that specifies heading levels (`<h1>`, `<h2>`, etc.) to use when rendering survey, page, panel, and question titles.
+   *
+   * Default value: `{ survey: "h3", page: "h4", panel: "h4", question: "h5" }`
+   *
+   * If you want to modify heading levels for individual titles, handle `SurveyModel`'s [`onGetTitleTagName`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onGetTitleTagName) event.
+   */
   titleTags: {
     survey: "h3",
     page: "h4",

src/survey-events-api.ts

@@ -372,23 +372,23 @@ export interface ProcessHtmlEvent {
 }
 export interface GetQuestionTitleEvent extends QuestionEventMixin {
   /**
-   * a calculated question title, based on question `title`, `name`
+   * A question title taken from the question's `title` or `name` property. You can change this parameter's value.
    */
   title: string;
 }
 export interface GetTitleTagNameEvent {
   /**
-   * an element title tagName that are used to render a title. You can change it from the default value
+   * A survey element (question, panel, page, or the survey itself) for which the event is raised.
    */
-  tagName: string;
+  element: Base;
   /**
-   * an element (question, panel, page and survey) that SurveyJS is going to render
+   * A heading used to render the title (`"h1"`-`"h6"`). You can change this parameter's value.
    */
-  element: Base;
+  tagName: string;
 }
 export interface GetQuestionNoEvent extends QuestionEventMixin {
   /**
-   * a calculated question no, based on question `visibleIndex`, survey `.questionStartIndex` properties. You can change it
+   * A question number that is calculated based upon the question's [`visibleIndex`](https://surveyjs.io/form-library/documentation/api-reference/question#visibleIndex) and survey's [`questionStartIndex`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#questionStartIndex) properties. You can change this parameter's value.
    */
   no: string;
 }

src/survey.ts

@@ -178,7 +178,7 @@ export class SurveyModel extends SurveyElementCore
    *
    * For information on event handler parameters, refer to descriptions within the interface.
    *
-   * [Continue an Incomplete Survey](https://surveyjs.io/form-library/documentation/handle-survey-results-continue-incomplete (linkStyle)).
+   * [Continue an Incomplete Survey](https://surveyjs.io/form-library/documentation/handle-survey-results-continue-incomplete (linkStyle))
    */
   public onPartialSend: EventBase<SurveyModel, {}> = this.addEvent<SurveyModel, {}>();
   /**
@@ -369,26 +369,37 @@ export class SurveyModel extends SurveyElementCore
    */
   public onGetQuestionDisplayValue: EventBase<SurveyModel, GetQuestionDisplayValueEvent> = this.addEvent<SurveyModel, GetQuestionDisplayValueEvent>();
   /**
-   * Use this event to change the question title in code. If you want to remove question numbering then set showQuestionNumbers to "off".
-   * @see showQuestionNumbers
+   * An event that is raised before the survey displays a question title. Handle this event to modify question titles.
+   *
+   * For information on event handler parameters, refer to descriptions within the interface.
+   *
+   * If you want to modify question numbers, handle the [`onGetQuestionNo`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onGetQuestionNo) event.
    * @see requiredText
    */
   public onGetQuestionTitle: EventBase<SurveyModel, GetQuestionTitleEvent> = this.addEvent<SurveyModel, GetQuestionTitleEvent>();
   /**
-   * Use this event to change the element title tag name that renders by default.
-   * @see showQuestionNumbers
-   * @see requiredText
+   * An event that is raised when the survey calculates heading levels (`<h1>`, `<h2>`, etc.) for a survey, page, panel, and question title. Handle this event to change the heading level of individual titles.
+   *
+   * For information on event handler parameters, refer to descriptions within the interface.
+   *
+   * If you want to specify heading levels for all titles, use the [`titleTags`](https://surveyjs.io/form-library/documentation/api-reference/settings#titleTags) object in [global settings](https://surveyjs.io/form-library/documentation/api-reference/settings).
+   * @see onGetQuestionTitle
+   * @see onGetQuestionNo
    */
   public onGetTitleTagName: EventBase<SurveyModel, GetTitleTagNameEvent> = this.addEvent<SurveyModel, GetTitleTagNameEvent>();
   /**
-   * Use this event to change the question no in code. If you want to remove question numbering then set showQuestionNumbers to "off".
-   * @see showQuestionNumbers
+   * An event that is raised before the survey calculates a question number. Handle this event to modify question numbers.
+   *
+   * For information on event handler parameters, refer to descriptions within the interface.
+   *
+   * If you want to hide question numbers, disable the [`showQuestionNumbers`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#showQuestionNumbers) property.
+   * @see onGetQuestionTitle
    * @see questionStartIndex
    */
   public onGetQuestionNo: EventBase<SurveyModel, GetQuestionNoEvent> = this.addEvent<SurveyModel, GetQuestionNoEvent>();
   /**
    * Use this event to change the progress text in code.
-   *  @see progressBarType
+   * @see progressBarType
    */
   public onProgressText: EventBase<SurveyModel, ProgressTextEvent> = this.addEvent<SurveyModel, ProgressTextEvent>();
   /**
@@ -2409,15 +2420,17 @@ export class SurveyModel extends SurveyElementCore
     this.updateVisibleIndexes();
   }
   /**
-   * Gets or sets a value that specifies how the question numbers are displayed.
+   * Specifies whether to display question numbers and how to calculate them.
    *
-   * The following options are available:
+   * Possible values:
    *
-   * - `on` - display question numbers
-   * - `onpage` - display question numbers, start numbering on every page
-   * - `off` - turn off the numbering for questions titles
+   * - `true` or `"on"` - Displays question numbers.
+   * - `"onpage"` - Displays question numbers and starts numbering on each page from scratch.
+   * - `false` or `"off"` - Hides question numbers.
    *
-   * [View Demo](https://surveyjs.io/form-library/examples/survey-options/ (linkStyle))
+   * [View Demo](https://surveyjs.io/form-library/examples/how-to-number-pages-and-questions/ (linkStyle))
+   *
+   * If you want to hide the number of an individual question, enable its [`hideNumber`](https://surveyjs.io/form-library/documentation/api-reference/question#hideNumber) property.
    */
   public get showQuestionNumbers(): string | boolean {
     return this.getPropertyValue("showQuestionNumbers");