dotnet · T-Gro · Aug 7, 2026
@@ -8,3 +8,7 @@
 ### Added
 
 * `Async.RunSynchronouslyImmediate`: runs work on the calling thread until the first asynchronous suspension (as opposed to `RunSynchronously`, which immediately offloads if not on a background and/or threadpool thread). ([Issue #1042](https://github.com/fsharp/fslang-suggestions/issues/1042), [PR #19804](https://github.com/dotnet/fsharp/pull/19804))
+
+### Changed
+
+* Deduplicate repeated XML documentation (sort stability/complexity, `Parallel.For`, dynamic entry points) via the compile-time `<include>` tag; generated FSharp.Core.xml is unchanged. ([PR #20231](https://github.com/dotnet/fsharp/pull/20231))
@@ -2432,8 +2432,7 @@ module Array =
 
     /// <summary>Sorts the elements of an array, returning a new array. Elements are compared using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>. </summary>
     ///
-    /// <remarks>This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved.
-    /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>. This is an O(n log n) operation, where n is the length of the array.</remarks>
+    /// <include file="xmldoc/sort.xml" path="/sort/arrayUnstable/*"/>
     ///
     /// <param name="array">The input array.</param>
     ///
@@ -2455,8 +2454,7 @@ module Array =
     /// <summary>Sorts the elements of an array, using the given projection for the keys and returning a new array.
     /// Elements are compared using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>.</summary>
     ///
-    /// <remarks>This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved.
-    /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>. This is an O(n log n) operation, where n is the length of the array.</remarks>
+    /// <include file="xmldoc/sort.xml" path="/sort/arrayUnstable/*"/>
     ///
     /// <param name="projection">The function to transform array elements into the type that is compared.</param>
     /// <param name="array">The input array.</param>
@@ -2478,8 +2476,7 @@ module Array =
 
     /// <summary>Sorts the elements of an array, using the given comparison function as the order, returning a new array.</summary>
     ///
-    /// <remarks>This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved.
-    /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>. This is an O(n log n) operation, where n is the length of the array.</remarks>
+    /// <include file="xmldoc/sort.xml" path="/sort/arrayUnstable/*"/>
     ///
     /// <param name="comparer">The function to compare pairs of array elements.</param>
     /// <param name="array">The input array.</param>
@@ -2507,8 +2504,7 @@ module Array =
     /// <summary>Sorts the elements of an array by mutating the array in-place, using the given projection for the keys.
     /// Elements are compared using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>.</summary>
     ///
-    /// <remarks>This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved.
-    /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>. This is an O(n log n) operation, modifying the array in place.</remarks>
+    /// <include file="xmldoc/sort.xml" path="/sort/arrayUnstableInPlace/*"/>
     ///
     /// <param name="projection">The function to transform array elements into the type that is compared.</param>
     /// <param name="array">The input array.</param>
@@ -2597,8 +2593,7 @@ module Array =
 
     /// <summary>Sorts the elements of an array, in descending order, returning a new array. Elements are compared using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>. </summary>
     ///
-    /// <remarks>This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved.
-    /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>. This is an O(n log n) operation, where n is the length of the array.</remarks>
+    /// <include file="xmldoc/sort.xml" path="/sort/arrayUnstable/*"/>
     ///
     /// <param name="array">The input array.</param>
     ///
@@ -2618,8 +2613,7 @@ module Array =
     /// <summary>Sorts the elements of an array, in descending order, using the given projection for the keys and returning a new array.
     /// Elements are compared using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>.</summary>
     ///
-    /// <remarks>This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved.
-    /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>. This is an O(n log n) operation, where n is the length of the array.</remarks>
+    /// <include file="xmldoc/sort.xml" path="/sort/arrayUnstable/*"/>
     ///
     /// <param name="projection">The function to transform array elements into the type that is compared.</param>
     /// <param name="array">The input array.</param>
@@ -4123,8 +4117,7 @@ module Array =
         /// the array comprised of the results <c>x</c> for each element where
         /// the function returns <c>Some(x)</c>.</summary>
         ///
-        /// <remarks>Performs the operation in parallel using <see cref="M:System.Threading.Tasks.Parallel.For" />.
-        /// The order in which the given function is applied to elements of the input array is not specified. This is an O(n) operation, where n is the length of the array.</remarks>
+        /// <include file="xmldoc/parallel.xml" path="/parallel/arrayUnordered/*"/>
         ///
         /// <param name="chooser">The function to generate options from the elements.</param>
         /// <param name="array">The input array.</param>
@@ -4190,8 +4183,7 @@ module Array =
         /// <summary>Build a new array whose elements are the results of applying the given function
         /// to each of the elements of the array.</summary>
         ///
-        /// <remarks>Performs the operation in parallel using <see cref="M:System.Threading.Tasks.Parallel.For" />.
-        /// The order in which the given function is applied to elements of the input array is not specified. This is an O(n) operation, where n is the length of the array.</remarks>
+        /// <include file="xmldoc/parallel.xml" path="/parallel/arrayUnordered/*"/>
         ///
         /// <param name="mapping"></param>
         /// <param name="array">The input array.</param>
@@ -4215,8 +4207,7 @@ module Array =
         /// to each of the elements of the array. The integer index passed to the
         /// function indicates the index of element being transformed.</summary>
         ///
-        /// <remarks>Performs the operation in parallel using <see cref="M:System.Threading.Tasks.Parallel.For" />.
-        /// The order in which the given function is applied to elements of the input array is not specified. This is an O(n) operation, where n is the length of the array.</remarks>
+        /// <include file="xmldoc/parallel.xml" path="/parallel/arrayUnordered/*"/>
         ///
         /// <param name="mapping"></param>
         /// <param name="array">The input array.</param>
@@ -4264,8 +4255,7 @@ module Array =
 
         /// <summary>Apply the given function to each element of the array. </summary>
         ///
-        /// <remarks>Performs the operation in parallel using <see cref="M:System.Threading.Tasks.Parallel.For" />.
-        /// The order in which the given function is applied to elements of the input array is not specified. This is an O(n) operation, where n is the length of the array.</remarks>
+        /// <include file="xmldoc/parallel.xml" path="/parallel/arrayUnordered/*"/>
         ///
         /// <param name="action"></param>
         /// <param name="array">The input array.</param>
@@ -4291,8 +4281,7 @@ module Array =
         /// <summary>Apply the given function to each element of the array. The integer passed to the
         /// function indicates the index of element.</summary>
         ///
-        /// <remarks>Performs the operation in parallel using <see cref="M:System.Threading.Tasks.Parallel.For" />.
-        /// The order in which the given function is applied to elements of the input array is not specified. This is an O(n) operation, where n is the length of the array.</remarks>
+        /// <include file="xmldoc/parallel.xml" path="/parallel/arrayUnordered/*"/>
         ///
         /// <param name="action"></param>
         /// <param name="array">The input array.</param>
@@ -4391,8 +4380,7 @@ module Array =
 
         /// <summary>Sorts the elements of an array in parallel, returning a new array. Elements are compared using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>. </summary>
         ///
-        /// <remarks>This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved.
-        /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>. This is an O(n log n) operation, where n is the length of the array.</remarks>
+        /// <include file="xmldoc/sort.xml" path="/sort/arrayUnstable/*"/>
         ///
         /// <param name="array">The input array.</param>
         ///
@@ -4414,8 +4402,7 @@ module Array =
         /// <summary>Sorts the elements of an array in parallel, using the given projection for the keys and returning a new array.
         /// Elements are compared using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>.</summary>
         ///
-        /// <remarks>This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved.
-        /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>. This is an O(n log n) operation, where n is the length of the array.</remarks>
+        /// <include file="xmldoc/sort.xml" path="/sort/arrayUnstable/*"/>
         ///
         /// <param name="projection">The function to transform array elements into the type that is compared.</param>
         /// <param name="array">The input array.</param>
@@ -4438,8 +4425,7 @@ module Array =
 
         /// <summary>Sorts the elements of an array in parallel, using the given comparison function as the order, returning a new array.</summary>
         ///
-        /// <remarks>This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved.
-        /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>. This is an O(n log n) operation, where n is the length of the array.</remarks>
+        /// <include file="xmldoc/sort.xml" path="/sort/arrayUnstable/*"/>
         ///
         /// <param name="comparer">The function to compare pairs of array elements.</param>
         /// <param name="array">The input array.</param>
@@ -4467,8 +4453,7 @@ module Array =
         /// <summary>Sorts the elements of an array by mutating the array in-place in parallel, using the given projection for the keys.
         /// Elements are compared using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>.</summary>
         ///
-        /// <remarks>This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved.
-        /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>. This is an O(n log n) operation, modifying the array in place.</remarks>
+        /// <include file="xmldoc/sort.xml" path="/sort/arrayUnstableInPlace/*"/>
         ///
         /// <param name="projection">The function to transform array elements into the type that is compared.</param>
         /// <param name="array">The input array.</param>
@@ -4533,8 +4518,7 @@ module Array =
 
         /// <summary>Sorts the elements of an array in parallel, in descending order, returning a new array. Elements are compared using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>. </summary>
         ///
-        /// <remarks>This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved.
-        /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>. This is an O(n log n) operation, where n is the length of the array.</remarks>
+        /// <include file="xmldoc/sort.xml" path="/sort/arrayUnstable/*"/>
         ///
         /// <param name="array">The input array.</param>
         ///
@@ -4554,8 +4538,7 @@ module Array =
         /// <summary>Sorts the elements of an array in parallel, in descending order, using the given projection for the keys and returning a new array.
         /// Elements are compared using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>.</summary>
         ///
-        /// <remarks>This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved.
-        /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>. This is an O(n log n) operation, where n is the length of the array.</remarks>
+        /// <include file="xmldoc/sort.xml" path="/sort/arrayUnstable/*"/>
         ///
         /// <param name="projection">The function to transform array elements into the type that is compared.</param>
         /// <param name="array">The input array.</param>

@@ -2075,7 +2075,7 @@ module List =
 
     /// <summary>Sorts the given list using the given comparison function.</summary>
     ///
-    /// <remarks>This is a stable sort, i.e. the original order of equal elements is preserved. This is an O(n log n) operation, where n is the length of the list.</remarks>
+    /// <include file="xmldoc/sort.xml" path="/sort/listStable/*"/>
     /// <param name="comparer">The function to compare the list elements.</param>
     /// <param name="list">The input list.</param>
     ///
@@ -2099,7 +2099,7 @@ module List =
 
     /// <summary>Sorts the given list using keys given by the given projection. Keys are compared using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>.</summary>
     ///
-    /// <remarks>This is a stable sort, i.e. the original order of equal elements is preserved. This is an O(n log n) operation, where n is the length of the list.</remarks>
+    /// <include file="xmldoc/sort.xml" path="/sort/listStable/*"/>
     /// <param name="projection">The function to transform the list elements into the type to be compared.</param>
     /// <param name="list">The input list.</param>
     ///
@@ -2118,7 +2118,7 @@ module List =
 
     /// <summary>Sorts the given list using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>.</summary>
     ///
-    /// <remarks>This is a stable sort, i.e. the original order of equal elements is preserved. This is an O(n log n) operation, where n is the length of the list.</remarks>
+    /// <include file="xmldoc/sort.xml" path="/sort/listStable/*"/>
     /// <param name="list">The input list.</param>
     ///
     /// <returns>The sorted list.</returns>
@@ -2159,7 +2159,7 @@ module List =
 
     /// <summary>Sorts the given list in descending order using keys given by the given projection. Keys are compared using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>.</summary>
     ///
-    /// <remarks>This is a stable sort, i.e. the original order of equal elements is preserved. This is an O(n log n) operation, where n is the length of the list.</remarks>
+    /// <include file="xmldoc/sort.xml" path="/sort/listStable/*"/>
     /// <param name="projection">The function to transform the list elements into the type to be compared.</param>
     /// <param name="list">The input list.</param>
     ///
@@ -2178,7 +2178,7 @@ module List =
 
     /// <summary>Sorts the given list in descending order using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>.</summary>
     ///
-    /// <remarks>This is a stable sort, i.e. the original order of equal elements is preserved. This is an O(n log n) operation, where n is the length of the list.</remarks>
+    /// <include file="xmldoc/sort.xml" path="/sort/listStable/*"/>
     /// <param name="list">The input list.</param>
     ///
     /// <returns>The sorted list.</returns>

@@ -98,19 +98,19 @@ module ResumableCode =
     /// Specifies resumable code which does nothing
     val inline Zero: unit -> ResumableCode<'Data, unit>
 
-    /// The dynamic implementation of the corresponding operation. This operation should not be used directly.
+    /// <include file="xmldoc/dynamic.xml" path="/dynamic/impl/*"/>
     val CombineDynamic: sm: byref<ResumableStateMachine<'Data>> * code1: ResumableCode<'Data, unit> * code2: ResumableCode<'Data, 'T> -> bool
 
-    /// The dynamic implementation of the corresponding operation. This operation should not be used directly.
+    /// <include file="xmldoc/dynamic.xml" path="/dynamic/impl/*"/>
     val WhileDynamic: sm: byref<ResumableStateMachine<'Data>> * condition: (unit -> bool) * body: ResumableCode<'Data, unit> -> bool
 
-    /// The dynamic implementation of the corresponding operation. This operation should not be used directly.
+    /// <include file="xmldoc/dynamic.xml" path="/dynamic/impl/*"/>
     val TryFinallyAsyncDynamic: sm: byref<ResumableStateMachine<'Data>> * body: ResumableCode<'Data, 'T> * compensation: ResumableCode<'Data,unit> -> bool
 
-    /// The dynamic implementation of the corresponding operation. This operation should not be used directly.
+    /// <include file="xmldoc/dynamic.xml" path="/dynamic/impl/*"/>
     val TryWithDynamic: sm: byref<ResumableStateMachine<'Data>> * body: ResumableCode<'Data, 'T> * handler: (exn -> ResumableCode<'Data, 'T>) -> bool
 
-    /// The dynamic implementation of the corresponding operation. This operation should not be used directly.
+    /// <include file="xmldoc/dynamic.xml" path="/dynamic/impl/*"/>
     val YieldDynamic: sm: byref<ResumableStateMachine<'Data>> -> bool
 
 /// Defines the implementation of the MoveNext method for a struct state machine.