Improve docs for FSharp.Core (dotnet#9880)

* various doc improvements

* don't use uppercase since in cref it is shown as text

Author: dsyme

src/fsharp/FSharp.Core/Linq.fsi

@@ -8,6 +8,13 @@ open Microsoft.FSharp.Core
 open Microsoft.FSharp.Collections
 open Microsoft.FSharp.Quotations
 
+/// <summary>
+/// Contains functionality to convert F# quotations to LINQ expression trees.
+/// </summary>
+///
+/// <namespacedoc><summary>
+///   Library functionality associated with converting F# quotations to .NET LINQ expression trees.
+/// </summary></namespacedoc>
 module LeafExpressionConverter =
     /// When used in a quotation, this function indicates a specific conversion
     /// should be performed when converting the quotation to a LINQ expression. 

src/fsharp/FSharp.Core/MutableTuple.fs

@@ -22,14 +22,16 @@ open Microsoft.FSharp.Core
 // This terminology mistake also runs all the way through Query.fs. 
 // ----------------------------------------------------------------------------
 
-/// This type shouldn't be used directly from user code.
+/// <summary>This type shouldn't be used directly from user code.</summary>
+/// <exclude />
 type AnonymousObject<'T1> =
     val private item1 : 'T1
     member x.Item1 = x.item1 
 
     new (Item1) = { item1 = Item1 }
 
-/// This type shouldn't be used directly from user code.
+/// <summary>This type shouldn't be used directly from user code.</summary>
+/// <exclude />
 type AnonymousObject<'T1, 'T2> =
     val private item1 : 'T1
     member x.Item1 = x.item1 
@@ -39,7 +41,8 @@ type AnonymousObject<'T1, 'T2> =
 
     new (Item1, Item2) = { item1 = Item1; item2 = Item2  }
 
-/// This type shouldn't be used directly from user code.
+/// <summary>This type shouldn't be used directly from user code.</summary>
+/// <exclude />
 type AnonymousObject<'T1, 'T2, 'T3> =
     val private item1 : 'T1
     member x.Item1 = x.item1 
@@ -53,7 +56,8 @@ type AnonymousObject<'T1, 'T2, 'T3> =
     new (Item1, Item2, Item3) = { item1 = Item1; item2 = Item2; item3 = Item3  }
 
 
-/// This type shouldn't be used directly from user code.
+/// <summary>This type shouldn't be used directly from user code.</summary>
+/// <exclude />
 type AnonymousObject<'T1, 'T2, 'T3, 'T4> =
     val private item1 : 'T1
     member x.Item1 = x.item1 
@@ -71,7 +75,8 @@ type AnonymousObject<'T1, 'T2, 'T3, 'T4> =
 
 
 
-/// This type shouldn't be used directly from user code.
+/// <summary>This type shouldn't be used directly from user code.</summary>
+/// <exclude />
 type AnonymousObject<'T1, 'T2, 'T3, 'T4, 'T5> =
     val private item1 : 'T1
     member x.Item1 = x.item1 
@@ -91,7 +96,8 @@ type AnonymousObject<'T1, 'T2, 'T3, 'T4, 'T5> =
     new (Item1, Item2, Item3, Item4, Item5) = { item1 = Item1; item2 = Item2; item3 = Item3; item4 = Item4 ; item5 = Item5  }
 
 
-/// This type shouldn't be used directly from user code.
+/// <summary>This type shouldn't be used directly from user code.</summary>
+/// <exclude />
 type AnonymousObject<'T1, 'T2, 'T3, 'T4, 'T5, 'T6> =
     val private item1 : 'T1
     member x.Item1 = x.item1 
@@ -114,7 +120,8 @@ type AnonymousObject<'T1, 'T2, 'T3, 'T4, 'T5, 'T6> =
     new (Item1, Item2, Item3, Item4, Item5, Item6) = { item1 = Item1; item2 = Item2; item3 = Item3; item4 = Item4 ; item5 = Item5 ; item6 = Item6  }
 
 
-/// This type shouldn't be used directly from user code.
+/// <summary>This type shouldn't be used directly from user code.</summary>
+/// <exclude />
 type AnonymousObject<'T1, 'T2, 'T3, 'T4, 'T5, 'T6, 'T7> =
     val private item1 : 'T1
     member x.Item1 = x.item1 
@@ -139,7 +146,8 @@ type AnonymousObject<'T1, 'T2, 'T3, 'T4, 'T5, 'T6, 'T7> =
 
     new (Item1, Item2, Item3, Item4, Item5, Item6, Item7) = { item1 = Item1; item2 = Item2; item3 = Item3; item4 = Item4 ; item5 = Item5 ; item6 = Item6  ; item7 = Item7  }
 
-/// This type shouldn't be used directly from user code.
+/// <summary>This type shouldn't be used directly from user code.</summary>
+/// <exclude />
 type AnonymousObject<'T1, 'T2, 'T3, 'T4, 'T5, 'T6, 'T7, 'T8> =
     val private item1 : 'T1
     member x.Item1 = x.item1 

src/fsharp/FSharp.Core/Query.fsi

@@ -11,19 +11,28 @@ namespace Microsoft.FSharp.Linq
     open System.Collections.Generic
 
     [<NoComparison; NoEquality; Sealed>]
+    /// <summary>
     /// A partial input or result in an F# query. This type is used to support the F# query syntax.
+    /// </summary>
+    ///
+    /// <namespacedoc><summary>
+    ///   Library functionality for F# query syntax and interoperability with .NET LINQ Expressions. See 
+    ///   also <a href="https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/query-expressions">F# Query Expressions</a> in the F# Language Guide.
+    /// </summary></namespacedoc>
     type QuerySource<'T, 'Q> =
         /// <summary>
         /// A method used to support the F# query syntax.  
         /// </summary>
         new : seq<'T> -> QuerySource<'T,'Q>
+
         /// <summary>
         /// A property used to support the F# query syntax.  
         /// </summary>
         member Source : seq<'T>
 
     [<Class>]
-    /// The type used to support the F# query syntax. Use 'query { ... }' to use the query syntax.
+    /// The type used to support the F# query syntax. Use 'query { ... }' to use the query syntax. See 
+    /// also <a href="https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/query-expressions">F# Query Expressions</a> in the F# Language Guide.
     type QueryBuilder =
         /// <summary>Create an instance of this builder. Use 'query { ... }' to use the query syntax.</summary>
         new : unit -> QueryBuilder
@@ -350,6 +359,13 @@ namespace Microsoft.FSharp.Linq.QueryRunExtensions
 
     open Microsoft.FSharp.Core
 
+    /// <summary>
+    /// A module used to support the F# query syntax.  
+    /// </summary>
+    ///
+    /// <namespacedoc><summary>
+    ///    Contains modules used to support the F# query syntax.  
+    /// </summary></namespacedoc>
     module LowPriority = 
         type Microsoft.FSharp.Linq.QueryBuilder with
             /// <summary>
@@ -358,6 +374,9 @@ namespace Microsoft.FSharp.Linq.QueryRunExtensions
             [<CompiledName("RunQueryAsValue")>]
             member Run : Microsoft.FSharp.Quotations.Expr<'T> -> 'T
 
+    /// <summary>
+    /// A module used to support the F# query syntax.  
+    /// </summary>
     module HighPriority = 
         type Microsoft.FSharp.Linq.QueryBuilder with
             /// <summary>

src/fsharp/FSharp.Core/array.fsi

@@ -7,7 +7,7 @@ namespace Microsoft.FSharp.Collections
     open Microsoft.FSharp.Collections
     open System.Collections.Generic
 
-    /// <summary>Basic operations on arrays.</summary>
+    /// <summary>Contains operations for working with arrays.</summary>
     ///
     /// <remarks>
     ///  See also <a href="https://docs.microsoft.com/dotnet/fsharp/language-reference/arrays">F# Language Guide - Arrays</a>.
@@ -1033,10 +1033,10 @@ namespace Microsoft.FSharp.Collections
         [<CompiledName("GetSubArray")>]
         val sub: array:'T[] -> startIndex:int -> count:int -> 'T[]
 
-        /// <summary>Sorts the elements of an array, returning a new array. Elements are compared using Operators.compare. </summary>
+        /// <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 Seq.sort.</remarks>
+        /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>.</remarks>
         ///
         /// <param name="array">The input array.</param>
         ///
@@ -1047,10 +1047,10 @@ namespace Microsoft.FSharp.Collections
         val sort: array:'T[] -> 'T[] when 'T : comparison 
 
         /// <summary>Sorts the elements of an array, using the given projection for the keys and returning a new array. 
-        /// Elements are compared using Operators.compare.</summary>
+        /// 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 Seq.sort.</remarks>
+        /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>.</remarks>
         ///
         /// <param name="projection">The function to transform array elements into the type that is compared.</param>
         /// <param name="array">The input array.</param>
@@ -1064,7 +1064,7 @@ namespace Microsoft.FSharp.Collections
         /// <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 Seq.sort.</remarks>
+        /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>.</remarks>
         ///
         /// <param name="comparer">The function to compare pairs of array elements.</param>
         /// <param name="array">The input array.</param>
@@ -1076,10 +1076,10 @@ namespace Microsoft.FSharp.Collections
         val sortWith: comparer:('T -> 'T -> int) -> array:'T[] -> 'T[]
 
         /// <summary>Sorts the elements of an array by mutating the array in-place, using the given projection for the keys. 
-        /// Elements are compared using Operators.compare.</summary>
+        /// 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 Seq.sort.</remarks>
+        /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>.</remarks>
         ///
         /// <param name="projection">The function to transform array elements into the type that is compared.</param>
         /// <param name="array">The input array.</param>
@@ -1100,7 +1100,7 @@ namespace Microsoft.FSharp.Collections
         val sortInPlaceWith: comparer:('T -> 'T -> int) -> array:'T[] -> unit
 
         /// <summary>Sorts the elements of an array by mutating the array in-place, using the given comparison function. 
-        /// Elements are compared using Operators.compare.</summary>
+        /// Elements are compared using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>.</summary>
         ///
         /// <param name="array">The input array.</param>
         ///
@@ -1121,10 +1121,10 @@ namespace Microsoft.FSharp.Collections
         [<CompiledName("SplitAt")>]
         val splitAt: index:int -> array:'T[] -> ('T[] * 'T[])
 
-        /// <summary>Sorts the elements of an array, in descending order, returning a new array. Elements are compared using Operators.compare. </summary>
+        /// <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 Seq.sort.</remarks>
+        /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>.</remarks>
         ///
         /// <param name="array">The input array.</param>
         ///
@@ -1133,10 +1133,10 @@ namespace Microsoft.FSharp.Collections
         val inline sortDescending: array:'T[] -> 'T[] when 'T : comparison
 
         /// <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 Operators.compare.</summary>
+        /// 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 Seq.sort.</remarks>
+        /// For a stable sort, consider using <see cref="M:Microsoft.FSharp.Collections.SeqModule.Sort"/>.</remarks>
         ///
         /// <param name="projection">The function to transform array elements into the type that is compared.</param>
         /// <param name="array">The input array.</param>
@@ -1403,21 +1403,21 @@ namespace Microsoft.FSharp.Collections
             /// the array comprised of the results "x" for each element where
             /// the function returns Some(x).</summary>
             ///
-            /// <remarks>Performs the operation in parallel using System.Threading.Parallel.For.
+            /// <remarks>Performs the operation in parallel using <see cref="M:System.Threading.Parallel.For" />.
             /// The order in which the given function is applied to elements of the input array is not specified.</remarks>
             ///
             /// <param name="chooser">The function to generate options from the elements.</param>
             /// <param name="array">The input array.</param>
             ///
-            /// <returns>'U[]</returns>
+            /// <returns>The array of results.</returns>
             ///
             /// <exception cref="T:System.ArgumentNullException">Thrown when the input array is null.</exception>
             [<CompiledName("Choose")>]
             val choose: chooser:('T -> 'U option) -> array:'T[] -> 'U[]
 
             /// <summary>For each element of the array, apply the given function. Concatenate all the results and return the combined array.</summary>
             ///
-            /// <remarks>Performs the operation in parallel using System.Threading.Parallel.For.
+            /// <remarks>Performs the operation in parallel using <see cref="M:System.Threading.Parallel.For" />.
             /// The order in which the given function is applied to elements of the input array is not specified.</remarks>
             ///
             /// <param name="mapping"></param>
@@ -1432,13 +1432,13 @@ namespace Microsoft.FSharp.Collections
             /// <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 System.Threading.Parallel.For.
+            /// <remarks>Performs the operation in parallel using <see cref="M:System.Threading.Parallel.For" />.
             /// The order in which the given function is applied to elements of the input array is not specified.</remarks>
             ///
             /// <param name="mapping"></param>
             /// <param name="array">The input array.</param>
             ///
-            /// <returns>'U[]</returns>
+            /// <returns>The array of results.</returns>
             ///
             /// <exception cref="T:System.ArgumentNullException">Thrown when the input array is null.</exception>
             [<CompiledName("Map")>]
@@ -1448,21 +1448,21 @@ namespace Microsoft.FSharp.Collections
             /// 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 System.Threading.Parallel.For.
+            /// <remarks>Performs the operation in parallel using <see cref="M:System.Threading.Parallel.For" />.
             /// The order in which the given function is applied to elements of the input array is not specified.</remarks>
             ///
             /// <param name="mapping"></param>
             /// <param name="array">The input array.</param>
             ///
-            /// <returns>'U[]</returns>
+            /// <returns>The array of results.</returns>
             ///
             /// <exception cref="T:System.ArgumentNullException">Thrown when the input array is null.</exception>
             [<CompiledName("MapIndexed")>]
             val mapi: mapping:(int -> 'T -> 'U) -> array:'T[] -> 'U[]
 
             /// <summary>Apply the given function to each element of the array. </summary>
             ///
-            /// <remarks>Performs the operation in parallel using System.Threading.Parallel.For.
+            /// <remarks>Performs the operation in parallel using <see cref="M:System.Threading.Parallel.For" />.
             /// The order in which the given function is applied to elements of the input array is not specified.</remarks>
             ///
             /// <param name="action"></param>
@@ -1475,7 +1475,7 @@ namespace Microsoft.FSharp.Collections
             /// <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 System.Threading.Parallel.For.
+            /// <remarks>Performs the operation in parallel using <see cref="M:System.Threading.Parallel.For" />.
             /// The order in which the given function is applied to elements of the input array is not specified.</remarks>
             ///
             /// <param name="action"></param>
@@ -1487,27 +1487,27 @@ namespace Microsoft.FSharp.Collections
 
             /// <summary>Create an array given the dimension and a generator function to compute the elements.</summary>
             ///
-            /// <remarks>Performs the operation in parallel using System.Threading.Parallel.For.
+            /// <remarks>Performs the operation in parallel using <see cref="M:System.Threading.Parallel.For" />.
             /// The order in which the given function is applied to indices is not specified.</remarks>
             ///
             /// <param name="count"></param>
             /// <param name="initializer"></param>
             ///
-            /// <returns>'T[]</returns>
+            /// <returns>The array of results.</returns>
             [<CompiledName("Initialize")>]
             val init : count:int -> initializer:(int -> 'T) -> 'T[]
 
             /// <summary>Split the collection into two collections, containing the 
             /// elements for which the given predicate returns "true" and "false"
             /// respectively </summary>
             ///
-            /// <remarks>Performs the operation in parallel using System.Threading.Parallel.For.
+            /// <remarks>Performs the operation in parallel using <see cref="M:System.Threading.Parallel.For" />.
             /// The order in which the given function is applied to indices is not specified.</remarks>
             ///
             /// <param name="predicate">The function to test the input elements.</param>
             /// <param name="array">The input array.</param>
             ///
-            /// <returns>'T[] * 'T[]</returns>
+            /// <returns>The two arrays of results.</returns>
             ///
             /// <exception cref="T:System.ArgumentNullException">Thrown when the input array is null.</exception>
             [<CompiledName("Partition")>]

src/fsharp/FSharp.Core/array2.fsi

@@ -8,7 +8,7 @@ namespace Microsoft.FSharp.Collections
 
     [<CompilationRepresentation(CompilationRepresentationFlags.ModuleSuffix)>]
     [<RequireQualifiedAccess>]
-    /// <summary>Basic operations on 2-dimensional arrays.</summary>
+    /// <summary>Contains operations for working with 2-dimensional arrays.</summary>
     ///
     /// <remarks>
     ///  <para>See also <a href="https://docs.microsoft.com/dotnet/fsharp/language-reference/arrays">F# Language Guide - Arrays</a>.</para>