Merge pull request #11185 from TerryGLee/tglee-ide010

update Spell Checker preview page with recent changes & examples

Author: American-Dipper

docs/ide/text-spell-checker.md

@@ -1,7 +1,7 @@
 ---
-title: "Learn about the Text Spell Checker (Preview)"
-description: Learn how to use the Text Spell Checker to correct misspelled words in multiple languages and to customize it to share with your dev team.
-ms.date: 03/17/2023
+title: "Learn about the Spell Checker (Preview)"
+description: Learn how to use the Spell Checker in Visual Studio to correct misspelled words in multiple languages and to customize it to share with your dev team.
+ms.date: 05/10/2023
 ms.topic: conceptual
 author: TerryGLee
 ms.author: tglee
@@ -11,18 +11,18 @@ ms.workload:
 - multiple
 monikerRange: vs-2022
 ---
-# Learn about the Text Spell Checker (Preview)
+# Learn about the Spell Checker (Preview)
 
  [!INCLUDE [Visual Studio](~/includes/applies-to-version/vs-windows-only.md)]
 
-Many of the features in Visual Studio are designed to help you write the code you want, from making sure that your code compiles to helping you with code styling. Now, with the **Text Spell Checker** feature—introduced in [version 17.5](/visualstudio/releases/2022/release-notes-v17.5)—Visual Studio can even make sure your spelling is accurate.
+Many of the features in Visual Studio are designed to help you write the code you want, from making sure that your code compiles to helping you with code styling. Now, with the **Spell Checker** feature—introduced in [version 17.5](/visualstudio/releases/2022/release-notes-v17.5)—Visual Studio can even make sure your spelling is accurate.
 
-:::image type="content" source="media/vs-2022/text-spell-checker.png" alt-text="Screenshot of an example of the Text Spell Checker in action.":::
+:::image type="content" source="media/vs-2022/text-spell-checker.png" alt-text="Screenshot of an example of the Spell Checker in action.":::
 
 > [!IMPORTANT]
