Merge main into live

.github/policies/disallow-edits.yml

@@ -10,158 +10,50 @@ configuration:
           - payloadType: Pull_Request
           - isAction:
               action: Opened
+          - or:
+              - filesMatchPattern:
+                  pattern: xml/Microsoft.Extensions*/*
+                  matchAny: true
+                  excludedFiles:
+                    - xml/Microsoft.Extensions.FileSystemGlobbing/*
+                    - xml/Microsoft.Extensions.FileSystemGlobbing.Abstractions/*
+                    - xml/Microsoft.Extensions.FileSystemGlobbing.Internal*/*
+              - filesMatchPattern:
+                  matchAny: true
+                  pattern: xml/System.Composition/*
+              - filesMatchPattern:
+                  matchAny: true
+                  pattern: xml/System.Formats.Cbor/*
+              - filesMatchPattern:
+                  matchAny: true
+                  pattern: xml/System.Formats.Nrbf/*
+              - filesMatchPattern:
+                  matchAny: true
+                  pattern: xml/System.Net.ServerSentEvents/*
+              - filesMatchPattern:
+                  matchAny: true
+                  pattern: xml/System.Numerics.Tensors/*
+              - filesMatchPattern:
+                  matchAny: true
+                  pattern: xml/System.Speech/*
+              - filesMatchPattern:
+                  matchAny: true
+                  pattern: xml/System.Runtime.Serialization/ISerializationCodeDomSurrogateProvider.xml
+              - filesMatchPattern:
+                  matchAny: true
+                  pattern: xml/System.Runtime.Serialization/ImportOptions.xml
+              - filesMatchPattern:
+                  matchAny: true
+                  pattern: xml/System.Runtime.Serialization/XsdDataContractExporter.xml
         then:
-          - if:
-              - includesModifiedFile:
-                  file: xml/Microsoft.Extensions*/*
-                    # TODO - These files do use this repo as source-of-truth - how to exclude them?
-                    # - xml/Microsoft.Extensions.FileSystemGlobbing/*
-                    # - xml/Microsoft.Extensions.FileSystemGlobbing.Abstractions/*
-                    # - xml/Microsoft.Extensions.FileSystemGlobbing.Internal*/*
-            then:
-              - addReply:
-                  reply: >-
-                    @${issueAuthor} - This PR edits one or more files whose 'source of truth' for documentation is not in this repo. Please make documentation updates for 'Microsoft.Extensions' in the /// comments in the dotnet/runtime or dotnet/extensions repo instead.
-              - if:
-                  - or:
-                      - activitySenderHasPermission:
-                          permission: None
-                      - activitySenderHasPermission:
-                          permission: Read
-                then:
-                  - closePullRequest
-          - if:
-              - includesModifiedFile:
-                  file: xml/System.Composition/*
-            then:
-              - addReply:
-                  reply: >-
-                    @${issueAuthor} - This PR edits one or more files whose 'source of truth' for documentation is not in this repo. Please make documentation updates for 'System.Composition' in the /// comments in the dotnet/runtime repo instead.
-              - if:
-                  - or:
-                      - activitySenderHasPermission:
-                          permission: None
-                      - activitySenderHasPermission:
-                          permission: Read
-                then:
-                  - closePullRequest
-          - if:
-              - includesModifiedFile:
-                  file: xml/System.Formats.Cbor/*
-            then:
-              - addReply:
-                  reply: >-
-                    @${issueAuthor} - This PR edits one or more files whose 'source of truth' for documentation is not in this repo. Please make documentation updates for 'System.Formats.Cbor' in the /// comments in the dotnet/runtime repo instead.
-              - if:
-                  - or:
-                      - activitySenderHasPermission:
-                          permission: None
-                      - activitySenderHasPermission:
-                          permission: Read
-                then:
-                  - closePullRequest
-          - if:
-              - includesModifiedFile:
-                  file: xml/System.Formats.Nrbf/*
-            then:
-              - addReply:
-                  reply: >-
-                    @${issueAuthor} - This PR edits one or more files whose 'source of truth' for documentation is not in this repo. Please make documentation updates for 'System.Formats.Nrbf' in the /// comments in the dotnet/runtime repo instead.
-              - if:
-                  - or:
-                      - activitySenderHasPermission:
-                          permission: None
-                      - activitySenderHasPermission:
-                          permission: Read
-                then:
-                  - closePullRequest
-          - if:
-              - includesModifiedFile:
-                  file: xml/System.Net.ServerSentEvents/*
-            then:
-              - addReply:
-                  reply: >-
-                    @${issueAuthor} - This PR edits one or more files whose 'source of truth' for documentation is not in this repo. Please make documentation updates for 'System.Net.ServerSentEvents' in the /// comments in the dotnet/runtime repo instead.
-              - if:
-                  - or:
-                      - activitySenderHasPermission:
-                          permission: None
-                      - activitySenderHasPermission:
-                          permission: Read
-                then:
-                  - closePullRequest
-          - if:
-              - includesModifiedFile:
-                  file: xml/System.Numerics.Tensors/*
-            then:
-              - addReply:
-                  reply: >-
-                    @${issueAuthor} - This PR edits one or more files whose 'source of truth' for documentation is not in this repo. Please make documentation updates for 'System.Numerics.Tensors' in the /// comments in the dotnet/runtime repo instead.
-              - if:
-                  - or:
-                      - activitySenderHasPermission:
-                          permission: None
-                      - activitySenderHasPermission:
-                          permission: Read
-                then:
-                  - closePullRequest
-          - if:
-              - includesModifiedFile:
-                  file: xml/System.Speech/*
-            then:
-              - addReply:
-                  reply: >-
-                    @${issueAuthor} - This PR edits one or more files whose 'source of truth' for documentation is not in this repo. Please make documentation updates for 'System.Speech' in the /// comments in the dotnet/runtime repo instead.
-              - if:
-                  - or:
-                      - activitySenderHasPermission:
-                          permission: None
-                      - activitySenderHasPermission:
-                          permission: Read
-                then:
-                  - closePullRequest
-          - if:
-              - includesModifiedFile:
-                  file: xml/System.Runtime.Serialization/ISerializationCodeDomSurrogateProvider.xml
-            then:
-              - addReply:
-                  reply: >-
-                    @${issueAuthor} - This PR edits one or more files whose 'source of truth' for documentation is not in this repo. Please make documentation updates for 'ISerializationCodeDomSurrogateProvider' in the /// comments in the dotnet/runtime repo instead.
-              - if:
-                  - or:
-                      - activitySenderHasPermission:
-                          permission: None
-                      - activitySenderHasPermission:
-                          permission: Read
-                then:
-                  - closePullRequest
-          - if:
-              - includesModifiedFile:
-                  file: xml/System.Runtime.Serialization/ImportOptions.xml
-            then:
-              - addReply:
-                  reply: >-
-                    @${issueAuthor} - This PR edits one or more files whose 'source of truth' for documentation is not in this repo. Please make documentation updates for 'ImportOptions' in the /// comments in the dotnet/runtime repo instead.
-              - if:
-                  - or:
-                      - activitySenderHasPermission:
-                          permission: None
-                      - activitySenderHasPermission:
-                          permission: Read
-                then:
-                  - closePullRequest
-          - if:
-              - includesModifiedFile:
-                  file: xml/System.Runtime.Serialization/XsdDataContractExporter.xml
-            then:
-              - addReply:
-                  reply: >-
-                    @${issueAuthor} - This PR edits one or more files whose 'source of truth' for documentation is not in this repo. Please make documentation updates for 'XsdDataContractExporter' in the /// comments in the dotnet/runtime repo instead.
-              - if:
-                  - or:
-                      - activitySenderHasPermission:
-                          permission: None
-                      - activitySenderHasPermission:
-                          permission: Read
-                then:
-                  - closePullRequest
+            - addReply:
+                reply: >-
+                  @${issueAuthor} - This PR edits one or more files whose 'source of truth' for documentation is not in this repo. Please make documentation updates in the /// comments in the dotnet/runtime repo (or dotnet/extensions repo) instead.
+            - if:
+                - or:
+                    - activitySenderHasPermission:
+                        permission: None
+                    - activitySenderHasPermission:
+                        permission: Read
+              then:
+                - closePullRequest

xml/System.IO/Directory.xml

@@ -4055,13 +4055,13 @@ The returned collection is not cached. Each call to the <xref:System.Collections
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>Retrieves the names of the logical drives on this computer in the form "&lt;drive letter&gt;:\\".</summary>
-        <returns>The logical drives on this computer.</returns>
+        <summary>Retrieves the names of the logical drives on this computer.</summary>
+        <returns>An array of strings representing the logical drive names.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- GetLogicalDrives returns all of the accessible drives on a particular machine, including the floppy drive and any optical drives.
+ On Windows, `GetLogicalDrives` returns the names of all accessible drives on a particular machine, including any optical drives or removable media devices, in the form "\<drive letter\>:\\" (for example, "C:\\"). On Unix, it returns the paths of all filesystem mount points mounted on a particular machine (for example, "/home/user", "/media/usb").
 
  For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks).
 

xml/System.Numerics/Vector2.xml

@@ -663,7 +663,7 @@
       <Docs>
         <param name="values">The span of elements to assign to the vector.</param>
         <summary>Constructs a vector from the given <see cref="T:System.ReadOnlySpan`1" />. The span must contain at least 2 elements.</summary>
-        <returns>To be added.</returns>
+        <returns>A new <see cref="T:System.Numerics.Vector2" /> whose elements have the specified values.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/System.Numerics/Vector3.xml

@@ -709,7 +709,7 @@
       <Docs>
         <param name="values">The span of elements to assign to the vector.</param>
         <summary>Constructs a vector from the given <see cref="T:System.ReadOnlySpan`1" />. The span must contain at least 3 elements.</summary>
-        <returns>To be added.</returns>
+        <returns>A new <see cref="T:System.Numerics.Vector3" /> whose elements have the specified values.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/System.Numerics/Vector4.xml

@@ -757,7 +757,7 @@
       <Docs>
         <param name="values">The span of elements to assign to the vector.</param>
         <summary>Constructs a vector from the given <see cref="T:System.ReadOnlySpan`1" />. The span must contain at least 4 elements.</summary>
-        <returns>To be added.</returns>
+        <returns>A new <see cref="T:System.Numerics.Vector4" /> whose elements have the specified values.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/System.Reflection.Emit/AssemblyBuilder.xml

@@ -76,7 +76,18 @@
   </Attributes>
   <Docs>
     <summary>Defines and represents a dynamic assembly.</summary>
-    <remarks>For more information about this API, see <see href="/dotnet/fundamentals/runtime-libraries/system-reflection-emit-assemblybuilder">Supplemental API remarks for AssemblyBuilder</see>.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information about this API, see [Supplemental API remarks for AssemblyBuilder](/dotnet/fundamentals/runtime-libraries/system-reflection-emit-assemblybuilder).
+
+> [!WARNING]
+> `AssemblyBuilder` APIs require a fully trusted environment with trusted input, similar to other technologies such as compilers. There are no restrictions other than basic validation for generated IL that the `AssemblyBuilder` can contain. That includes validation for member name, count, and associated metadata, such as custom attributes.
+]]>
+      </format>
+    </remarks>
     <example>
       <format type="text/markdown"><![CDATA[
 The following code example shows how to define and use a dynamic assembly. The example assembly contains one type, `MyDynamicType`, that has a private field, a property that gets and sets the private field, constructors that initialize the private field, and a method that multiplies a user-supplied number by the private field value and returns the result.

xml/System.Reflection.Emit/ILGenerator.xml

@@ -84,6 +84,15 @@
 
  MSIL is used as input to a just-in-time (JIT) compiler.
 
+> [!WARNING]
+> There are no restrictions, other than basic validation, for ILGenerator APIs that produce method IL. If untrusted input is used for producing IL:
+>
+> - IL and metadata can contain secrets provided by the consumer.
+> - IL can be invalid, such as not having balanced push versus pop opcodes, or invalid operands for a given opcode.
+> - IL can contain any code that might, for example, deadlock, have infinite stack recursion, or have an infinite loop.
+> - IL can load and execute code on any other reachable assembly.
+>
+> Such code can do whatever it wishes when the method is loaded and executed. To protect against such vulnerabilities, `ILGenerator` requires a fully trusted environment with trusted input.
  ]]></format>
     </remarks>
   </Docs>

xml/System.Reflection.Emit/PersistedAssemblyBuilder.xml

@@ -25,7 +25,17 @@
   </Attributes>
   <Docs>
     <summary>Provides an AssemblyBuilder implementation that can persist assembly to a disk or stream.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+For more information about this API, see [Persisted dynamic assemblies in .NET](/dotnet/fundamentals/runtime-libraries/system-reflection-emit-persistedassemblybuilder).
+
+> [!WARNING]
+> `PersistedAssemblyBuilder` APIs require a fully trusted environment with trusted input, similar to other technologies such as compilers. There are no restrictions other than basic validation for generated IL that the `AssemblyBuilder` can contain. That includes validation for member name, count, and associated metadata, such as custom attributes.
+]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">

xml/System/Environment.xml

@@ -1421,11 +1421,14 @@ The following example creates environment variables for the <xref:System.Environ
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>Returns an array of string containing the names of the logical drives on the current computer.</summary>
-        <returns>An array of strings where each element contains the name of a logical drive. For example, if the computer's hard drive is the first logical drive, the first element returned is "C:\\".</returns>
+        <summary>Retrieves the names of the logical drives on this computer.</summary>
+        <returns>An array of strings representing the logical drive names.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
+## Remarks
+ On Windows, `GetLogicalDrives` returns the names of all accessible drives on a particular machine, including any optical drives or removable media devices, in the form "\<drive letter\>:\\" (for example, "C:\\"). On Unix, it returns the paths of all filesystem mount points mounted on a particular machine (for example, "/home/user", "/media/usb").
+
 ## Examples
  The following example shows how to display the logical drives of the current computer using the <xref:System.Environment.GetLogicalDrives%2A> method.