@cspell/cspell-types 5.19.6 → 5.21.0

package/cspell.schema.json

@@ -630,7 +630,7 @@
       "properties": {
         "allowCompoundWords": {
           "default": false,
-          "description": "True to enable compound word checking.",
+          "description": "True to enable compound word checking. See [Case Sensitivity](https://cspell.org/docs/case-sensitive/) for more details.",
           "type": "boolean"
         },
         "caseSensitive": {
@@ -643,14 +643,14 @@
           "type": "string"
         },
         "dictionaries": {
-          "description": "Optional list of dictionaries to use. Each entry should match the name of the dictionary. To remove a dictionary from the list add `!` before the name. i.e. `!typescript` will turn off the dictionary with the name `typescript`.",
+          "description": "Optional list of dictionaries to use. Each entry should match the name of the dictionary.\n\nTo remove a dictionary from the list, add `!` before the name.\n\nFor example, `!typescript` will turn off the dictionary with the name `typescript`.\n\nSee the [Dictionaries](https://cspell.org/docs/dictionaries/) and [Custom Dictionaries](https://cspell.org/docs/dictionaries-custom/) for more details.",
           "items": {
             "$ref": "#/definitions/DictionaryReference"
           },
           "type": "array"
         },
         "dictionaryDefinitions": {
-          "description": "Define additional available dictionaries.",
+          "description": "Define additional available dictionaries.\n\nFor example, you can use the following to add a custom dictionary:\n\n```json \"dictionaryDefinitions\": [   { \"name\": \"custom-words\", \"path\": \"./custom-words.txt\"} ], \"dictionaries\": [\"custom-words\"] ```",
           "items": {
             "$ref": "#/definitions/DictionaryDefinition"
           },
@@ -674,10 +674,10 @@
         },
         "ignoreRegExpList": {
           "$ref": "#/definitions/RegExpPatternList",
-          "description": "List of RegExp patterns or Pattern names to exclude from spell checking.\n\nExample: [\"href\"] - to exclude html href."
+          "description": "List of regular expression patterns or pattern names to exclude from spell checking.\n\nExample: [\"href\"] - to exclude html href.\n\nBy default, several patterns are excluded. See [Configuration](https://cspell.org/configuration/#cspelljson-sections) for more details.\n\nWhile you can create your own patterns, you can also leverage several patterns that are [built-in to CSpell](https://github.com/streetsidesoftware/cspell/blob/main/packages/cspell-lib/src/Settings/DefaultSettings.ts#L22)."
         },
         "ignoreWords": {
-          "description": "List of words to be ignored. An Ignored word will not show up as an error even if it is also in the `flagWords`.",
+          "description": "List of words to be ignored. An ignored word will not show up as an error, even if it is also in the `flagWords`.",
           "items": {
             "type": "string"
           },
@@ -685,7 +685,7 @@
         },
         "includeRegExpList": {
           "$ref": "#/definitions/RegExpPatternList",
-          "description": "List of RegExp patterns or defined Pattern names to define the text to be included for spell checking. If includeRegExpList is defined, ONLY, text matching the included patterns will be checked."
+          "description": "List of regular expression patterns or defined pattern names to match for spell checking.\n\nIf this property is defined, only text matching the included patterns will be checked.\n\nWhile you can create your own patterns, you can also leverage several patterns that are [built-in to CSpell](https://github.com/streetsidesoftware/cspell/blob/main/packages/cspell-lib/src/Settings/DefaultSettings.ts#L22)."
         },
         "languageId": {
           "anyOf": [
@@ -743,7 +743,7 @@
           "type": "array"
         },
         "patterns": {
-          "description": "Defines a list of patterns that can be used in ignoreRegExpList and includeRegExpList.",
+          "description": "Defines a list of patterns that can be used with the `ignoreRegExpList` and `includeRegExpList` options.\n\nFor example:\n\n```javascript \"ignoreRegExpList\": [\"comments\"], \"patterns\": [   {     \"name\": \"comment-single-line\",     \"pattern\": \"/#.*​/g\"   },   {     \"name\": \"comment-multi-line\",     \"pattern\": \"/(?:\\\\/\\\\*[\\\\s\\\\S]*?\\\\*\\\\/)/g\"   },   // You can also combine multiple named patterns into one single named pattern   {     \"name\": \"comments\",     \"pattern\": [\"comment-single-line\", \"comment-multi-line\"]   } ] ```",
           "items": {
             "$ref": "#/definitions/RegExpPatternDefinition"
           },
@@ -771,7 +771,7 @@
       "properties": {
         "allowCompoundWords": {
           "default": false,
-          "description": "True to enable compound word checking.",
+          "description": "True to enable compound word checking. See [Case Sensitivity](https://cspell.org/docs/case-sensitive/) for more details.",
           "type": "boolean"
         },
         "caseSensitive": {
@@ -784,14 +784,14 @@
           "type": "string"
         },
         "dictionaries": {
-          "description": "Optional list of dictionaries to use. Each entry should match the name of the dictionary. To remove a dictionary from the list add `!` before the name. i.e. `!typescript` will turn off the dictionary with the name `typescript`.",
+          "description": "Optional list of dictionaries to use. Each entry should match the name of the dictionary.\n\nTo remove a dictionary from the list, add `!` before the name.\n\nFor example, `!typescript` will turn off the dictionary with the name `typescript`.\n\nSee the [Dictionaries](https://cspell.org/docs/dictionaries/) and [Custom Dictionaries](https://cspell.org/docs/dictionaries-custom/) for more details.",
           "items": {
             "$ref": "#/definitions/DictionaryReference"
           },
           "type": "array"
         },
         "dictionaryDefinitions": {
-          "description": "Define additional available dictionaries.",
+          "description": "Define additional available dictionaries.\n\nFor example, you can use the following to add a custom dictionary:\n\n```json \"dictionaryDefinitions\": [   { \"name\": \"custom-words\", \"path\": \"./custom-words.txt\"} ], \"dictionaries\": [\"custom-words\"] ```",
           "items": {
             "$ref": "#/definitions/DictionaryDefinition"
           },
@@ -846,10 +846,10 @@
         },
         "ignoreRegExpList": {
           "$ref": "#/definitions/RegExpPatternList",
-          "description": "List of RegExp patterns or Pattern names to exclude from spell checking.\n\nExample: [\"href\"] - to exclude html href."
+          "description": "List of regular expression patterns or pattern names to exclude from spell checking.\n\nExample: [\"href\"] - to exclude html href.\n\nBy default, several patterns are excluded. See [Configuration](https://cspell.org/configuration/#cspelljson-sections) for more details.\n\nWhile you can create your own patterns, you can also leverage several patterns that are [built-in to CSpell](https://github.com/streetsidesoftware/cspell/blob/main/packages/cspell-lib/src/Settings/DefaultSettings.ts#L22)."
         },
         "ignoreWords": {
-          "description": "List of words to be ignored. An Ignored word will not show up as an error even if it is also in the `flagWords`.",
+          "description": "List of words to be ignored. An ignored word will not show up as an error, even if it is also in the `flagWords`.",
           "items": {
             "type": "string"
           },
@@ -857,7 +857,7 @@
         },
         "includeRegExpList": {
           "$ref": "#/definitions/RegExpPatternList",
-          "description": "List of RegExp patterns or defined Pattern names to define the text to be included for spell checking. If includeRegExpList is defined, ONLY, text matching the included patterns will be checked."
+          "description": "List of regular expression patterns or defined pattern names to match for spell checking.\n\nIf this property is defined, only text matching the included patterns will be checked.\n\nWhile you can create your own patterns, you can also leverage several patterns that are [built-in to CSpell](https://github.com/streetsidesoftware/cspell/blob/main/packages/cspell-lib/src/Settings/DefaultSettings.ts#L22)."
         },
         "language": {
           "$ref": "#/definitions/LocaleId",
@@ -868,7 +868,7 @@
           "description": "Sets the programming language id."
         },
         "languageSettings": {
-          "description": "Additional settings for individual languages.",
+          "description": "Additional settings for individual languages.\n\nSee [Language Settings](https://cspell.org/configuration/language-settings/) for more details.",
           "items": {
             "$ref": "#/definitions/LanguageSetting"
           },
@@ -911,7 +911,7 @@
           "type": "number"
         },
         "patterns": {
-          "description": "Defines a list of patterns that can be used in ignoreRegExpList and includeRegExpList.",
+          "description": "Defines a list of patterns that can be used with the `ignoreRegExpList` and `includeRegExpList` options.\n\nFor example:\n\n```javascript \"ignoreRegExpList\": [\"comments\"], \"patterns\": [   {     \"name\": \"comment-single-line\",     \"pattern\": \"/#.*​/g\"   },   {     \"name\": \"comment-multi-line\",     \"pattern\": \"/(?:\\\\/\\\\*[\\\\s\\\\S]*?\\\\*\\\\/)/g\"   },   // You can also combine multiple named patterns into one single named pattern   {     \"name\": \"comments\",     \"pattern\": [\"comment-single-line\", \"comment-multi-line\"]   } ] ```",
           "items": {
             "$ref": "#/definitions/RegExpPatternDefinition"
           },
@@ -1168,7 +1168,7 @@
     },
     "allowCompoundWords": {
       "default": false,
-      "description": "True to enable compound word checking.",
+      "description": "True to enable compound word checking. See [Case Sensitivity](https://cspell.org/docs/case-sensitive/) for more details.",
       "type": "boolean"
     },
     "cache": {
@@ -1185,14 +1185,14 @@
       "type": "string"
     },
     "dictionaries": {
-      "description": "Optional list of dictionaries to use. Each entry should match the name of the dictionary. To remove a dictionary from the list add `!` before the name. i.e. `!typescript` will turn off the dictionary with the name `typescript`.",
+      "description": "Optional list of dictionaries to use. Each entry should match the name of the dictionary.\n\nTo remove a dictionary from the list, add `!` before the name.\n\nFor example, `!typescript` will turn off the dictionary with the name `typescript`.\n\nSee the [Dictionaries](https://cspell.org/docs/dictionaries/) and [Custom Dictionaries](https://cspell.org/docs/dictionaries-custom/) for more details.",
       "items": {
         "$ref": "#/definitions/DictionaryReference"
       },
       "type": "array"
     },
     "dictionaryDefinitions": {
-      "description": "Define additional available dictionaries.",
+      "description": "Define additional available dictionaries.\n\nFor example, you can use the following to add a custom dictionary:\n\n```json \"dictionaryDefinitions\": [   { \"name\": \"custom-words\", \"path\": \"./custom-words.txt\"} ], \"dictionaries\": [\"custom-words\"] ```",
       "items": {
         "$ref": "#/definitions/DictionaryDefinition"
       },
@@ -1210,7 +1210,7 @@
     },
     "enableGlobDot": {
       "default": false,
-      "description": "Enable scanning files and directories beginning with `.` (period). By default, CSpell does not scan `hidden` files.",
+      "description": "Enable scanning files and directories beginning with `.` (period).\n\nBy default, CSpell does not scan `hidden` files.",
       "type": "boolean"
     },
     "enabled": {
@@ -1235,7 +1235,7 @@
       "description": "Configure CSpell features.\n\n- Added with `v5.16.0`."
     },
     "files": {
-      "description": "Glob patterns of files to be checked. Glob patterns are relative to the `globRoot` of the configuration file that defines them.",
+      "description": "Glob patterns of files to be checked.\n\nGlob patterns are relative to the `globRoot` of the configuration file that defines them.",
       "items": {
         "$ref": "#/definitions/Glob"
       },
@@ -1271,7 +1271,7 @@
       "type": "string"
     },
     "ignorePaths": {
-      "description": "Glob patterns of files to be ignored. Glob patterns are relative to the `globRoot` of the configuration file that defines them.",
+      "description": "Glob patterns of files to be ignored.\n\nGlob patterns are relative to the `globRoot` of the configuration file that defines them.",
       "items": {
         "$ref": "#/definitions/Glob"
       },
@@ -1279,10 +1279,10 @@
     },
     "ignoreRegExpList": {
       "$ref": "#/definitions/RegExpPatternList",
-      "description": "List of RegExp patterns or Pattern names to exclude from spell checking.\n\nExample: [\"href\"] - to exclude html href."
+      "description": "List of regular expression patterns or pattern names to exclude from spell checking.\n\nExample: [\"href\"] - to exclude html href.\n\nBy default, several patterns are excluded. See [Configuration](https://cspell.org/configuration/#cspelljson-sections) for more details.\n\nWhile you can create your own patterns, you can also leverage several patterns that are [built-in to CSpell](https://github.com/streetsidesoftware/cspell/blob/main/packages/cspell-lib/src/Settings/DefaultSettings.ts#L22)."
     },
     "ignoreWords": {
-      "description": "List of words to be ignored. An Ignored word will not show up as an error even if it is also in the `flagWords`.",
+      "description": "List of words to be ignored. An ignored word will not show up as an error, even if it is also in the `flagWords`.",
       "items": {
         "type": "string"
       },
@@ -1300,23 +1300,23 @@
           "type": "array"
         }
       ],
-      "description": "Other settings files to be included."
+      "description": "Allows this configuration to inherit configuration for one or more other files.\n\nSee [Importing / Extending Configuration](https://cspell.org/configuration/imports/) for more details."
     },
     "includeRegExpList": {
       "$ref": "#/definitions/RegExpPatternList",
-      "description": "List of RegExp patterns or defined Pattern names to define the text to be included for spell checking. If includeRegExpList is defined, ONLY, text matching the included patterns will be checked."
+      "description": "List of regular expression patterns or defined pattern names to match for spell checking.\n\nIf this property is defined, only text matching the included patterns will be checked.\n\nWhile you can create your own patterns, you can also leverage several patterns that are [built-in to CSpell](https://github.com/streetsidesoftware/cspell/blob/main/packages/cspell-lib/src/Settings/DefaultSettings.ts#L22)."
     },
     "language": {
       "$ref": "#/definitions/LocaleId",
       "default": "en",
-      "description": "Current active spelling language.\n\nExample: \"en-GB\" for British English.\n\nExample: \"en,nl\" to enable both English and Dutch."
+      "description": "Current active spelling language. This specifies the language locale to use in choosing the general dictionary.\n\nFor example:\n\n- \"en-GB\" for British English.\n- \"en,nl\" to enable both English and Dutch."
     },
     "languageId": {
       "$ref": "#/definitions/LanguageId",
       "description": "Forces the spell checker to assume a give language id. Used mainly as an Override."
     },
     "languageSettings": {
-      "description": "Additional settings for individual languages.",
+      "description": "Additional settings for individual languages.\n\nSee [Language Settings](https://cspell.org/configuration/language-settings/) for more details.",
       "items": {
         "$ref": "#/definitions/LanguageSetting"
       },
@@ -1364,14 +1364,14 @@
       "type": "number"
     },
     "overrides": {
-      "description": "Overrides to apply based upon the file path.",
+      "description": "Overrides are used to apply settings for specific files in your project.\n\nFor example:\n\n```javascript \"overrides\": [   // Force `*.hrr` and `*.crr` files to be treated as `cpp` files:   {     \"filename\": \"**​/{*.hrr,*.crr}\",     \"languageId\": \"cpp\"   },   // Force `*.txt` to use the Dutch dictionary (Dutch dictionary needs to be installed separately):   {     \"language\": \"nl\",     \"filename\": \"**​/dutch/**​/*.txt\"   } ] ```",
       "items": {
         "$ref": "#/definitions/OverrideSettings"
       },
       "type": "array"
     },
     "patterns": {
-      "description": "Defines a list of patterns that can be used in ignoreRegExpList and includeRegExpList.",
+      "description": "Defines a list of patterns that can be used with the `ignoreRegExpList` and `includeRegExpList` options.\n\nFor example:\n\n```javascript \"ignoreRegExpList\": [\"comments\"], \"patterns\": [   {     \"name\": \"comment-single-line\",     \"pattern\": \"/#.*​/g\"   },   {     \"name\": \"comment-multi-line\",     \"pattern\": \"/(?:\\\\/\\\\*[\\\\s\\\\S]*?\\\\*\\\\/)/g\"   },   // You can also combine multiple named patterns into one single named pattern   {     \"name\": \"comments\",     \"pattern\": [\"comment-single-line\", \"comment-multi-line\"]   } ] ```",
       "items": {
         "$ref": "#/definitions/RegExpPatternDefinition"
       },
@@ -1440,7 +1440,7 @@
     "version": {
       "$ref": "#/definitions/Version",
       "default": "0.2",
-      "description": "Configuration format version of the settings file."
+      "description": "Configuration format version of the settings file.\n\nThis controls how the settings in the configuration file behave."
     },
     "words": {
       "description": "List of words to be always considered correct.",

package/dist/CSpellSettingsDef.d.ts

@@ -27,12 +27,19 @@ export interface CSpellSettingsWithSourceTrace extends CSpellSettings {
 export interface FileSettings extends ExtendableSettings, CommandLineSettings {
     /**
      * Configuration format version of the settings file.
+     *
+     * This controls how the settings in the configuration file behave.
+     *
      * @default "0.2"
      */
     version?: Version;
     /** Words to add to global dictionary -- should only be in the user config file. */
     userWords?: string[];
-    /** Other settings files to be included. */
+    /**
+     * Allows this configuration to inherit configuration for one or more other files.
+     *
+     * See [Importing / Extending Configuration](https://cspell.org/configuration/imports/) for more details.
+     */
     import?: FsPath | FsPath[];
     /**
      * The root to use for glob patterns found in this configuration.
@@ -52,11 +59,13 @@ export interface FileSettings extends ExtendableSettings, CommandLineSettings {
     globRoot?: FSPathResolvable;
     /**
      * Glob patterns of files to be checked.
+     *
      * Glob patterns are relative to the `globRoot` of the configuration file that defines them.
      */
     files?: Glob[];
     /**
      * Enable scanning files and directories beginning with `.` (period).
+     *
      * By default, CSpell does not scan `hidden` files.
      *
      * @default false
@@ -64,11 +73,13 @@ export interface FileSettings extends ExtendableSettings, CommandLineSettings {
     enableGlobDot?: boolean;
     /**
      * Glob patterns of files to be ignored.
+     *
      * Glob patterns are relative to the `globRoot` of the configuration file that defines them.
      */
     ignorePaths?: Glob[];
     /**
      * Prevents searching for local configuration when checking individual documents.
+     *
      * @default false
      */
     noConfigSearch?: boolean;
@@ -76,6 +87,7 @@ export interface FileSettings extends ExtendableSettings, CommandLineSettings {
      * Indicate that the configuration file should not be modified.
      * This is used to prevent tools like the VS Code Spell Checker from
      * modifying the file to add words and other configuration.
+     *
      * @default false
      */
     readonly?: boolean;
@@ -99,17 +111,47 @@ export interface FileSettings extends ExtendableSettings, CommandLineSettings {
      */
     features?: Features;
 }
+/**
+ * In the below JSDoc comment, we helpfully specify an example configuration for the end-user to
+ * reference. And this example will get captured by the automatic documentation generator.
+ *
+ * However, specifying the glob pattern inside of a JSDoc is tricky, because the glob contains the
+ * same symbol as the end-of-JSDoc symbol. To work around this, we insert a zero-width space in
+ * between the "*" and the "/" symbols.
+ */
 export interface ExtendableSettings extends Settings {
-    /** Overrides to apply based upon the file path. */
+    /**
+     * Overrides are used to apply settings for specific files in your project.
+     *
+     * For example:
+     *
+     * ```javascript
+     * "overrides": [
+     *   // Force `*.hrr` and `*.crr` files to be treated as `cpp` files:
+     *   {
+     *     "filename": "**​/{*.hrr,*.crr}",
+     *     "languageId": "cpp"
+     *   },
+     *   // Force `*.txt` to use the Dutch dictionary (Dutch dictionary needs to be installed separately):
+     *   {
+     *     "language": "nl",
+     *     "filename": "**​/dutch/**​/*.txt"
+     *   }
+     * ]
+     * ```
+     */
     overrides?: OverrideSettings[];
 }
 export interface Settings extends ReportingConfiguration, BaseSetting, PnPSettings {
     /**
-     * Current active spelling language.
+     * Current active spelling language. This specifies the language locale to use in choosing the
+     * general dictionary.
+     *
+     * For example:
      *
-     * Example: "en-GB" for British English.
+     * - "en-GB" for British English.
+     * - "en,nl" to enable both English and Dutch.
      *
-     * Example: "en,nl" to enable both English and Dutch.
      * @default "en"
      */
     language?: LocaleId;
@@ -132,13 +174,18 @@ export interface Settings extends ReportingConfiguration, BaseSetting, PnPSettin
      * ```
      */
     enableFiletypes?: LanguageIdSingle[];
-    /** Additional settings for individual languages. */
+    /**
+     * Additional settings for individual languages.
+     *
+     * See [Language Settings](https://cspell.org/configuration/language-settings/) for more details.
+     */
     languageSettings?: LanguageSetting[];
     /** Forces the spell checker to assume a give language id. Used mainly as an Override. */
     languageId?: LanguageId;
     /**
      * By default, the bundled dictionary configurations are loaded. Explicitly setting this to `false`
      * will prevent ALL default configuration from being loaded.
+     *
      * @default true
      */
     loadDefaultConfiguration?: boolean;
@@ -146,16 +193,19 @@ export interface Settings extends ReportingConfiguration, BaseSetting, PnPSettin
 export interface ReportingConfiguration extends SuggestionsConfiguration {
     /**
      * The maximum number of problems to report in a file.
+     *
      * @default 100
      */
     maxNumberOfProblems?: number;
     /**
      * The maximum number of times the same word can be flagged as an error in a file.
+     *
      * @default 5
      */
     maxDuplicateProblems?: number;
     /**
      * The minimum length of a word before checking it against a dictionary.
+     *
      * @default 4
      */
     minWordLength?: number;
@@ -163,11 +213,13 @@ export interface ReportingConfiguration extends SuggestionsConfiguration {
 export interface SuggestionsConfiguration {
     /**
      * Number of suggestions to make.
+     *
      * @default 10
      */
     numSuggestions?: number;
     /**
      * The maximum amount of time in milliseconds to generate suggestions for a word.
+     *
      * @default 500
      */
     suggestionsTimeout?: number;
@@ -177,6 +229,7 @@ export interface SuggestionsConfiguration {
      * For example, appending an `s` onto `example` -> `examples` is considered 1 change.
      *
      * Range: between 1 and 5.
+     *
      * @default 3
      */
     suggestionNumChanges?: number;
@@ -310,10 +363,14 @@ export interface BaseSetting {
     words?: string[];
     /** List of words to always be considered incorrect. */
     flagWords?: string[];
-    /** List of words to be ignored. An Ignored word will not show up as an error even if it is also in the `flagWords`. */
+    /**
+     * List of words to be ignored. An ignored word will not show up as an error, even if it is
+     * also in the `flagWords`.
+     */
     ignoreWords?: string[];
     /**
-     * True to enable compound word checking.
+     * True to enable compound word checking. See [Case Sensitivity](https://cspell.org/docs/case-sensitive/) for more details.
+     *
      * @default false
      */
     allowCompoundWords?: boolean;
@@ -327,13 +384,28 @@ export interface BaseSetting {
      * @default false
      */
     caseSensitive?: boolean;
-    /** Define additional available dictionaries. */
+    /**
+     * Define additional available dictionaries.
+     *
+     * For example, you can use the following to add a custom dictionary:
+     *
+     * ```json
+     * "dictionaryDefinitions": [
+     *   { "name": "custom-words", "path": "./custom-words.txt"}
+     * ],
+     * "dictionaries": ["custom-words"]
+     * ```
+     */
     dictionaryDefinitions?: DictionaryDefinition[];
     /**
-     * Optional list of dictionaries to use.
-     * Each entry should match the name of the dictionary.
-     * To remove a dictionary from the list add `!` before the name.
-     * i.e. `!typescript` will turn off the dictionary with the name `typescript`.
+     * Optional list of dictionaries to use. Each entry should match the name of the dictionary.
+     *
+     * To remove a dictionary from the list, add `!` before the name.
+     *
+     * For example, `!typescript` will turn off the dictionary with the name `typescript`.
+     *
+     * See the [Dictionaries](https://cspell.org/docs/dictionaries/)
+     * and [Custom Dictionaries](https://cspell.org/docs/dictionaries-custom/) for more details.
      */
     dictionaries?: DictionaryReference[];
     /**
@@ -347,17 +419,51 @@ export interface BaseSetting {
      */
     noSuggestDictionaries?: DictionaryReference[];
     /**
-     * List of RegExp patterns or Pattern names to exclude from spell checking.
+     * List of regular expression patterns or pattern names to exclude from spell checking.
      *
      * Example: ["href"] - to exclude html href.
+     *
+     * By default, several patterns are excluded. See
+     * [Configuration](https://cspell.org/configuration/#cspelljson-sections) for more details.
+     *
+     * While you can create your own patterns, you can also leverage several patterns that are
+     * [built-in to CSpell](https://github.com/streetsidesoftware/cspell/blob/main/packages/cspell-lib/src/Settings/DefaultSettings.ts#L22).
      */
     ignoreRegExpList?: RegExpPatternList;
     /**
-     * List of RegExp patterns or defined Pattern names to define the text to be included for spell checking.
-     * If includeRegExpList is defined, ONLY, text matching the included patterns will be checked.
+     * List of regular expression patterns or defined pattern names to match for spell checking.
+     *
+     * If this property is defined, only text matching the included patterns will be checked.
+     *
+     * While you can create your own patterns, you can also leverage several patterns that are
+     * [built-in to CSpell](https://github.com/streetsidesoftware/cspell/blob/main/packages/cspell-lib/src/Settings/DefaultSettings.ts#L22).
      */
     includeRegExpList?: RegExpPatternList;
-    /** Defines a list of patterns that can be used in ignoreRegExpList and includeRegExpList. */
+    /**
+     * Defines a list of patterns that can be used with the `ignoreRegExpList` and
+     * `includeRegExpList` options.
+     *
+     * For example:
+     *
+     * ```javascript
+     * "ignoreRegExpList": ["comments"],
+     * "patterns": [
+     *   {
+     *     "name": "comment-single-line",
+     *     "pattern": "/#.*​/g"
+     *   },
+     *   {
+     *     "name": "comment-multi-line",
+     *     "pattern": "/(?:\\/\\*[\\s\\S]*?\\*\\/)/g"
+     *   },
+     *   // You can also combine multiple named patterns into one single named pattern
+     *   {
+     *     "name": "comments",
+     *     "pattern": ["comment-single-line", "comment-multi-line"]
+     *   }
+     * ]
+     * ```
+     */
     patterns?: RegExpPatternDefinition[];
 }
 export declare type DictionaryFileTypes = 'S' | 'W' | 'C' | 'T';

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "5.19.6",
+  "version": "5.21.0",
   "description": "Types for cspell and cspell-lib",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -18,7 +18,7 @@
     "build": "npm run compile && npm run build-schema",
     "build-dev": "tsc -p tsconfig.dev.json",
     "build-schema": "ts-json-schema-generator --no-top-ref --path src/CSpellSettingsDef.ts --type CSpellSettings --validation-keywords markdownDescription  --validation-keywords scope --validation-keywords deprecated --validation-keywords deprecationMessage -o  ./cspell.schema.json && cp ./cspell.schema.json ../..",
-    "build-docs": "rimraf ../../docs/types/cspell-types && typedoc --out ../../docs/types/cspell-types src/index.ts",
+    "build-cspell-types-docs": "rimraf ../../docs/types/cspell-types && typedoc --out ../../docs/types/cspell-types src/index.ts",
     "test-build-docs": "typedoc --out ./temp/docs src/index.ts",
     "clean-build": "npm run clean && npm run build",
     "compile": "tsc -p .",
@@ -50,12 +50,12 @@
   },
   "devDependencies": {
     "ajv-cli": "^5.0.0",
-    "jest": "^27.5.1",
+    "jest": "^28.1.0",
     "rimraf": "^3.0.2",
     "ts-json-schema-generator": "^1.0.0",
-    "typedoc": "0.22.14",
-    "typedoc-plugin-markdown": "^3.11.14",
-    "typescript": "^4.6.3"
+    "typedoc": "0.22.15",
+    "typedoc-plugin-markdown": "^3.12.1",
+    "typescript": "^4.6.4"
   },
-  "gitHead": "288584aa11eb262dab45201824c90206d7db65c3"
+  "gitHead": "d0758cb805404cb62b7a0c6c852c337f2122ead0"
 }