Merge pull request #27 from matteo-prosperi/dev/maprospe/classification

Add docs for classification taggers and minor cleanup of editor docs.

Author: tinaschrepfer

docs/extensibility/visualstudio.extensibility/editor/editor-concepts.md

@@ -14,7 +14,7 @@ ms.subservice: extensibility-integration
 
 This article describes the extensibility object model that represents the Visual Studio editor and the text document that is opened for editing. For an introduction to working with the editor extension functionality, see [Use Visual Studio editor extensibility](editor.md).
 
-The Visual Studio Editor extensibility object model is composed of a few integral parts. This article covers [ITextViewSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextviewsnapshot), [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot), and other abstract representations of the whole document, as well as `Position` and `Span`, which represent location and spans of text, respectively.
+The Visual Studio Editor extensibility object model is composed of a few integral parts. This article covers [ITextViewSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextviewsnapshot), [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot), and other abstract representations of the whole document, as well as [TextPosition](/dotnet/api/microsoft.visualstudio.extensibility.editor.textposition) and [TextRange](/dotnet/api/microsoft.visualstudio.extensibility.editor.textrange), which represent locations and spans of text, respectively.
 
 ## ITextViewSnapshot
 
@@ -36,25 +36,33 @@ If you're familiar with legacy Visual Studio extensions, [ITextDocumentSnapshot]
 
 Best Practices:
 
-- You can use Position and Span to represent substrings in the document without expending resources copying or allocating strings. Most APIs operate in terms of these primitives.
+- You can use Position and Range to represent substrings in the document without expending resources copying or allocating strings. Most APIs operate in terms of these primitives.
 - You can use the indexer syntax, `textDocument[0]`, to read character by character in the document without copying it to a string.
-- If you must create a string such as for use as a dictionary key, use the overload that takes a `Span`, to avoid creating a large throwaway string from the entire line or document.
+- If you must create a string such as for use as a dictionary key, use the overload that takes a `Range`, to avoid creating a large throwaway string from the entire line or document.
 - Avoid assuming lines or documents will be short. Many languages minify into huge lines or consume very large files
-- - [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) references large data structures that may consume memory if an old enough version is stored. Best practice is to periodically update positions and spans that you're storing long term to the latest document version via their `TranslateTo()` method so the old `ITextDocumentSnapshot` version can be garbage collected.
+- - [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) references large data structures that may consume memory if an old enough version is stored. Best practice is to periodically update positions and ranges that you're storing long term to the latest document version via their `TranslateTo()` method so the old `ITextDocumentSnapshot` version can be garbage collected.
 
 ## Position
 
-Represents a position within the text document. As opposed to `int` positions, the Position type is aware of the [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) it came from and supports `GetChar()` to directly get the character at that point.
+[TextPosition](/dotnet/api/microsoft.visualstudio.extensibility.editor.textposition) represents a position within the text document. As opposed to `int` positions, the `TextPosition` type is aware of the [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) it came from and supports `GetChar()` to directly get the character at that point.
 
-If you're familiar with legacy Visual Studio extensions, Position is almost the same as [SnapshotPoint](/dotnet/api/microsoft.visualstudio.text.snapshotpoint) and supports most of the same methods.
+If you're familiar with legacy Visual Studio extensions, `TextPosition` is almost the same as [SnapshotPoint](/dotnet/api/microsoft.visualstudio.text.snapshotpoint) and supports most of the same methods.
 
-## Span
+## Range
 
-Represents a contiguous substring of characters within an [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot). As opposed to a string created with `string.Substring()` or `ITextDocumentSnapshot.CopyToString()`, creating a Span doesn't require any allocations or additional memory. You can later call `Span.GetText()` to realize it into a string in a deferred fashion.
+[TextRange](/dotnet/api/microsoft.visualstudio.extensibility.editor.textrange) represents a contiguous substring of characters within an [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot). As opposed to a string created with `string.Substring()` or `ITextDocumentSnapshot.CopyToString()`, creating a `TextRange` doesn't require any allocations or additional memory. You can later call [CopyToString()](/dotnet/api/microsoft.visualstudio.extensibility.editor.textextensions.copytostring) to realize it into a string in a deferred fashion.
 
-If you're familiar with legacy Visual Studio extensions, `Position` is almost the same as
+If you're familiar with legacy Visual Studio extensions, `TextRange` is almost the same as
 [SnapshotSpan](/dotnet/api/microsoft.visualstudio.text.snapshotSpan) and supports most of the same methods.
 
