@univerjs/sheets-data-validation 0.6.1 → 0.6.2-nightly.202503031606

package/lib/types/facade/f-data-validation-builder.d.ts

@@ -37,6 +37,8 @@ export declare class FDataValidationBuilder {
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a new data validation rule that requires a number between 1 and 10 for the range A1:B10
      * const fRange = fWorksheet.getRange('A1:B10');
      * const rule = univerAPI.newDataValidation()
      *   .requireNumberBetween(1, 10)
@@ -55,9 +57,24 @@ export declare class FDataValidationBuilder {
      * @returns {FDataValidationBuilder} A new instance of the DataValidationBuilder class
      * @example
      * ```typescript
-     * const builder = univerAPI.newDataValidation().requireNumberBetween(1, 10);
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a new data validation rule that requires a number between 1 and 10 for the range A1:B10
+     * const fRange = fWorksheet.getRange('A1:B10');
+     * const builder = univerAPI.newDataValidation()
+     *   .requireNumberBetween(1, 10)
+     *   .setOptions({
+     *     allowBlank: true,
+     *     showErrorMessage: true,
+     *     error: 'Please enter a number between 1 and 10'
+     *   });
+     * fRange.setDataValidation(builder.build());
+     *
+     * // Copy the builder applied to the new range F1:G10
+     * const newRange = fWorksheet.getRange('F1:G10');
      * const copyBuilder = builder.copy();
-     * console.log(copyBuilder);
+     * newRange.setDataValidation(copyBuilder.build());
      * ```
      */
     copy(): FDataValidationBuilder;
@@ -77,13 +94,13 @@ export declare class FDataValidationBuilder {
      * @example
      * ```typescript
      * const builder = univerAPI.newDataValidation();
-     * console.log(builder.getCriteriaType());
+     * console.log(builder.getCriteriaType()); // custom
      *
      * builder.requireNumberBetween(1, 10);
-     * console.log(builder.getCriteriaType());
+     * console.log(builder.getCriteriaType()); // decimal
      *
      * builder.requireValueInList(['Yes', 'No']);
-     * console.log(builder.getCriteriaType());
+     * console.log(builder.getCriteriaType()); // list
      * ```
      */
     getCriteriaType(): DataValidationType | string;
@@ -94,10 +111,10 @@ export declare class FDataValidationBuilder {
      * ```typescript
      * const builder = univerAPI.newDataValidation().requireNumberBetween(1, 10);
      * const [operator, formula1, formula2] = builder.getCriteriaValues();
-     * console.log(operator, formula1, formula2);
+     * console.log(operator, formula1, formula2); // between 1 10
      *
      * builder.requireValueInList(['Yes', 'No']);
-     * console.log(builder.getCriteriaValues());
+     * console.log(builder.getCriteriaValues()); // undefined Yes,No undefined
      * ```
      */
     getCriteriaValues(): [string | undefined, string | undefined, string | undefined];
@@ -115,10 +132,10 @@ export declare class FDataValidationBuilder {
      */
     getHelpText(): string | undefined;
     /**
-     * Sets the data validation type to CHECKBOX and sets the checked and unchecked values
-     * @param {string} [checkedValue] - The value when the checkbox is checked
-     * @param {string} [uncheckedValue] - The value when the checkbox is unchecked
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Sets the data validation rule to require that the input is a boolean value; this value is rendered as a checkbox.
+     * @param {string} [checkedValue] - The value assigned to a checked box.
+     * @param {string} [uncheckedValue] - The value assigned to an unchecked box.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -141,179 +158,217 @@ export declare class FDataValidationBuilder {
      */
     requireCheckbox(checkedValue?: string, uncheckedValue?: string): FDataValidationBuilder;
     /**
-     * Set the data validation type to DATE and configure the validation rules to be after a specific date
-     * @param {Date} date - The date to compare against
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Set the data validation type to DATE and configure the validation rules to be after a specific date.
+     * @param {Date} date - The latest unacceptable date.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Set some date values in the range A1:B2
      * const fRange = fWorksheet.getRange('A1:B2');
      * fRange.setValues([
      *   ['2024-01-01', '2024-12-31'],
      *   ['2025-01-01', '2025-12-31']
      * ]);
+     *
+     * // Create a data validation rule that requires a date after 2025-01-01
      * const rule = univerAPI.newDataValidation()
      *   .requireDateAfter(new Date('2025-01-01'))
      *   .build();
      * fRange.setDataValidation(rule);
      *
+     * // Get the validation status of the range
      * const status = await fRange.getValidatorStatus();
      * console.log(status); // [['invalid', 'invalid', 'invalid', 'valid']]
      * ```
      */
     requireDateAfter(date: Date): FDataValidationBuilder;
     /**
-     * Set the data validation type to DATE and configure the validation rules to be before a specific date
-     * @param {Date} date - The date to compare against
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Set the data validation type to DATE and configure the validation rules to be before a specific date.
+     * @param {Date} date - The earliest unacceptable date.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Set some date values in the range A1:B2
      * const fRange = fWorksheet.getRange('A1:B2');
      * fRange.setValues([
      *   ['2024-01-01', '2024-12-31'],
      *   ['2025-01-01', '2025-12-31']
      * ]);
+     *
+     * // Create a data validation rule that requires a date before 2025-01-01
      * const rule = univerAPI.newDataValidation()
      *   .requireDateBefore(new Date('2025-01-01'))
      *   .build();
      * fRange.setDataValidation(rule);
      *
+     * // Get the validation status of the range
      * const status = await fRange.getValidatorStatus();
      * console.log(status); // [['valid', 'valid', 'invalid', 'invalid']]
      * ```
      */
     requireDateBefore(date: Date): FDataValidationBuilder;
     /**
-     * Set the data validation type to DATE and configure the validation rules to be within a specific date range
-     * @param {Date} start - The starting date of the range
-     * @param {Date} end - The ending date of the range
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Set the data validation type to DATE and configure the validation rules to be within a specific date range.
+     * @param {Date} start - The earliest acceptable date.
+     * @param {Date} end - The latest acceptable date.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Set some date values in the range A1:B2
      * const fRange = fWorksheet.getRange('A1:B2');
      * fRange.setValues([
      *   ['2024-01-01', '2024-12-31'],
      *   ['2025-01-01', '2025-12-31']
      * ]);
+     *
+     * // Create a data validation rule that requires a date between 2024-06-01 and 2025-06-01
      * const rule = univerAPI.newDataValidation()
      *   .requireDateBetween(new Date('2024-06-01'), new Date('2025-06-01'))
      *   .build();
      * fRange.setDataValidation(rule);
      *
+     * // Get the validation status of the range
      * const status = await fRange.getValidatorStatus();
      * console.log(status); // [['invalid', 'valid', 'valid', 'invalid']]
      * ```
      */
     requireDateBetween(start: Date, end: Date): FDataValidationBuilder;
     /**
-     * Set the data validation type to DATE and configure the validation rules to be equal to a specific date
-     * @param {Date} date - The date to compare against
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Set the data validation type to DATE and configure the validation rules to be equal to a specific date.
+     * @param {Date} date - The sole acceptable date.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Set some date values in the range A1:B2
      * const fRange = fWorksheet.getRange('A1:B2');
      * fRange.setValues([
      *   ['2024-01-01', '2024-12-31'],
      *   ['2025-01-01', '2025-12-31']
      * ]);
+     *
+     * // Create a data validation rule that requires a date equal to 2025-01-01
      * const rule = univerAPI.newDataValidation()
      *   .requireDateEqualTo(new Date('2025-01-01'))
      *   .build();
      * fRange.setDataValidation(rule);
      *
+     * // Get the validation status of the cell A2
      * const status = await fWorksheet.getRange('A2').getValidatorStatus();
      * console.log(status?.[0]?.[0]); // 'valid'
      *
+     * // Get the validation status of the cell B2
      * const status2 = await fWorksheet.getRange('B2').getValidatorStatus();
      * console.log(status2?.[0]?.[0]); // 'invalid'
      * ```
      */
     requireDateEqualTo(date: Date): FDataValidationBuilder;
     /**
-     * Set the data validation type to DATE and configure the validation rules to be not within a specific date range
-     * @param {Date} start - The starting date of the date range
-     * @param {Date} end - The ending date of the date range
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Set the data validation type to DATE and configure the validation rules to be not within a specific date range.
+     * @param {Date} start - The earliest unacceptable date.
+     * @param {Date} end - The latest unacceptable date.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Set some date values in the range A1:B2
      * const fRange = fWorksheet.getRange('A1:B2');
      * fRange.setValues([
      *   ['2024-01-01', '2024-12-31'],
      *   ['2025-01-01', '2025-12-31']
      * ]);
+     *
+     * // Create a data validation rule that requires a date not between 2024-06-01 and 2025-06-01
      * const rule = univerAPI.newDataValidation()
      *   .requireDateNotBetween(new Date('2024-06-01'), new Date('2025-06-01'))
      *   .build();
      * fRange.setDataValidation(rule);
      *
+     * // Get the validation status of the range
      * const status = await fRange.getValidatorStatus();
      * console.log(status); // [['valid', 'invalid', 'invalid', 'valid']]
      * ```
      */
     requireDateNotBetween(start: Date, end: Date): FDataValidationBuilder;
     /**
-     * Set the data validation type to DATE and configure the validation rules to be on or after a specific date
-     * @param {Date} date - The date to compare against
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Set the data validation type to DATE and configure the validation rules to be on or after a specific date.
+     * @param {Date} date - The earliest acceptable date.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Set some date values in the range A1:B2
      * const fRange = fWorksheet.getRange('A1:B2');
      * fRange.setValues([
      *   ['2024-01-01', '2024-12-31'],
      *   ['2025-01-01', '2025-12-31']
      * ]);
+     *
+     * // Create a data validation rule that requires a date on or after 2025-01-01
      * const rule = univerAPI.newDataValidation()
      *   .requireDateOnOrAfter(new Date('2025-01-01'))
      *   .build();
      * fRange.setDataValidation(rule);
      *
+     * // Get the validation status of the range
      * const status = await fRange.getValidatorStatus();
      * console.log(status); // [['invalid', 'invalid', 'valid', 'valid']]
      * ```
      */
     requireDateOnOrAfter(date: Date): FDataValidationBuilder;
     /**
-     * Set the data validation type to DATE and configure the validation rules to be on or before a specific date
-     * @param {Date} date - The date to compare against
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Set the data validation type to DATE and configure the validation rules to be on or before a specific date.
+     * @param {Date} date - The latest acceptable date.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Set some date values in the range A1:B2
      * const fRange = fWorksheet.getRange('A1:B2');
      * fRange.setValues([
      *   ['2024-01-01', '2024-12-31'],
      *   ['2025-01-01', '2025-12-31']
      * ]);
+     *
+     * // Create a data validation rule that requires a date on or before 2025-01-01
      * const rule = univerAPI.newDataValidation()
      *   .requireDateOnOrBefore(new Date('2025-01-01'))
      *   .build();
      * fRange.setDataValidation(rule);
      *
+     * // Get the validation status of the range
      * const status = await fRange.getValidatorStatus();
      * console.log(status); // [['valid', 'valid', 'valid', 'invalid']]
      * ```
      */
     requireDateOnOrBefore(date: Date): FDataValidationBuilder;
     /**
-     * Requires that a custom formula be satisfied
-     * @param {string} formula - The formula string that needs to be satisfied, formula result should be TRUE or FALSE, and references range will relative offset
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Sets the data validation rule to require that the given formula evaluates to `true`.
+     * @param {string} formula - The formula string that needs to be satisfied, formula result should be TRUE or FALSE, and references range will relative offset.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Set some values in the range A1:B2 and C1:D2
      * const cell = fWorksheet.getRange('A1:B2');
      * cell.setValues([
      *   [4, 3],
@@ -324,6 +379,8 @@ export declare class FDataValidationBuilder {
      *   [1, 2],
      *   [3, 4]
      * ]);
+     *
+     * // Create a data validation rule that requires the formula '=A1>2' to be satisfied
      * const rule = univerAPI.newDataValidation()
      *   .requireFormulaSatisfied('=A1>2')
      *   .setOptions({
@@ -333,21 +390,24 @@ export declare class FDataValidationBuilder {
      *   .build();
      * fRange.setDataValidation(rule);
      *
+     * // Get the validation status of the range
      * const status = await fRange.getValidatorStatus();
      * console.log(status); // [['valid', 'valid', 'invalid', 'invalid']]
      * ```
      */
     requireFormulaSatisfied(formula: string): FDataValidationBuilder;
     /**
-     * Requires the user to enter a number within a specific range, which can be integer or decimal
-     * @param {number} start - The starting value of the number range
-     * @param {number} end - The ending value of the number range
-     * @param {boolean} [isInteger] - Indicates whether the required number is an integer
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Sets the data validation rule to require a number that falls between, or is either of, two specified numbers.
+     * @param {number} start - The lowest acceptable value.
+     * @param {number} end - The highest acceptable value.
+     * @param {boolean} [isInteger] - Indicates whether the required number is an integer.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a new data validation rule that requires a number between 1 and 10 for the range A1:B10
      * const fRange = fWorksheet.getRange('A1:B10');
      * const rule = univerAPI.newDataValidation()
      *   .requireNumberBetween(1, 10)
@@ -362,14 +422,16 @@ export declare class FDataValidationBuilder {
      */
     requireNumberBetween(start: number, end: number, isInteger?: boolean): FDataValidationBuilder;
     /**
-     * Requires the user to enter a number that is equal to a specific value, which can be an integer or a decimal
-     * @param {number} num - The number to which the entered number should be equal
-     * @param {boolean} [isInteger] - Indicates whether the required number is an integer
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Sets the data validation rule to require a number equal to the given value.
+     * @param {number} num - The sole acceptable value.
+     * @param {boolean} [isInteger] - Indicates whether the required number is an integer.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a new data validation rule that requires a number equal to 10 for the range A1:B10
      * const fRange = fWorksheet.getRange('A1:B10');
      * const rule = univerAPI.newDataValidation()
      *   .requireNumberEqualTo(10)
@@ -384,14 +446,16 @@ export declare class FDataValidationBuilder {
      */
     requireNumberEqualTo(num: number, isInteger?: boolean): FDataValidationBuilder;
     /**
-     * Requires the user to enter a number that is greater than a specific value, which can be an integer or a decimal
-     * @param {number} num - The number to which the entered number should be greater
-     * @param {boolean} [isInteger] - Indicates whether the required number is an integer
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Sets the data validation rule to require a number greater than the given value.
+     * @param {number} num - The highest unacceptable value.
+     * @param {boolean} [isInteger] - Indicates whether the required number is an integer.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a new data validation rule that requires a number greater than 10 for the range A1:B10
      * const fRange = fWorksheet.getRange('A1:B10');
      * const rule = univerAPI.newDataValidation()
      *   .requireNumberGreaterThan(10)
@@ -406,14 +470,16 @@ export declare class FDataValidationBuilder {
      */
     requireNumberGreaterThan(num: number, isInteger?: boolean): FDataValidationBuilder;
     /**
-     * Requires the user to enter a number that is greater than or equal to a specific value, which can be an integer or a decimal
-     * @param {number} num - The number to which the entered number should be greater than or equal
-     * @param {boolean} [isInteger] - Indicates whether the required number is an integer
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Sets the data validation rule to require a number greater than or equal to the given value.
+     * @param {number} num - The lowest acceptable value.
+     * @param {boolean} [isInteger] - Indicates whether the required number is an integer.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a new data validation rule that requires a number greater than 10 or equal to 10 for the range A1:B10
      * const fRange = fWorksheet.getRange('A1:B10');
      * const rule = univerAPI.newDataValidation()
      *   .requireNumberGreaterThanOrEqualTo(10)
@@ -428,14 +494,16 @@ export declare class FDataValidationBuilder {
      */
     requireNumberGreaterThanOrEqualTo(num: number, isInteger?: boolean): FDataValidationBuilder;
     /**
-     * Requires the user to enter a number that is less than a specific value, which can be an integer or a decimal
-     * @param {number} num - The number to which the entered number should be less
-     * @param {boolean} [isInteger] - Indicates whether the required number is an integer
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Sets the data validation rule to require a number less than the given value.
+     * @param {number} num - The lowest unacceptable value.
+     * @param {boolean} [isInteger] - Indicates whether the required number is an integer.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a new data validation rule that requires a number less than 10 for the range A1:B10
      * const fRange = fWorksheet.getRange('A1:B10');
      * const rule = univerAPI.newDataValidation()
      *   .requireNumberLessThan(10)
@@ -450,15 +518,16 @@ export declare class FDataValidationBuilder {
      */
     requireNumberLessThan(num: number, isInteger?: boolean): FDataValidationBuilder;
     /**
-     * Sets the data validation rule to require a number less than or equal to a specified value
-     * The specified value can be an integer or a decimal
-     * @param {number} num - The number to which the entered number should be less than or equal
-     * @param {boolean} [isInteger] - Indicates whether the required number is an integer
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Sets the data validation rule to require a number less than or equal to the given value.
+     * @param {number} num - The highest acceptable value.
+     * @param {boolean} [isInteger] - Indicates whether the required number is an integer.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a new data validation rule that requires a number less than 10 or equal to 10 for the range A1:B10
      * const fRange = fWorksheet.getRange('A1:B10');
      * const rule = univerAPI.newDataValidation()
      *   .requireNumberLessThanOrEqualTo(10)
@@ -473,16 +542,17 @@ export declare class FDataValidationBuilder {
      */
     requireNumberLessThanOrEqualTo(num: number, isInteger?: boolean): FDataValidationBuilder;
     /**
-     * Sets a data validation rule that requires the user to enter a number outside a specified range
-     * The specified range includes all integers and decimals
-     * @param {number} start - The starting point of the specified range
-     * @param {number} end - The end point of the specified range
-     * @param {boolean} [isInteger] - Optional parameter, indicating whether the number to be verified is an integer
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Sets the data validation rule to require a number that does not fall between, and is neither of, two specified numbers.
+     * @param {number} start - The lowest unacceptable value.
+     * @param {number} end - The highest unacceptable value.
+     * @param {boolean} [isInteger] - Optional parameter, indicating whether the number to be verified is an integer.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a new data validation rule that requires a number not between 1 and 10 for the range A1:B10
      * const fRange = fWorksheet.getRange('A1:B10');
      * const rule = univerAPI.newDataValidation()
      *   .requireNumberNotBetween(1, 10)
@@ -497,15 +567,16 @@ export declare class FDataValidationBuilder {
      */
     requireNumberNotBetween(start: number, end: number, isInteger?: boolean): FDataValidationBuilder;
     /**
-     * Creates a data validation rule that requires the user to enter a number that is not equal to a specific value
-     * The specific value can be an integer or a decimal
-     * @param {number} num - The number to which the entered number should not be equal
-     * @param {boolean} [isInteger] - Indicates whether the required number is an integer
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Sets the data validation rule to require a number not equal to the given value.
+     * @param {number} num - The sole unacceptable value.
+     * @param {boolean} [isInteger] - Indicates whether the required number is an integer.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a new data validation rule that requires a number not equal to 10 for the range A1:B10
      * const fRange = fWorksheet.getRange('A1:B10');
      * const rule = univerAPI.newDataValidation()
      *   .requireNumberNotEqualTo(10)
@@ -520,16 +591,18 @@ export declare class FDataValidationBuilder {
      */
     requireNumberNotEqualTo(num: number, isInteger?: boolean): FDataValidationBuilder;
     /**
-     * Sets a data validation rule that requires the user to enter a value from a list of specific values
-     * The list can be displayed in a dropdown, and the user can choose multiple values according to the settings
-     * @param {string[]} values - An array containing the specific values that the user can enter
-     * @param {boolean} [multiple] - Optional parameter indicating whether the user can select multiple values
-     * @param {boolean} [showDropdown] - Optional parameter indicating whether to display the list in a dropdown
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Sets a data validation rule that requires the user to enter a value from a list of specific values.
+     * The list can be displayed in a dropdown, and the user can choose multiple values according to the settings.
+     * @param {string[]} values - An array of acceptable values.
+     * @param {boolean} [multiple] - Optional parameter indicating whether the user can select multiple values.
+     * @param {boolean} [showDropdown] - Optional parameter indicating whether to display the list in a dropdown.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a new data validation rule that requires the user to enter a value from the list ['Yes', 'No'] for the range A1:B10
      * const fRange = fWorksheet.getRange('A1:B10');
      * const rule = univerAPI.newDataValidation()
      *   .requireValueInList(['Yes', 'No'])
@@ -544,22 +617,25 @@ export declare class FDataValidationBuilder {
      */
     requireValueInList(values: string[], multiple?: boolean, showDropdown?: boolean): FDataValidationBuilder;
     /**
-     * Sets a data validation rule that requires the user to enter a value within a specific range
-     * The range is defined by an FRange object, which contains the unit ID, sheet name, and cell range
-     * @param {FRange} range - An FRange object representing the range of values that the user can enter
-     * @param {boolean} [multiple] - Optional parameter indicating whether the user can select multiple values
-     * @param {boolean} [showDropdown] - Optional parameter indicating whether to display the list in a dropdown
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Sets a data validation rule that requires the user to enter a value within a specific range.
+     * The range is defined by an FRange object, which contains the unit ID, sheet name, and cell range.
+     * @param {FRange} range - An FRange object representing the range of values that the user can enter.
+     * @param {boolean} [multiple] - Optional parameter indicating whether the user can select multiple values.
+     * @param {boolean} [showDropdown] - Optional parameter indicating whether to display the list in a dropdown.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Set the values in the range B1:B2
      * const fRange = fWorksheet.getRange('B1:B2');
      * fRange.setValues([
      *   ['Yes'],
      *   ['No']
      * ]);
      *
+     * // Create a new data validation rule that requires the user to enter a value from the range B1:B2 for the range A1:A10
      * const rule = univerAPI.newDataValidation()
      *   .requireValueInRange(fRange)
      *   .setOptions({
@@ -574,11 +650,11 @@ export declare class FDataValidationBuilder {
      */
     requireValueInRange(range: FRange, multiple?: boolean, showDropdown?: boolean): FDataValidationBuilder;
     /**
-     * Sets whether to allow invalid data and configures the error style
-     * If invalid data is not allowed, the error style will be set to STOP, indicating that data entry must stop upon encountering an error
-     * If invalid data is allowed, the error style will be set to WARNING, indicating that a warning will be displayed when invalid data is entered, but data entry can continue
-     * @param {boolean} allowInvalidData - Whether to allow invalid data
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Sets whether to allow invalid data and configures the error style.
+     * If invalid data is not allowed, the error style will be set to STOP, indicating that data entry must stop upon encountering an error.
+     * If invalid data is allowed, the error style will be set to WARNING, indicating that a warning will be displayed when invalid data is entered, but data entry can continue.
+     * @param {boolean} allowInvalidData - Whether to allow invalid data.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
@@ -603,9 +679,9 @@ export declare class FDataValidationBuilder {
      */
     setAllowInvalid(allowInvalidData: boolean): FDataValidationBuilder;
     /**
-     * Sets whether to allow blank values
-     * @param {boolean} allowBlank - Whether to allow blank values
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Sets whether to allow blank values.
+     * @param {boolean} allowBlank - Whether to allow blank values.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * // Assume current sheet is empty data
@@ -631,13 +707,15 @@ export declare class FDataValidationBuilder {
      */
     setAllowBlank(allowBlank: boolean): FDataValidationBuilder;
     /**
-     * Sets the options for the data validation rule
-     * @param {Partial<IDataValidationRuleOptions>} options - The options to set for the data validation rule
-     * @returns {FDataValidationBuilder} The current instance for method chaining
+     * Sets the options for the data validation rule.
+     * @param {Partial<IDataValidationRuleOptions>} options - The options to set for the data validation rule.
+     * @returns {FDataValidationBuilder} The current instance for method chaining.
      * @example
      * ```typescript
      * const fWorkbook = univerAPI.getActiveWorkbook();
      * const fWorksheet = fWorkbook.getActiveSheet();
+     *
+     * // Create a new data validation rule that requires the user to enter a value from the list ['Yes', 'No'] for the range A1:B10
      * const fRange = fWorksheet.getRange('A1:B10');
      * const rule = univerAPI.newDataValidation()
      *   .requireValueInList(['Yes', 'No'])