edit pass: visual-studio-editor

Author: paulth1

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

@@ -18,18 +18,18 @@ The Visual Studio editor extensibility object model is composed of a few integra
 
 ## ITextViewSnapshot
 
-The [ITextViewSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextviewsnapshot) parameter contains the URI and version information necessary to acquire an [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) parameter and some properties of the text view, such as selections.
+The [ITextViewSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextviewsnapshot) class contains the URI and version information necessary to acquire an [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) class and some properties of the text view, such as selections.
 
 - This object is immutable and never changes after it's created.
 - You can use `ITextViewSnapshot.GetTextDocumentAsync()` to get the content from the document. Calling this method is expensive, and you should do it only if you need the document content.
-- The `ITextViewSnapshot` parameter can't be changed directly. All changes are requested via mutation. For more information, see [Make changes in a text document from an extension](./walkthroughs/editing-text.md).
+- The `ITextViewSnapshot` class can't be changed directly. All changes are requested via mutation. For more information, see [Make changes in a text document from an extension](./walkthroughs/editing-text.md).
 
 ## ITextDocumentSnapshot
 
-The [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) parameter contains the content of the text document from a point in time or version.
+The [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) class contains the content of the text document from a point in time or version.
 
 - This object is immutable and never changes after it's created.
-- The `ITextDocumentSnapshot` parameter can't be changed directly. All changes are requested via mutation. For more information, see [Make changes in a text document from an extension](./walkthroughs/editing-text.md).
+- The `ITextDocumentSnapshot` class can't be changed directly. All changes are requested via mutation. For more information, see [Make changes in a text document from an extension](./walkthroughs/editing-text.md).
 
 If you're familiar with legacy Visual Studio extensions, [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) is almost the same as
 [ITextSnapshot](/dotnet/api/microsoft.visualstudio.text.itextsnapshot) and supports most of the same methods for accessing the text.
@@ -40,24 +40,24 @@ If you're familiar with legacy Visual Studio extensions, [ITextDocumentSnapshot]
 - 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 `Range` to avoid creating a large throwaway string from the entire line or document.
 - Avoid the assumption that lines or documents are short. Many languages minify into huge lines or consume large files.
-   - The [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) parameter references large data structures that might 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 that the old `ITextDocumentSnapshot` version can be collected as garbage.
+   - The [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) class references large data structures that might 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 that the old `ITextDocumentSnapshot` version can be garbage collected.
 
 ## Position
 
-The [TextPosition](/dotnet/api/microsoft.visualstudio.extensibility.editor.textposition) parameter 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) parameter that it came from and supports `GetChar()` to get the character directly at that point.
+The [TextPosition](/dotnet/api/microsoft.visualstudio.extensibility.editor.textposition) class 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) class that it came from and supports `GetChar()` to get the character directly at that point.
 
 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.
 
 ## Range
 
-The [TextRange](/dotnet/api/microsoft.visualstudio.extensibility.editor.textrange) parameter represents a contiguous substring of characters within an [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) parameter. As opposed to a string created with `string.Substring()` or `ITextDocumentSnapshot.CopyToString()`, creating a `TextRange` parameter doesn't require any allocations or extra memory. Later, you can call [CopyToString()](/dotnet/api/microsoft.visualstudio.extensibility.editor.textextensions.copytostring) to realize it into a string in a deferred fashion.
+The [TextRange](/dotnet/api/microsoft.visualstudio.extensibility.editor.textrange) class represents a contiguous substring of characters within an [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) class. As opposed to a string created with `string.Substring()` or `ITextDocumentSnapshot.CopyToString()`, creating a `TextRange` class doesn't require any allocations or extra memory. Later, you can 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, `TextRange` is almost the same as
 [SnapshotSpan](/dotnet/api/microsoft.visualstudio.text.snapshotSpan) and supports most of the same methods.
 
 ## Tracking modes
 
-The `TextPosition` and `TextRange` parameters are associated with a specific `ITextDocumentSnapshot` parameter, which is the state of the document at a specific time. You can use the `TranslateTo` methods to translate such positions and ranges to a different snapshot. Such translation takes into account any text that was added or removed before, after (or, in the case of ranges, in the middle of) the position or range. When any of these 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.
+The `TextPosition` and `TextRange` classs are associated with a specific `ITextDocumentSnapshot` class, which is the state of the document at a specific time. You can use the `TranslateTo` methods to translate such positions and ranges to a different snapshot. Such translation takes into account any text that was added or removed before, after (or, in the case of ranges, in the middle of) the position or range. When any of these 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
 

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