+## Tracking modes
+
+`TextPosition` and `TextRange` are associated with a specific `ITextDocumentSnapshot`: the state of the document at a specific time. Such positions and ranges can be translated to a different snapshot using the `TranslateTo` methods. Such translation takes in account any text added or removed before, after (or, in the case of ranges, in the middle) the position or range. When any of such edits happen exactly at the position or exactly at the edge of the range, [TextPositionTrackingMode](/dotnet/api/microsoft.visualstudio.extensibility.editor.textpositiontrackingmode) and [TextRangeTrackingMode](/dotnet/api/microsoft.visualstudio.extensibility.editor.textrangetrackingmode) are used to specify how the translation should behave.
+
+## Tag
+
+[Taggers](./walkthroughs/taggers.md) are used to associate data (a [tag](/dotnet/api/microsoft.visualstudio.extensibility.editor.itag)) with spans of text, such data is consumed by other Visual Studio features (E.g., [CodeLens](./walkthroughs/codelens.md), [classification](./walkthroughs/classification.md), etc.).
+
 ## Related content
 
 Review sample code for a simple editor-based extension:

docs/extensibility/visualstudio.extensibility/editor/editor.md

@@ -44,7 +44,7 @@ Extensions can contribute new CodeLenses to the Visual Studio editor. A CodeLens
 For detailed walkthrough of how to provide your own CodeLens with your extension, refer to [Extending Visual Studio editor with a new CodeLens](./walkthroughs/codelens.md)
 
 ### Taggers
-Extensions can contribute new taggers to the Visual Studio editor. Taggers are used to associate data with spans of text, such data is consumed by other Visual Studio features (E.g., CodeLens).
+Extensions can contribute new taggers to the Visual Studio editor. Taggers are used to associate data with ranges of text, such data is consumed by other Visual Studio features (E.g., [CodeLens](./walkthroughs/codelens.md), [classification](./walkthroughs/classification.md), etc.).
 
 For detailed walkthrough of how to provide your own taggers with your extension, refer to [Extending Visual Studio editor with a new tagger](./walkthroughs/taggers.md)
 

docs/extensibility/visualstudio.extensibility/editor/walkthroughs/classification.md

@@ -0,0 +1,81 @@
+---
+title: Customizing classification in the editor
+description: A walkthrough of how to provide your own classification in the Visual Studio editor using extensions
+ms.date: 4/23/2025
+ms.topic: conceptual
+ms.author: maprospe
+monikerRange: ">=vs-2022"
+author: tinaschrepfer
+manager: mijacobs
+ms.subservice: extensibility-integration
+---
+
+# Extending Visual Studio editor with a new classification tagger
+
+A Visual Studio extension can classify a document's syntax allowing for
+the text to be colorized accordingly. This is achieved by contributing
+a tagger that returns `ClassificationTag` values.
+
+A detailed description of how to provide a tagger can be found in the
+[Extending Visual Studio editor with a new tagger](./taggers.md) article.
+
+Following the article linked above, we implement a tagger provider and a
+tagger:
+
+```cs
+[VisualStudioContribution]
+internal class MyClassificationTaggerProvider :
+    ExtensionPart,
+    ITextViewTaggerProvider<ClassificationTag>,
+    ITextViewChangedListener
+{
+    ...
+```
+
+```cs
+internal class MyClassificationTagger :
+    TextViewTagger<ClassificationTag>
+{
+    ...
+```
+
+Since we want the document colorization to appear as instantly as possible,
+the tagger will need to be as fast as possible. The article linked above
+stresses the importance of:
+- only generating tags for the requested document portion (or a small
+superset of it), not the whole document;
+- avoiding parsing the whole document in order to generate tags.
+
+Once the tagger structure is ready and the syntax parsing for the specific
+file format is implemented, the tagger can provide text classification, by
+simply creating `ClassificationTag` values using the available
+`ClassificationType` know values, and calling `UpdateTagsAsync`.
+
+```cs
+List<TaggedTrackingTextRange<ClassificationTag>> tags = new();
+List<TextRange> ranges = new();
+
+...
+
+ranges.Add(new(document, lineStart, lineLength));
+tags.Add(
+    new TaggedTrackingTextRange<ClassificationTag>(
+        new TrackingTextRange(
+            document,
+            tagStartPosition,
+            tagLength,
+            TextRangeTrackingMode.ExtendNone),
+        new ClassificationTag(ClassificationType.KnownValues.Operator)));
+
+...
+
+await this.UpdateTagsAsync(ranges, tags, CancellationToken.None);
+```
+
+At this time, VisualStudio.Extensibility doesn't support defining text colors
+for new classification types yet, so we must use existing classification types
+(`ClassificationType.KnownValues`).
+
+[VisualStudio.Extensibility in-proc extension](../../get-started/in-proc-extensions.md), can use [ClassificationTypeDefinition](/dotnet/api/microsoft.visualstudio.text.classification.classificationtypedefinition)
+to define new classification types. Their name can be referenced using
+`ClassificationType.Custom`.

