Merge pull request #10795 from MicrosoftDocs/main638847686543320976sync_temp

For protected branch, push strategy should use PR and merge to target branch method to work around git push error

Author: learn-build-service-prod[bot]

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

@@ -1,6 +1,6 @@
 ---
-title: Editor extensibility concepts
-description: An overview of the object model for editor-based extensions
+title: Editor Extensibility Concepts
+description: An overview of the object model for editor-based extensions.
 ms.topic: conceptual
 ms.date: 3/31/2023
 ms.author: maiak
@@ -12,59 +12,57 @@ ms.subservice: extensibility-integration
 
 # Editor extensibility concepts
 
-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).
+This article describes the extensibility object model that represents the Visual Studio editor and the text document that's 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 [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.
+The extensibility object model for the Visual Studio editor consists 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. The article also introduces [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
 
-[ITextViewSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextviewsnapshot) contains the URI and version information necessary to acquire an [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) as well as 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 will never change after it is created.
-- You can use `ITextViewSnapshot.GetTextDocumentAsync()` to get the content from the document. Calling this method is expensive and only should be done if you need the document content.
-- `ITextViewSnapshot` can't be changed directly. All changes are requested via mutation. See [Make changes in a text document from an extension](./walkthroughs/editing-text.md).
+- 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` 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
 
-[ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) 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 will never change after it is created.
-- `ITextDocumentSnapshot` can't be changed directly. All changes are requested via mutation. See [Make changes in a text document from an extension](./walkthroughs/editing-text.md).
+- This object is immutable and never changes after it's created.
+- 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.
 
-Best Practices:
+### Best practices
 
-- 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 `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 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.
+- Use position and range to represent substrings in the document without expending resources by copying or allocating strings. Most APIs operate in terms of these primitives.
+- 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) class references large data structures that might consume memory if an old-enough version is stored. The 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
 
-[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.
+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
 
-[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.
+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
 
-`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.
+The `TextPosition` and `TextRange` classes 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
 
-[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.).
+[Taggers](./walkthroughs/taggers.md) are used to associate data (a [tag](/dotnet/api/microsoft.visualstudio.extensibility.editor.itag)) with spans of text. Other Visual Studio features (for example, [CodeLens](./walkthroughs/codelens.md) and [classification](./walkthroughs/classification.md)) consume such data.
 
 ## Related content
 
-Review sample code for a simple editor-based extension:
-
-- [DocumentSelectorSample](https://github.com/Microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/DocumentSelectorSample/)
+- Review sample code for a simple editor-based extension in [DocumentSelectorSample](https://github.com/Microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/DocumentSelectorSample/).

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

@@ -1,5 +1,5 @@
 ---
-title: Editor remote procedure calls (RPC)
+title: Editor Remote Procedure Calls (RPC)
 description: Learn about the RPC protocol for editor-based extensions.
 ms.date: 3/31/2023
 ms.topic: conceptual
@@ -12,21 +12,21 @@ ms.subservice: extensibility-integration
 
 # Editor RPC support
 
-Since the new Visual Studio extensibility model is entirely in a separate process, and communication between the extension process and the Visual Studio process occurs through a stream, all APIs have to at some level operate with serializable data types. Typically, extensions can ignore these implementation details. In some scenarios, an extension may need to interface directly with RPC services acquired from `this.Extensibility.ServiceBroker`.
+The new Visual Studio extensibility model is entirely in a separate process, and communication between the extension process and the Visual Studio process occurs through a stream. As a result, all APIs have to operate at some level with serializable data types. Typically, extensions can ignore these implementation details. In some scenarios, an extension might need to interface directly with remote procedure call (RPC) services acquired from `this.Extensibility.ServiceBroker`.
 
 ## Serializable RPC types
 
 To facilitate interactions with RPC services, the object model exposes [RpcContract](/dotnet/api/microsoft.visualstudio.extensibility.editor.selection.rpccontract) properties on most core types, and the following serializable RPC types:
 
-- `VersionedTextDocumentRange` - 1:1 serializable version of `Span`, which you can access through the `RpcContract` property. This type should be used in most RPC contracts between processes.
-- `VersionedTextDocumentPosition` - 1:1 serializable version of `Position`, which you can access through the `RpcContract` property. This type should be used in most RPC contracts between processes.
-- `Range` - Serializable version of Span, omitting the Uri and version number.
-- `Microsoft.VisualStudio.RpcContracts.Utilities.Position` - Serializable version of `Position`, omitting the Uri and version number.
-- `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.
+- `VersionedTextDocumentRange`: 1:1 serializable version of `Span`, which you can access through the `RpcContract` property. Use this type in most RPC contracts between processes.
+- `VersionedTextDocumentPosition`: 1:1 serializable version of `Position`, which you can access through the `RpcContract` property. Use this type in most RPC contracts between processes.
+- `Range`: Serializable version of Span, which omits the URI and version number.
+- `Microsoft.VisualStudio.RpcContracts.Utilities.Position`: Serializable version of `Position`, which omits the URI and version number.
+- `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, making for a smaller serializable representation. This type should be used in RPC contracts that contain lots of span/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 the [IEditorHostService](/dotnet/api/microsoft.visualstudio.extensibility.editor.ieditorhostservice). `IEditorHostService` interfaces with extension-local copies of the text buffer, and manages 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
 
-Learn more about Remote UI, the RPC model used in VS.Extensibilty at [Remote UI](../inside-the-sdk/remote-ui.md).
+- To learn more about Remote UI, the RPC model used in `VisualStudio.Extensibility`, see [Remote UI](../inside-the-sdk/remote-ui.md).