@@ -25,7 +25,7 @@ To facilitate interactions with RPC services, the object model exposes [RpcContr
 - `TextView`: 1:1 serialized form of `ITextView`, which you can access through the `RpcContract` property.
 - `TextDocument`: 1:1 serialized form of `ITextDocument` through the `RpcContract` property.
 
-As opposed to `VersionedTextDocumentRange` and `VersionedTextDocumentPosition`, `Range` and `Microsoft.VisualStudio.RpcContracts.Utilities.Position` omit the URI and document version, which makes for a smaller serializable representation. Use this type in RPC contracts that contain lots of span or range equivalents that need to reduce their payload size for performance. These RPC contracts need to pass the document URI and version for the spans or range to be instantiated into `Span` and `Position` objects by [IEditorHostService](/dotnet/api/microsoft.visualstudio.extensibility.editor.ieditorhostservice). The `IEditorHostService` parameter interfaces with extension-local copies of the text buffer and manages the opening and closing of documents described by the RPC types.
+As opposed to `VersionedTextDocumentRange` and `VersionedTextDocumentPosition`, `Range` and `Microsoft.VisualStudio.RpcContracts.Utilities.Position` omit the URI and document version, which makes for a smaller serializable representation. Use this type in RPC contracts that contain lots of span or range equivalents that need to reduce their payload size for performance. These RPC contracts need to pass the document URI and version for the spans or range to be instantiated into `Span` and `Position` objects by [IEditorHostService](/dotnet/api/microsoft.visualstudio.extensibility.editor.ieditorhostservice). The `IEditorHostService` interfaces with extension-local copies of the text buffer and manages the opening and closing of documents described by the RPC types.
 
 ## Related content
 

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

@@ -27,7 +27,7 @@ The following sections summarize the high-level editor extensibility scenarios t
 
 The most fundamental extensibility point for the Visual Studio editor is to manipulate text, either by reading the text in the editor or editing the text. These scenarios are core to any editor-based extensions. For example, to provide diagnostics information, such as warnings or errors, the extension must read the code in the editor and then interpret it. An extension also needs a way to detect when the text in the editor changed, if a new file opened, or if an open file closed.
 
-For a walkthrough of how to make read-text and track-text changes by using `VisualStudio.Extensibility`, see [Work with text in the editor](./walkthroughs/working-with-text.md).
+For a walkthrough of how to make read text and track text changes by using `VisualStudio.Extensibility`, see [Work with text in the editor](./walkthroughs/working-with-text.md).
 
 ## Make edits to text in the editor
 

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

@@ -14,10 +14,10 @@ ms.subservice: extensibility-integration
 
 Extensions can contribute new taggers to Visual Studio. Taggers are used to associate data with ranges of text. Then other Visual Studio features (for example, [CodeLens](./codelens.md)) can consume the data that the taggers provided.
 
-`VisualStudio.Extensibility` supports tag types that are only provided by the [Microsoft.VisualStudio.Extensibility](https://www.nuget.org/packages/Microsoft.VisualStudio.Extensibility) package and implement the `Microsoft.VisualStudio.Extensibility.Editor.ITag` interface:
+`VisualStudio.Extensibility` supports tag types that are only provided by the [Microsoft.VisualStudio.Extensibility](https://www.nuget.org/packages/Microsoft.VisualStudio.Extensibility) package and implement the [ITag](/dotnet/api/microsoft.visualstudio.extensibility.editor.itag) interface:
 
-- `CodeLensTag` is used together with an [ICodeLensProvider](./codelens.md) to add CodeLens to documents.
-- `TextMarkerTag` is used to highlight portions of documents. `VisualStudio.Extensibility` doesn't support defining new Text Marker styles yet. For now, you can use only styles that are built into Visual Studio or provided by a Visual Studio SDK extension. (A [VisualStudio.Extensibility in-proc extension](../../get-started/in-proc-extensions.md) can create Text Marker styles with an `[Export(typeof(EditorFormatDefinition))]` parameter.)
+- `CodeLensTag` is used together with an [ICodeLensProvider](./codelens.md) to add CodeLens to documents. `TextMarkerTag` and `ClassificationTag` can also be linked to the API documents.
+- `TextMarkerTag` is used to highlight portions of documents. `VisualStudio.Extensibility` doesn't support defining new Text Marker styles yet. For now, you can use only styles that are built into Visual Studio or provided by a Visual Studio SDK extension. (A [VisualStudio.Extensibility in-proc extension](../../get-started/in-proc-extensions.md) can create Text Marker styles with `[Export(typeof(EditorFormatDefinition))]`.)
 - `ClassificationTag` is used to classify a document's syntax, which allows 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/editor/walkthroughs/working-with-text.md

@@ -64,7 +64,7 @@ When you run your extension, you should see:
 - [ITextViewOpenClosedListener.TextViewClosedAsync](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextviewopenclosedlistener.textviewclosedasync) called any time that a user closes a text view.
 - [ITextViewChangedListener.TextViewChangedAsync](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextviewchangedlistener.textviewchangedasync) called any time that a user makes a text change to a text document that a text view displays.
 
-Each of these methods is passed an [ITextViewSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextviewsnapshot) parameter that contains the state of the text view and text document at the time that the user invoked the action and a `CancellationToken` that has `IsCancellationRequested == true` when the integrated development environment (IDE) wants to cancel a pending action.
+Each of these methods is passed an [ITextViewSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextviewsnapshot) class that contains the state of the text view and text document at the time that the user invoked the action and a `CancellationToken` that has `IsCancellationRequested == true` when the integrated development environment (IDE) wants to cancel a pending action.
 
 ## Define when your extension is relevant
 
@@ -92,7 +92,7 @@ Document types are hierarchical. That is, C# and C++ both descend from `code`, s
 
 You can define a new document type, for example, to support a custom code language, by adding a static [DocumentTypeConfiguration](/dotnet/api/microsoft.visualstudio.extensibility.editor.documenttypeconfiguration) property to any class in the extension project. Then mark the property with the [`VisualStudioContribution`](/dotnet/api/microsoft.visualstudio.extensibility.visualstudiocontributionattribute) attribute.
 
-You can use the `DocumentTypeConfiguration` parameter to define a new document type, specify that it inherits one or more other document types, and specify one or more file extensions that are used to identify the file type.
+You can use `DocumentTypeConfiguration` to define a new document type, specify that it inherits one or more other document types, and specify one or more file extensions that are used to identify the file type.
 
 ```csharp
 using Microsoft.VisualStudio.Extensibility.Editor;
@@ -144,7 +144,7 @@ public sealed class TextViewOperationListener
     };
 ```
 
-The `pattern` parameter represents a glob pattern that's matched on the absolute path of the document.
+The pattern represents a glob pattern that's matched on the absolute path of the document.
 
 Glob patterns can have the following syntax:
 
@@ -167,10 +167,10 @@ EditorExtensibility editorService = this.Extensibility.Editor();
 
 ### Access editor state within a command
 
-The `ExecuteCommandAsync()` parameter in each `Command` parameter is passed an `IClientContext` parameter that contains a snapshot of the state of the IDE at the time the command was invoked. You can access the active document via the [`ITextViewSnapshot`](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextviewsnapshot) interface, which you get from the [`EditorExtensibility`](/dotnet/api/microsoft.visualstudio.extensibility.editor.editorextensibility) object by calling the asynchronous method [`GetActiveTextViewAsync`](/dotnet/api/microsoft.visualstudio.extensibility.editor.editorextensibility.getactivetextviewasync).
+The `ExecuteCommandAsync()` method in each `Command` is passed `IClientContext` that contains a snapshot of the state of the IDE at the time the command was invoked. You can access the active document via the [`ITextViewSnapshot`](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextviewsnapshot) interface, which you get from the [`EditorExtensibility`](/dotnet/api/microsoft.visualstudio.extensibility.editor.editorextensibility) object by calling the asynchronous method [`GetActiveTextViewAsync`](/dotnet/api/microsoft.visualstudio.extensibility.editor.editorextensibility.getactivetextviewasync).
 
 ```csharp
 using ITextViewSnapshot textView = await this.Extensibility.Editor().GetActiveTextViewAsync(clientContext, cancellationToken);
 ```
 
-When you have the `ITextViewSnapshot` parameter, you can access the editor state. The [`ITextViewSnapshot`](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextviewsnapshot) parameter is an immutable view of the editor state at a point in time, so you need to use the other interfaces in the [Editor object model](./../editor-concepts.md) to make edits.
+When you have the `ITextViewSnapshot` class, you can access the editor state. The [`ITextViewSnapshot`](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextviewsnapshot) class is an immutable view of the editor state at a point in time, so you need to use the other interfaces in the [Editor object model](./../editor-concepts.md) to make edits.