docs/extensibility/visualstudio.extensibility/editor/walkthroughs/taggers.md

@@ -11,12 +11,13 @@ ms.subservice: extensibility-integration
 ---
 
 # Extending Visual Studio editor with a new tagger
-Extensions can contribute new taggers to Visual Studio. Taggers are used to associate data with spans of text. The data provided by taggers are consumed by other Visual Studio features (for example, [CodeLens](./codelens.md)).
+Extensions can contribute new taggers to Visual Studio. Taggers are used to associate data with ranges of text. The data provided by taggers are consumed by other Visual Studio features (for example, [CodeLens](./codelens.md)).
 
 VisualStudio.Extensibility only supports tag types that are provided by the [Microsoft.VisualStudio.Extensibility](https://www.nuget.org/packages/Microsoft.VisualStudio.Extensibility) package and implement the `Microsoft.VisualStudio.Extensibility.Editor.ITag` interface:
 
 - `CodeLensTag` can be used together with an [ICodeLensProvider](./codelens.md) to add Code Lenses to documents
 - `TextMarkerTag` can be used to highlight portions of documents. VisualStudio.Extensibility doesn't support defining new Text Marker styles yet, so only styles that are built into Visual Studio or provided by a VSSDK extension can be used for now (a [VisualStudio.Extensibility in-proc extension](../../get-started/in-proc-extensions.md) can create Text Marker styles with an `[Export(typeof(EditorFormatDefinition))]`).
+- `ClassificationTag` can be used to classify a document's syntax allowing for the text to be colorized accordingly.
 
 To generate tags, the extension must contribute an extension part that implements `ITextViewTaggerProvider<>` for the type (or types) of tags provided. The extension part also needs to implement `ITextViewChangedListener` to react to document changes:
 

docs/extensibility/visualstudio.extensibility/toc.yml

@@ -46,7 +46,9 @@ items:
       - name: Extending Visual Studio editor with a new CodeLens
         href: ./editor/walkthroughs/codelens.md
       - name: Extending Visual Studio editor with a new tagger
-        href: ./editor/walkthroughs/taggers.md  
+        href: ./editor/walkthroughs/taggers.md
+      - name: Extending Visual Studio editor with new classification tagger
+        href: ./editor/walkthroughs/classification.md
   - name: Editor concepts
     href: ./editor/editor-concepts.md
   - name: Editor RPC

docs/extensibility/visualstudio.extensibility/visualstudio-extensibility.md

@@ -107,6 +107,7 @@ You can find a Visual Studio solution that contains all samples at [Samples.sln]
 | [RegexMatchDebugVisualizer](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/RegexMatchDebugVisualizer) | Shows how to use [Remote UI](./inside-the-sdk/remote-ui.md) to create a [Debugger Visualizer](./debugger-visualizer/debugger-visualizers.md) to visualize regular expression matches that will launch in a modal dialog window. |
 | [MemoryStreamDebugVisualizer](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/MemoryStreamDebugVisualizer) | Shows how to create a [Debugger Visualizer](./debugger-visualizer/debugger-visualizers.md) to visualize MemoryStream objects that launches in a non-modal tool window. |
 | [RustLanguageServiceProvider](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/RustLanguageServerProvider) | Shows how to create a Rust language server provider extension that adds Intellisense and tooltips when a rust file is opened. |
+| [CompositeExtension](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/CompositeExtension) | Shows how to create an extension with in-proc and out-of-proc components that communicate using brokered services. . |
 
 ## Experimental APIs and Breaking Changes
 Starting with our 17.9 release, we're ready to label most of our APIs as stable. That is, we don't plan to make any breaking changes to these APIs. Any breaking changes, such as those prompted by user feedback on usability, will be formally communicated in advance on our [breaking changes](https://github.com/microsoft/VSExtensibility/blob/main/docs/breaking_changes.md) page with ample notice.