From adff9a8b0c3b8f3fee4836f3ff97e0259f402934 Mon Sep 17 00:00:00 2001 From: Tomas Grosup Date: Fri, 7 Aug 2026 13:51:21 +0200 Subject: [PATCH] Deduplicate FSharp.Core XML docs via Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/release-notes/.FSharp.Core/11.0.100.md | 4 ++ src/FSharp.Core/array.fsi | 51 +++++++-------------- src/FSharp.Core/list.fsi | 10 ++-- src/FSharp.Core/resumable.fsi | 10 ++-- src/FSharp.Core/seq.fsi | 35 ++------------ src/FSharp.Core/tasks.fsi | 16 ++----- src/FSharp.Core/xmldoc/dynamic.xml | 7 +++ src/FSharp.Core/xmldoc/parallel.xml | 5 ++ src/FSharp.Core/xmldoc/sort.xml | 20 ++++++++ 9 files changed, 72 insertions(+), 86 deletions(-) create mode 100644 src/FSharp.Core/xmldoc/dynamic.xml create mode 100644 src/FSharp.Core/xmldoc/parallel.xml create mode 100644 src/FSharp.Core/xmldoc/sort.xml diff --git a/docs/release-notes/.FSharp.Core/11.0.100.md b/docs/release-notes/.FSharp.Core/11.0.100.md index 97c667e0eb3..0c1bfd89b72 100644 --- a/docs/release-notes/.FSharp.Core/11.0.100.md +++ b/docs/release-notes/.FSharp.Core/11.0.100.md @@ -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 `` tag; generated FSharp.Core.xml is unchanged. ([PR #20231](https://github.com/dotnet/fsharp/pull/20231)) diff --git a/src/FSharp.Core/array.fsi b/src/FSharp.Core/array.fsi index 9d5ae1c0742..397df39d7cb 100644 --- a/src/FSharp.Core/array.fsi +++ b/src/FSharp.Core/array.fsi @@ -2432,8 +2432,7 @@ module Array = /// Sorts the elements of an array, returning a new array. Elements are compared using . /// - /// This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved. - /// For a stable sort, consider using . This is an O(n log n) operation, where n is the length of the array. + /// /// /// The input array. /// @@ -2455,8 +2454,7 @@ module Array = /// Sorts the elements of an array, using the given projection for the keys and returning a new array. /// Elements are compared using . /// - /// This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved. - /// For a stable sort, consider using . This is an O(n log n) operation, where n is the length of the array. + /// /// /// The function to transform array elements into the type that is compared. /// The input array. @@ -2478,8 +2476,7 @@ module Array = /// Sorts the elements of an array, using the given comparison function as the order, returning a new array. /// - /// This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved. - /// For a stable sort, consider using . This is an O(n log n) operation, where n is the length of the array. + /// /// /// The function to compare pairs of array elements. /// The input array. @@ -2507,8 +2504,7 @@ module Array = /// Sorts the elements of an array by mutating the array in-place, using the given projection for the keys. /// Elements are compared using . /// - /// This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved. - /// For a stable sort, consider using . This is an O(n log n) operation, modifying the array in place. + /// /// /// The function to transform array elements into the type that is compared. /// The input array. @@ -2597,8 +2593,7 @@ module Array = /// Sorts the elements of an array, in descending order, returning a new array. Elements are compared using . /// - /// This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved. - /// For a stable sort, consider using . This is an O(n log n) operation, where n is the length of the array. + /// /// /// The input array. /// @@ -2618,8 +2613,7 @@ module Array = /// 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 . /// - /// This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved. - /// For a stable sort, consider using . This is an O(n log n) operation, where n is the length of the array. + /// /// /// The function to transform array elements into the type that is compared. /// The input array. @@ -4123,8 +4117,7 @@ module Array = /// the array comprised of the results x for each element where /// the function returns Some(x). /// - /// Performs the operation in parallel using . - /// 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. + /// /// /// The function to generate options from the elements. /// The input array. @@ -4190,8 +4183,7 @@ module Array = /// Build a new array whose elements are the results of applying the given function /// to each of the elements of the array. /// - /// Performs the operation in parallel using . - /// 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. + /// /// /// /// The input array. @@ -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. /// - /// Performs the operation in parallel using . - /// 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. + /// /// /// /// The input array. @@ -4264,8 +4255,7 @@ module Array = /// Apply the given function to each element of the array. /// - /// Performs the operation in parallel using . - /// 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. + /// /// /// /// The input array. @@ -4291,8 +4281,7 @@ module Array = /// Apply the given function to each element of the array. The integer passed to the /// function indicates the index of element. /// - /// Performs the operation in parallel using . - /// 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. + /// /// /// /// The input array. @@ -4391,8 +4380,7 @@ module Array = /// Sorts the elements of an array in parallel, returning a new array. Elements are compared using . /// - /// This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved. - /// For a stable sort, consider using . This is an O(n log n) operation, where n is the length of the array. + /// /// /// The input array. /// @@ -4414,8 +4402,7 @@ module Array = /// Sorts the elements of an array in parallel, using the given projection for the keys and returning a new array. /// Elements are compared using . /// - /// This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved. - /// For a stable sort, consider using . This is an O(n log n) operation, where n is the length of the array. + /// /// /// The function to transform array elements into the type that is compared. /// The input array. @@ -4438,8 +4425,7 @@ module Array = /// Sorts the elements of an array in parallel, using the given comparison function as the order, returning a new array. /// - /// This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved. - /// For a stable sort, consider using . This is an O(n log n) operation, where n is the length of the array. + /// /// /// The function to compare pairs of array elements. /// The input array. @@ -4467,8 +4453,7 @@ module Array = /// 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 . /// - /// This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved. - /// For a stable sort, consider using . This is an O(n log n) operation, modifying the array in place. + /// /// /// The function to transform array elements into the type that is compared. /// The input array. @@ -4533,8 +4518,7 @@ module Array = /// Sorts the elements of an array in parallel, in descending order, returning a new array. Elements are compared using . /// - /// This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved. - /// For a stable sort, consider using . This is an O(n log n) operation, where n is the length of the array. + /// /// /// The input array. /// @@ -4554,8 +4538,7 @@ module Array = /// 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 . /// - /// This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved. - /// For a stable sort, consider using . This is an O(n log n) operation, where n is the length of the array. + /// /// /// The function to transform array elements into the type that is compared. /// The input array. diff --git a/src/FSharp.Core/list.fsi b/src/FSharp.Core/list.fsi index af7ddf2aeef..a1d101c40df 100644 --- a/src/FSharp.Core/list.fsi +++ b/src/FSharp.Core/list.fsi @@ -2075,7 +2075,7 @@ module List = /// Sorts the given list using the given comparison function. /// - /// 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. + /// /// The function to compare the list elements. /// The input list. /// @@ -2099,7 +2099,7 @@ module List = /// Sorts the given list using keys given by the given projection. Keys are compared using . /// - /// 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. + /// /// The function to transform the list elements into the type to be compared. /// The input list. /// @@ -2118,7 +2118,7 @@ module List = /// Sorts the given list using . /// - /// 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. + /// /// The input list. /// /// The sorted list. @@ -2159,7 +2159,7 @@ module List = /// Sorts the given list in descending order using keys given by the given projection. Keys are compared using . /// - /// 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. + /// /// The function to transform the list elements into the type to be compared. /// The input list. /// @@ -2178,7 +2178,7 @@ module List = /// Sorts the given list in descending order using . /// - /// 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. + /// /// The input list. /// /// The sorted list. diff --git a/src/FSharp.Core/resumable.fsi b/src/FSharp.Core/resumable.fsi index e62a6597729..f279ac85c33 100644 --- a/src/FSharp.Core/resumable.fsi +++ b/src/FSharp.Core/resumable.fsi @@ -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. + /// val CombineDynamic: sm: byref> * code1: ResumableCode<'Data, unit> * code2: ResumableCode<'Data, 'T> -> bool - /// The dynamic implementation of the corresponding operation. This operation should not be used directly. + /// val WhileDynamic: sm: byref> * condition: (unit -> bool) * body: ResumableCode<'Data, unit> -> bool - /// The dynamic implementation of the corresponding operation. This operation should not be used directly. + /// val TryFinallyAsyncDynamic: sm: byref> * body: ResumableCode<'Data, 'T> * compensation: ResumableCode<'Data,unit> -> bool - /// The dynamic implementation of the corresponding operation. This operation should not be used directly. + /// val TryWithDynamic: sm: byref> * body: ResumableCode<'Data, 'T> * handler: (exn -> ResumableCode<'Data, 'T>) -> bool - /// The dynamic implementation of the corresponding operation. This operation should not be used directly. + /// val YieldDynamic: sm: byref> -> bool /// Defines the implementation of the MoveNext method for a struct state machine. diff --git a/src/FSharp.Core/seq.fsi b/src/FSharp.Core/seq.fsi index 86f09996263..74dcdc89133 100644 --- a/src/FSharp.Core/seq.fsi +++ b/src/FSharp.Core/seq.fsi @@ -2287,12 +2287,7 @@ module Seq = /// Yields a sequence ordered by keys. /// - /// This function returns a sequence that digests the whole initial sequence as soon as - /// that sequence is iterated. As a result this function should not be used with - /// large or infinite sequences. - /// - /// The function makes no assumption on the ordering of the original - /// sequence and uses a stable sort, that is the original order of equal elements is preserved. This is an O(n log n) operation, where n is the length of the sequence. + /// /// /// The input sequence. /// @@ -2313,12 +2308,7 @@ module Seq = /// Yields a sequence ordered using the given comparison function. /// - /// This function returns a sequence that digests the whole initial sequence as soon as - /// that sequence is iterated. As a result this function should not be used with - /// large or infinite sequences. - /// - /// The function makes no assumption on the ordering of the original - /// sequence and uses a stable sort, that is the original order of equal elements is preserved. This is an O(n log n) operation, where n is the length of the sequence. + /// /// /// The function to compare the collection elements. /// The input sequence. @@ -2344,12 +2334,7 @@ module Seq = /// Applies a key-generating function to each element of a sequence and yield a sequence ordered /// by keys. The keys are compared using generic comparison as implemented by . /// - /// This function returns a sequence that digests the whole initial sequence as soon as - /// that sequence is iterated. As a result this function should not be used with - /// large or infinite sequences. - /// - /// The function makes no assumption on the ordering of the original - /// sequence and uses a stable sort, that is the original order of equal elements is preserved. This is an O(n log n) operation, where n is the length of the sequence. + /// /// /// A function to transform items of the input sequence into comparable keys. /// The input sequence. @@ -2371,12 +2356,7 @@ module Seq = /// Yields a sequence ordered descending by keys. /// - /// This function returns a sequence that digests the whole initial sequence as soon as - /// that sequence is iterated. As a result this function should not be used with - /// large or infinite sequences. The function makes no assumption on the ordering of the original - /// sequence. - /// - /// This is a stable sort, that is the original order of equal elements is preserved. This is an O(n log n) operation, where n is the length of the sequence. + /// /// /// The input sequence. /// @@ -2398,12 +2378,7 @@ module Seq = /// Applies a key-generating function to each element of a sequence and yield a sequence ordered /// descending by keys. The keys are compared using generic comparison as implemented by . /// - /// This function returns a sequence that digests the whole initial sequence as soon as - /// that sequence is iterated. As a result this function should not be used with - /// large or infinite sequences. The function makes no assumption on the ordering of the original - /// sequence. - /// - /// This is a stable sort, that is the original order of equal elements is preserved. This is an O(n log n) operation, where n is the length of the sequence. + /// /// /// A function to transform items of the input sequence into comparable keys. /// The input sequence. diff --git a/src/FSharp.Core/tasks.fsi b/src/FSharp.Core/tasks.fsi index 76d84bcfd28..cb73022a74f 100644 --- a/src/FSharp.Core/tasks.fsi +++ b/src/FSharp.Core/tasks.fsi @@ -119,9 +119,7 @@ type TaskBuilderBase = type TaskBuilder = inherit TaskBuilderBase - /// - /// The entry point for the dynamic implementation of the corresponding operation. Do not use directly, only used when executing quotations that involve tasks or other reflective execution of F# code. - /// + /// static member RunDynamic: code: TaskCode<'T, 'T> -> Task<'T> /// Hosts the task code in a state machine and starts the task. @@ -134,9 +132,7 @@ type TaskBuilder = type BackgroundTaskBuilder = inherit TaskBuilderBase - /// - /// The entry point for the dynamic implementation of the corresponding operation. Do not use directly, only used when executing quotations that involve tasks or other reflective execution of F# code. - /// + /// static member RunDynamic: code: TaskCode<'T, 'T> -> Task<'T> /// @@ -218,9 +214,7 @@ module LowPriority = and ^Awaiter: (member get_IsCompleted: unit -> bool) and ^Awaiter: (member GetResult: unit -> 'T) - /// - /// The entry point for the dynamic implementation of the corresponding operation. Do not use directly, only used when executing quotations that involve tasks or other reflective execution of F# code. - /// + /// [] static member inline BindDynamic< ^TaskLike, 'TResult1, 'TResult2, ^Awaiter, 'TOverall> : sm: byref> * @@ -435,9 +429,7 @@ module HighPriority = /// member inline ReturnFrom: task: Task<'T> -> TaskCode<'T, 'T> - /// - /// The entry point for the dynamic implementation of the corresponding operation. Do not use directly, only used when executing quotations that involve tasks or other reflective execution of F# code. - /// + /// static member BindDynamic: sm: byref> * task: Task<'TResult1> * diff --git a/src/FSharp.Core/xmldoc/dynamic.xml b/src/FSharp.Core/xmldoc/dynamic.xml new file mode 100644 index 00000000000..0606fbdf676 --- /dev/null +++ b/src/FSharp.Core/xmldoc/dynamic.xml @@ -0,0 +1,7 @@ + + + +The entry point for the dynamic implementation of the corresponding operation. Do not use directly, only used when executing quotations that involve tasks or other reflective execution of F# code. + + The dynamic implementation of the corresponding operation. This operation should not be used directly. + diff --git a/src/FSharp.Core/xmldoc/parallel.xml b/src/FSharp.Core/xmldoc/parallel.xml new file mode 100644 index 00000000000..b81f982a13b --- /dev/null +++ b/src/FSharp.Core/xmldoc/parallel.xml @@ -0,0 +1,5 @@ + + + Performs the operation in parallel using . +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. + diff --git a/src/FSharp.Core/xmldoc/sort.xml b/src/FSharp.Core/xmldoc/sort.xml new file mode 100644 index 00000000000..3cb8257ad2a --- /dev/null +++ b/src/FSharp.Core/xmldoc/sort.xml @@ -0,0 +1,20 @@ + + + This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved. +For a stable sort, consider using . This is an O(n log n) operation, where n is the length of the array. + This is not a stable sort, i.e. the original order of equal elements is not necessarily preserved. +For a stable sort, consider using . This is an O(n log n) operation, modifying the array in place. + 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. + This function returns a sequence that digests the whole initial sequence as soon as +that sequence is iterated. As a result this function should not be used with +large or infinite sequences. + +The function makes no assumption on the ordering of the original +sequence and uses a stable sort, that is the original order of equal elements is preserved. This is an O(n log n) operation, where n is the length of the sequence. + This function returns a sequence that digests the whole initial sequence as soon as +that sequence is iterated. As a result this function should not be used with +large or infinite sequences. The function makes no assumption on the ordering of the original +sequence. + +This is a stable sort, that is the original order of equal elements is preserved. This is an O(n log n) operation, where n is the length of the sequence. +