-> This feature is still in development. It's available now in Visual Studio 2022 version 17.5, but it'll be refined in future Preview releases. For the latest update, see the [**Improving the Spell Checker**](https://devblogs.microsoft.com/visualstudio/improving-the-spell-checker/) post on the [Visual Studio Blog](https://devblogs.microsoft.com/visualstudio/).
+> This feature is still in development. It's available now in Visual Studio 2022 version 17.5, but it'll be refined in future releases. For the latest news, see the [**Improving the Spell Checker**](https://devblogs.microsoft.com/visualstudio/improving-the-spell-checker/) post on the [Visual Studio Blog](https://devblogs.microsoft.com/visualstudio/).
 
-Visual Studio automatically toggles on the Text Spell Checker feature with any C#, C++, or Markdown file. Visual Studio marks any words that it detects as misspelled words. Visual Studio also suggests alternate spellings and helps correct them. The feature even does a contextual rename when those misspellings are identifiers so that your code still compiles.
+The Spell Checker is available for any C#, C++, or Markdown file. When the Spell Checker is enabled, Visual Studio marks any words that it detects as misspelled words. Visual Studio also suggests alternate spellings and helps correct them. The feature even does a contextual rename when those misspellings are identifiers so that your code still compiles.
 
 You can turn the spell checker off or on by using the **Toggle Text Spell Checker** button on the main toolbar, or by selecting **Edit** > **Advanced** > **Toggle Text Spell Checker** command from the menu bar.
 
@@ -32,17 +32,20 @@ When the caret is on a spelling error, the [Quick Actions](quick-actions.md) pro
 
 If any of the dictionaries provide spelling suggestions, Visual Studio displays them. If multiple dictionaries provide suggestions, Visual Studio groups its suggestions by dictionary. For strings and comments, choosing one of these suggestions results in a single, in-place replacement. For identifiers in a C++ or a C# document, accepting a suggestion results in a Refactor/Rename that updates all instances of the identifier to make sure the code compiles.
 
-:::image type="content" source="media/vs-2022/text-spell-checker-multiple-dictionaries.png" alt-text="Screenshot of the Text Spelling Checker with multiple dictionaries listed.":::
+:::image type="content" source="media/vs-2022/text-spell-checker-multiple-dictionaries.png" alt-text="Screenshot of the Spell Checker with multiple dictionaries listed.":::
 
 You can also choose to ignore the spelling issue. By choosing to ignore the issue, Visual Studio creates an exclusion.dic file in your AppData directory on your local machine. After you choose to ignore a word, the spelling checker ignores it across all instances of Visual Studio.
 
 ## How does it work?
 
 Because C#, C++, and Markdown all use English as the language for their keywords, Visual Studio typically uses the "English (United States)" or "en-us" dictionary for spell checking. Visual Studio checks the instance of Windows for the display language it's using, and if it's not "en-us", it uses that dictionary as well.
 
-Feedback from early users of this feature informed us that developers wanted to know about errors in the documents they were currently working with. In direct response to this feedback, the spell checker scans documents that are open.
+> [!NOTE]
+> C# and C++ also have additional dictonaries for keywords in those languages, which prevents words like ‘namespace’ or ‘alloc’ from being flagged as misspelled words.
 
-The following table shows some of the heuristics that the **Text Spell Checker** looks at when it scans a code document:
+Feedback from early users of this feature informed us that developers only want to know about errors in the document they are currently working with. In response to that feedback, the spell checker only scans the document(s) that are active in the editor. In direct response to this feedback, the spell checker scans documents that are open.
+
+The following table shows some of the heuristics that the **Spell Checker** looks at when it scans a code document:
 
 | What's in the code | What Visual Studio checks | Why? |
 |---------|---------|---------|
@@ -54,11 +57,11 @@ The following table shows some of the heuristics that the **Text Spell Checker**
 | btnWorld | World, world | Fragments of three characters or fewer are ignored |
 | helloworld | Helloworld, helloworld | No indicator to identify word boundaries |
 
-Otherwise, Visual Studio considers the word misspelled and flags the token as a spelling error. Visual Studio displays the spelling error with a severity of "Message" in the Error List with a "SPELL" Code.
+If Visual Studio finds a match for the token in any of the dictionaries it's using, the token is considered acceptable and the scan carries on. Otherwise, the token is considered misspelled and Visual Studio flags it as a spelling error.
 
 :::image type="content" source="media/vs-2022/text-spell-checker-error-list-example.png" alt-text="Screenshot of an example of spelling errors in the Error List.":::
 
-## How to customize the Text Spell Checker
+## How to customize the Spell Checker
 
 You can customize the spell checker so that it's optimized for a collaborative environment. As such, Visual Studio uses an [EditorConfig](create-portable-custom-editor-options.md) file for configuration so that you can control the spell checker behavior in a repository.
 
@@ -72,7 +75,7 @@ Here are some examples and use-case scenarios of the switches you can configure
     ```(Example: = en-us,fr-fr)```
 
     > [!NOTE]
-    > Make sure to install the [language pack](../install/install-visual-studio.md) for any non-default language you're using to prevent Visual Studio from incorrectly flagging words as spelling errors.
+    > Make sure to install the [language pack](../install/install-visual-studio.md) for any language you're using to prevent Visual Studio from incorrectly flagging words as spelling errors.
 
 - Control what Visual Studio should check. In this example, Visual Studio would check identifiers and comments for misspelled words but wouldn’t check inside strings.
 
@@ -84,13 +87,26 @@ Here are some examples and use-case scenarios of the switches you can configure
     ```spelling_error_severity = error OR warning OR information OR hint```<br>
     ```(Example: = error)```
 
-- Create your own exclusion dictionary to specify words you consider to be correctly spelled. In this example, the first time the Text Spell Checker is run against any file in the solution, Visual Studio checks for an exclusion.dic file in the same directory as the .sln file (for a C# project) or in the root directory (for a C++ directory). If no exclusion.dic file exists, the Visual Studio creates one. Then, whenever the user chooses to ignore a word, Visual Studio adds it to this exclusion.dic file. Visual Studio considers any word that appears in this exclusion.dic file as a correctly spelled word.
+- Create your own exclusion dictionary to specify words you consider to be correctly spelled. In this example, the first time the Spell Checker is run against any file in the solution, Visual Studio checks for an exclusion.dic file in the same directory as the .sln file (for a C# project) or in the root directory (for a C++ directory). If no exclusion.dic file exists, the Visual Studio creates one. Then, whenever the user chooses to ignore a word, Visual Studio adds it to this exclusion.dic file. Visual Studio considers any word that appears in this exclusion.dic file as a correctly spelled word.
 
     ```spelling_exclusion_path = absolute OR relative path to exclusion dictionary```<br>
     ```(Example: = .\exclusion.dic)```
 
-    > [!IMPORTANT]
-    > The exclusion.dic file must be UTF16 with BOM encoding to work correctly.
+    > [!NOTE]
+    > Visual Studio uses the exclusion dictionary specified by the spelling_exclusion_path switch in your .editorconfig file or an "exclusion.dic" file in your `%localappdata%\Microsoft\VisualStudio\<Version>` directory if a switch can’t be found.  
+
+- Control whether the language-specific exclusion dictionary so use. When set to false, any words specified in the exclusion dictionaries specific to C++ or C# won't be used. The default is true.
+
+    ```spelling_use_default_exclusion_dictionary = true OR false```<br> 
+    ```(Example: = spelling_use_default_exclusion_dictionary = false)```
+
+## Special case handling
+
+There are a few special behaviors in how Visual Studio checks code for spelling errors that are different from a traditional spell checker that's designed for written text. Some of these behaviors include:
+
+- In a string that includes punctuation, for example, 'misc.", Visual Studio won't suggest a correction because punctuation in an identifier might result in code that won't compile.
+- Backslashes in a string will omit the subsequent character from being spell-checked and treat the backslash and subsequent character as a word delimiter. For example, in the string `hello\nworld`, Visual Studio detects the backslash first. Visual Studio treats the `\n` as a word delimiter, which leaves "hello" and "world", each of which are checked individually.
+- Strings that contain URLs such as `https://...` or `mailto:..` won't be spell-checked over the entire string.
 
 ## See also