Samples for seq module (#12133)

* All pairs

* append

* Average

* averageBy

* Reordering

* Cache

* Cast

* Fixed types in xml comments

* Unused open removed

* Cleanup

* Comparewith

* Refined seq

* delay

* Addressing comments

* Addressing comments

* More examples normalized

* Addressed all comments

* Done with comments

* Added concat example

* Distinct and distinct by.

* Update seq.fsi
Co-authored-by: NDon Syme <dsyme@users.noreply.github.com>

src/fsharp/FSharp.Core/seq.fsi

@@ -4,7 +4,6 @@ namespace Microsoft.FSharp.Collections
 
     open System
     open System.Collections
-    open System.Collections.Generic
     open Microsoft.FSharp.Core
     open Microsoft.FSharp.Collections
         
@@ -21,6 +20,16 @@ namespace Microsoft.FSharp.Collections
         ///
         /// <returns>The result sequence.</returns>
         ///
+        /// <example id="all-pairs-1">
+        /// <code lang="fsharp">
+        /// ([1; 2], [3; 4]) ||> Seq.allPairs
+        /// </code>
+        /// Evaluates to
+        /// <code>
+        /// seq [(1, 3); (1, 4); (2, 3); (2, 4)]
+        /// </code>
+        /// </example>
+        ///
         /// <exception cref="T:System.ArgumentNullException">Thrown when either of the input sequences is null.</exception>
         [<CompiledName("AllPairs")>]
         val allPairs: source1:seq<'T1> -> source2:seq<'T2> -> seq<'T1 * 'T2>
@@ -37,6 +46,13 @@ namespace Microsoft.FSharp.Collections
         ///
         /// <returns>The result sequence.</returns>
         ///
+        /// <example id="append-1">
+        /// <code lang="fsharp">
+        /// ([1; 2], [3; 4]) ||> Seq.append
+        /// </code>
+        /// Evaluates to <c>seq [1; 2; 3; 4]</c>
+        /// </example>
+        ///
         /// <exception cref="T:System.ArgumentNullException">Thrown when either of the two provided sequences is
         /// null.</exception>
         [<CompiledName("Append")>]
@@ -51,12 +67,26 @@ namespace Microsoft.FSharp.Collections
         ///
         /// <returns>The average.</returns>
         ///
+        /// <example id="average-1">
+        /// <code lang="fsharp">
+        /// [1.0; 2.0; 3.0] |> Seq.average
+        /// </code>
+        /// Evaluates to <c>2.0</c>
+        /// </example>
+        ///
+        /// <example id="average-2">
+        /// <code lang="fsharp">
+        /// [] |> Seq.average
+        /// </code>
+        /// Throws <c>ArgumentException</c>
+        /// </example>
+        ///
         /// <exception cref="T:System.ArgumentNullException">Thrown when the input sequence is null.</exception>
         /// <exception cref="T:System.ArgumentException">Thrown when the input sequence has zero elements.</exception>
         [<CompiledName("Average")>]
         val inline average   : source:seq<(^T)> -> ^T 
                                       when ^T : (static member ( + ) : ^T * ^T -> ^T) 
-                                      and  ^T : (static member DivideByInt : ^T * int -> ^T) 
+                                      and  ^T : (static member DivideByInt : ^T * int -> ^T)
                                       and  ^T : (static member Zero : ^T)
 
         /// <summary>Returns the average of the results generated by applying the function to each element 
@@ -70,6 +100,23 @@ namespace Microsoft.FSharp.Collections
         ///
         /// <returns>The average.</returns>
         ///
+        /// <example id="average-by-1">
+        /// <code lang="fsharp">
+        /// type Foo = { Bar: float }
+        ///
+        /// [{Bar = 2.0}; {Bar = 4.0}] |> Seq.averageBy (fun foo -> foo.Bar)
+        /// </code>
+        /// Evaluates to <c>3.0</c>
+        /// </example>
+        ///
+        /// <example id="average-by-2">
+        /// <code lang="fsharp">
+        /// type Foo = { Bar: float }
+        /// [] |> Seq.averageBy (fun foo -> foo.Bar)
+        /// </code>
+        /// Throws <c>ArgumentException</c>
+        /// </example>
+        ///
         /// <exception cref="T:System.ArgumentNullException">Thrown when the input sequence is null.</exception>
         /// <exception cref="T:System.ArgumentException">Thrown when the input sequence has zero elements.</exception>
         [<CompiledName("AverageBy")>]
@@ -106,6 +153,17 @@ namespace Microsoft.FSharp.Collections
         ///
         /// <returns>The result sequence.</returns>
         ///
+        /// <example id="cache-1">
+        /// <code lang="fsharp">
+        /// let fibSeq =(0, 1) |> Seq.unfold (fun (a,b) -> Some(a + b, (b, a + b)))
+        ///
+        /// let fibSeq3 = fibSeq |> Seq.take 3 |> Seq.cache
+        /// fibSeq3
+        /// </code>
+        /// Evaluates to <c>seq [1; 2; 3]</c>,
+        /// and it will not do the calculation again when called.
+        /// </example>
+        ///
         /// <exception cref="T:System.ArgumentNullException">Thrown when the input sequence is null.</exception>
         [<CompiledName("Cache")>]
         val cache: source:seq<'T> -> seq<'T>
@@ -121,6 +179,13 @@ namespace Microsoft.FSharp.Collections
         ///
         /// <returns>The result sequence.</returns>
         ///
+        /// <example id="cast-1">
+        /// <code lang="fsharp">
+        /// ([1; 2; 3] :> IEnumerable) |> Seq.cast&lt;int&gt;
+        /// </code>
+        /// Evaluates to <c>seq [1; 2; 3]</c>, explicitly typed as int seq
+        /// </example>
+        ///
         /// <exception cref="T:System.ArgumentNullException">Thrown when the input sequence is null.</exception>
         [<CompiledName("Cast")>]
         val cast: source:IEnumerable -> seq<'T>
@@ -137,6 +202,20 @@ namespace Microsoft.FSharp.Collections
         /// <param name="source">The input sequence of type T.</param>
         ///
         /// <returns>The result sequence.</returns>
+        ///
+        /// <example id="choose-1">
+        /// <code lang="fsharp">
+        /// [Some 1; None; Some 2] |> Seq.choose id
+        /// </code>
+        /// Evaluates to <c>seq [1; 2]</c>
+        /// </example>
+        ///
+        /// <example id="choose-2">
+        /// <code lang="fsharp">
+        /// [1; 2; 3] |> Seq.choose (fun n -> if n % 2 = 0 then Some n else None)
+        /// </code>
+        /// Evaluates to <c>seq [2]</c>
+        /// </example>
         /// 
         /// <exception cref="T:System.ArgumentNullException">Thrown when the input sequence is null.</exception>
         [<CompiledName("Choose")>]
@@ -148,6 +227,21 @@ namespace Microsoft.FSharp.Collections
         /// <param name="source">The input sequence.</param>
         ///
         /// <returns>The sequence divided into chunks.</returns>
+        ///
+        /// <example id="chunk-by-size-1">
+        /// <code lang="fsharp">
+        /// [1; 2; 3] |> Seq.chunkBySize 2
+        /// </code>
+        /// Evaluates to <c>seq [[|1; 2|]; [|3|]]</c>
+        /// </example>
+        ///
+        /// <example id="chunk-by-size-2">
+        /// <code lang="fsharp">
+        /// [1; 2; 3] |> Seq.chunkBySize -2
+        /// </code>
+        /// Throws <c>ArgumentException</c>
+        /// </example>
+        ///
         /// <exception cref="T:System.ArgumentNullException">Thrown when the input sequence is null.</exception>
         /// <exception cref="T:System.ArgumentException">Thrown when <c>chunkSize</c> is not positive.</exception>
         [<CompiledName("ChunkBySize")>]
@@ -164,6 +258,21 @@ namespace Microsoft.FSharp.Collections
         ///
         /// <returns>The result sequence.</returns>
         ///
+        /// <example id="collec-1">
+        /// <code lang="fsharp">
+        /// type Foo = { Bar: int seq }
+        /// [[{Bar = [1; 2]}; {Bar = [3; 4]}] |> Seq.collect (fun foo -> foo.Bar)
+        /// </code>
+        /// Evaluates to <c>seq [1; 2; 3; 4]</c>
+        /// </example>
+        ///
+        /// <example id="collec-2">
+        /// <code lang="fsharp">
+        /// [[1; 2]; [3; 4]] |> Seq.collect id
+        /// </code>
+        /// Evaluates to <c>seq [1; 2; 3; 4]</c>
+        /// </example>
+        ///
         /// <exception cref="T:System.ArgumentNullException">Thrown when the input sequence is null.</exception>
         [<CompiledName("Collect")>]
         val collect: mapping:('T -> 'Collection) -> source:seq<'T> -> seq<'U>  when 'Collection :> seq<'U>
@@ -179,6 +288,46 @@ namespace Microsoft.FSharp.Collections
         /// is reached it returns a -1 if the first sequence is shorter and a 1 if the second sequence
         /// is shorter.</returns>
         ///
+        /// <example id="compare-with-1">
+        /// <code lang="fsharp">
+        /// ([1; 2], [1; 2])
+        /// ||> Seq.compareWith (fun a b -> a.CompareTo(b))
+        /// </code>
+        /// Evaluates to <c>0</c>
+        /// </example>
+        ///
+        /// <example id="compare-with-2">
+        /// <code lang="fsharp">
+        /// ([1; 2], [1; 3])
+        /// ||> Seq.compareWith (fun a b -> a.CompareTo(b))
+        /// </code>
+        /// Evaluates to <c>-1</c>
+        /// </example>
+        ///
+        /// <example id="compare-with-3">
+        /// <code lang="fsharp">
+        /// ([1; 3], [1; 2])
+        /// ||> Seq.compareWith (fun a b -> a.CompareTo(b))
+        /// </code>
+        /// Evaluates to <c>1</c>
+        /// </example>
+        ///
+        /// <example id="compare-with-4">
+        /// <code lang="fsharp">
+        /// ([1; 2], [1])
+        /// ||> Seq.compareWith (fun a b -> a.CompareTo(b))
+        /// </code>
+        /// Evaluates to <c>1</c>
+        /// </example>
+        ///
+        /// <example id="compare-with-5">
+        /// <code lang="fsharp">
+        /// ([1], [1; 2])
+        /// ||> Seq.compareWith (fun a b -> a.CompareTo(b))
+        /// </code>
+        /// Evaluates to <c>-1</c>
+        /// </example>
+        ///
         /// <exception cref="T:System.ArgumentNullException">Thrown when either of the input sequences
         /// is null.</exception>
         [<CompiledName("CompareWith")>]
@@ -194,6 +343,13 @@ namespace Microsoft.FSharp.Collections
         ///
         /// <returns>The result sequence.</returns>
         ///
+        /// <example id="concat-1">
+        /// <code lang="fsharp">
+        /// [[1; 2]; [3]; [4; 5]] |> Seq.concat
+        /// </code>
+        /// Evaluates to <c>seq [1; 2; 3; 4; 5]</c>
+        /// </example>
+        ///
         /// <exception cref="T:System.ArgumentNullException">Thrown when the input sequence is null.</exception>
         [<CompiledName("Concat")>]
         val concat: sources:seq<'Collection> -> seq<'T> when 'Collection :> seq<'T>
@@ -204,6 +360,14 @@ namespace Microsoft.FSharp.Collections
         /// <param name="source">The input sequence.</param>
         ///
         /// <returns>True if the input sequence contains the specified element; false otherwise.</returns>
+        ///
+        /// <example id="contains-1">
+        /// <code lang="fsharp">
+        /// [1; 2] |> Seq.contains 2 // evaluates to true
+        /// [1; 2] |> Seq.contains 5 // evaluates to false
+        /// </code>
+        /// </example>
+        ///
         /// <exception cref="T:System.ArgumentNullException">Thrown when the input sequence is null.</exception>
         [<CompiledName("Contains")>]
         val inline contains: value:'T -> source:seq<'T> -> bool when 'T : equality
@@ -223,8 +387,18 @@ namespace Microsoft.FSharp.Collections
         /// <returns>The result sequence.</returns>
         ///
         /// <exception cref="T:System.ArgumentNullException">Thrown when the input sequence is null.</exception>
+        ///
+        /// <example id="count-by-1">
+        /// <code lang="fsharp">
+        /// type Foo = { Bar: string }
+        ///
+        /// [{Bar = "a"}; {Bar = "b"}; {Bar = "a"}]
+        /// |> Seq.countBy (fun foo -> foo.Bar)
+        /// </code>
+        /// Evaluates to <c>seq [("a", 2); ("b", 1)]</c>
+        /// </example>
         [<CompiledName("CountBy")>]
-        val countBy : projection:('T -> 'Key) -> source:seq<'T> -> seq<'Key * int> when 'Key : equality
+        val countBy: projection:('T -> 'Key) -> source:seq<'T> -> seq<'Key * int> when 'Key : equality
 
         /// <summary>Returns a sequence that is built from the given delayed specification of a
         /// sequence.</summary>
@@ -233,8 +407,17 @@ namespace Microsoft.FSharp.Collections
         /// is requested.</remarks>
         ///
         /// <param name="generator">The generating function for the sequence.</param>
+        /// <returns>The result sequence.</returns>
+        ///
+        /// <example id="delay-1">
+        /// <code lang="fsharp">
+        /// Seq.delay (fun () -> Seq.ofList [1; 2; 3])
+        /// </code>
+        /// Evaluates to <c>seq [1; 2; 3]</c>, executing
+        /// the generator function every time is consumed.
+        /// </example>
         [<CompiledName("Delay")>]
-        val delay   : generator:(unit -> seq<'T>) -> seq<'T>
+        val delay: generator:(unit -> seq<'T>) -> seq<'T>
 
         /// <summary>Returns a sequence that contains no duplicate entries according to generic hash and
         /// equality comparisons on the entries.
@@ -245,6 +428,13 @@ namespace Microsoft.FSharp.Collections
         /// <returns>The result sequence.</returns>
         ///
         /// <exception cref="T:System.ArgumentNullException">Thrown when the input sequence is null.</exception>
+        ///
+        /// <example id="distinct-1">
+        /// <code lang="fsharp">
+        /// [1; 1; 2; 3] |> Seq.distinct
+        /// </code>
+        /// Evaluates to <c>seq [1; 2; 3]</c>
+        /// </example>
         [<CompiledName("Distinct")>]
         val distinct: source:seq<'T> -> seq<'T> when 'T : equality
 
@@ -258,6 +448,14 @@ namespace Microsoft.FSharp.Collections
         /// <returns>The result sequence.</returns>
         ///
         /// <exception cref="T:System.ArgumentNullException">Thrown when the input sequence is null.</exception>
+        ///
+        /// <example id="distinct-by-1">
+        /// <code lang="fsharp">
+        /// [{Bar = 1 };{Bar = 1}; {Bar = 2}; {Bar = 3}]
+        /// |> Seq.distinctBy (fun foo -> foo.Bar)
+        /// </code>
+        /// Evaluates to <c>seq [{ Bar = 1 }; { Bar = 2 }; { Bar = 3 }]</c>
+        /// </example>
         [<CompiledName("DistinctBy")>]
         val distinctBy: projection:('T -> 'Key) -> source:seq<'T> -> seq<'T> when 'Key : equality
 
@@ -277,7 +475,7 @@ namespace Microsoft.FSharp.Collections
         /// <summary>Creates an empty sequence.</summary>
         ///
         /// <returns>An empty sequence.</returns>
-        [<GeneralizableValueAttribute>]
+        [<GeneralizableValue>]
         [<CompiledName("Empty")>]
         val empty<'T> : seq<'T>
 
@@ -1484,4 +1682,4 @@ namespace Microsoft.FSharp.Collections
         ///
         /// <exception cref="T:System.ArgumentException">Thrown when index is below 0 or greater than source.Length.</exception>
         [<CompiledName("InsertManyAt")>]
-        val insertManyAt: index: int -> values: seq<'T> -> source: seq<'T> -> seq<'T>
\ No newline at end of file
+        val insertManyAt: index: int -> values: seq<'T> -> source: seq<'T> -> seq<'T>