Feature/docs improvements (#9854)

* improve xml doc spacing

* improve cref nodes

* fix broken xml doc

* fix more crefs

* doc improvements

* improve docs for FSHarp.Core

Author: dsyme

src/fsharp/FSharp.Core/array.fsi

@@ -8,6 +8,10 @@ namespace Microsoft.FSharp.Collections
     open System.Collections.Generic
 
     /// <summary>Basic operations on arrays.</summary>
+    ///
+    /// <remarks>
+    ///  See also <a href="https://docs.microsoft.com/dotnet/fsharp/language-reference/arrays">F# Language Guide - Arrays</a>.
+    /// </remarks>
     [<CompilationRepresentation(CompilationRepresentationFlags.ModuleSuffix)>]
     [<RequireQualifiedAccess>]
     module Array = 

src/fsharp/FSharp.Core/array2.fsi

@@ -10,15 +10,19 @@ namespace Microsoft.FSharp.Collections
     [<RequireQualifiedAccess>]
     /// <summary>Basic operations on 2-dimensional arrays.</summary>
     ///
-    /// <remarks>F# and CLI multi-dimensional arrays are typically zero-based. 
+    /// <remarks>
+    ///  <para>See also <a href="https://docs.microsoft.com/dotnet/fsharp/language-reference/arrays">F# Language Guide - Arrays</a>.</para>
+    /// 
+    /// <para>F# and CLI multi-dimensional arrays are typically zero-based. 
     /// However, CLI multi-dimensional arrays used in conjunction with external
     /// libraries (e.g. libraries associated with Visual Basic) be 
     /// non-zero based, using a potentially different base for each dimension.
     /// The operations in this module will accept such arrays, and
     /// the basing on an input array will be propagated to a matching output
     /// array on the <c>Array2D.map</c> and <c>Array2D.mapi</c> operations.
     /// Non-zero-based arrays can also be created using <c>Array2D.zeroCreateBased</c>, 
-    /// <c>Array2D.createBased</c> and <c>Array2D.initBased</c>.</remarks>
+    /// <c>Array2D.createBased</c> and <c>Array2D.initBased</c>.</para>
+    /// </remarks>
     module Array2D = 
 
         /// <summary>Fetches the base-index for the first dimension of the array.</summary>

src/fsharp/FSharp.Core/array3.fsi

@@ -10,6 +10,10 @@ namespace Microsoft.FSharp.Collections
     [<CompilationRepresentation(CompilationRepresentationFlags.ModuleSuffix)>]
     [<RequireQualifiedAccess>]
     /// <summary>Basic operations on rank 3 arrays.</summary>
+    ///
+    /// <remarks>
+    ///  See also <a href="https://docs.microsoft.com/dotnet/fsharp/language-reference/arrays">F# Language Guide - Arrays</a>.
+    /// </remarks>
     module Array3D =
 
         /// <summary>Creates an array whose elements are all initially the given value.</summary>

src/fsharp/FSharp.Core/async.fsi

@@ -11,24 +11,25 @@ namespace Microsoft.FSharp.Control
     open Microsoft.FSharp.Control
     open Microsoft.FSharp.Collections
 
-    /// <summary>A compositional asynchronous computation, which, when run, will eventually produce a value 
-    /// of type T, or else raises an exception.</summary> 
+    /// <summary>
+    /// An asynchronous computation, which, when run, will eventually produce a value  of type T, or else raises an exception.
+    /// </summary> 
     ///
-    /// <remarks>Asynchronous computations are normally specified using an F# computation expression.
+    /// <remarks>
+    ///  This type has no members. Asynchronous computations are normally specified either by using an async expression
+    ///  or the static methods in the <see cref="T:Microsoft.FSharp.Control.Async"/> type.
     ///
-    /// When run, asynchronous computations have two modes: as a work item (executing synchronous 
-    /// code), or as a wait item (waiting for an event or I/O completion). 
-    ///
-    /// When run, asynchronous computations can be governed by CancellationToken. This can usually 
-    /// be specified when the async computation is started. The associated CancellationTokenSource 
-    /// may be used to cancel the asynchronous computation. Asynchronous computations built using 
-    /// computation expressions can check the cancellation condition regularly. Synchronous 
-    /// computations within an asynchronous computation do not automatically check this condition.</remarks> 
+    ///  See also <a href="https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/asynchronous-workflows">F# Language Guide - Async Workflows</a>.
+    /// </remarks> 
      
     [<Sealed; NoEquality; NoComparison; CompiledName("FSharpAsync`1")>]
     type Async<'T>
 
-    /// <summary>This static class holds members for creating and manipulating asynchronous computations.</summary>
+    /// <summary>Holds static members for creating and manipulating asynchronous computations.</summary>
+    ///
+    /// <remarks>
+    ///  See also <a href="https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/asynchronous-workflows">F# Language Guide - Async Workflows</a>.
+    /// </remarks>
 
     [<Sealed>]
     [<CompiledName("FSharpAsync")>]
@@ -47,7 +48,7 @@ namespace Microsoft.FSharp.Control
         /// <param name="computation">The computation to run.</param>
         /// <param name="timeout">The amount of time in milliseconds to wait for the result of the
         /// computation before raising a <see cref="T:System.TimeoutException"/>.  If no value is provided
-        /// for timeout then a default of -1 is used to correspond to System.Threading.Timeout.Infinite.
+        /// for timeout then a default of -1 is used to correspond to <see cref="F:System.Threading.Timeout.Infinite"/>.
         /// If a cancellable cancellationToken is provided, timeout parameter will be ignored</param>
         /// <param name="cancellationToken">The cancellation token to be associated with the computation.
         /// If one is not supplied, the default cancellation token is used.</param>

src/fsharp/FSharp.Core/collections.fsi

@@ -9,47 +9,63 @@ namespace Microsoft.FSharp.Collections
     open System
     open System.Collections.Generic
 
-    /// <summary>Common notions of comparison identity used with sorted data structures.</summary>
+    /// <summary>Common notions of value ordering implementing the <see cref="T:System.Collections.Generic.IComparer`1"/> 
+    /// interface, for constructing sorted data structures and performing sorting operations.</summary>
     module ComparisonIdentity = 
 
-        /// <summary>Structural comparison.  Compare using Operators.compare.</summary>
+        /// <summary>Get an implementation of comparison semantics using structural comparison.</summary>
+        ///
+        /// <returns>An object implementing <see cref="T:System.Collections.Generic.IComparer`1"/> using <see cref="M:Microsoft.FSharp.Core.Operators.compare"/>.</returns>
         val inline Structural<'T> : IComparer<'T> when 'T : comparison 
 
-        /// <summary>Non-structural comparison.  Compare using NonStructuralComparison.compare.</summary>
+        /// <summary>Get an implementation of comparison semantics using non-structural comparison.</summary>
+        ///
+        /// <returns>An object implementing <see cref="T:System.Collections.Generic.IComparer`1"/> using <see cref="M:Microsoft.FSharp.Core.Operators.NonStructuralComparison.compare"/>.</returns>
         val inline NonStructural< ^T > : IComparer< ^T > when ^T : (static member ( < ) : ^T * ^T    -> bool) and ^T : (static member ( > ) : ^T * ^T    -> bool) 
 
-        /// <summary>Compare using the given comparer function.</summary>
+        /// <summary>Get an implementation of comparison semantics using the given function.</summary>
+        ///
         /// <param name="comparer">A function to compare two values.</param>
         ///
-        /// <returns>An object implementing IComparer using the supplied comparer.</returns>
+        /// <returns>An object implementing <see cref="T:System.Collections.Generic.IComparer`1"/> using the supplied function.</returns>
         val FromFunction : comparer:('T -> 'T -> int) -> IComparer<'T>  
 
-    /// <summary>Common notions of value identity used with hash tables.</summary>
+    /// <summary>Common notions of value identity implementing the <see cref="T:System.Collections.Generic.IEqualityComparer`1"/> 
+    /// interface, for constructing <see cref="T:System.Collections.Generic.Dictionary`2"/> objects and other collections</summary>
     module HashIdentity = 
 
-        /// <summary>Structural hashing.  Hash using Operators.(=) and Operators.hash.</summary>
+        /// <summary>Get an implementation of equality semantics using structural equality and structural hashing.</summary>
+        ///
+        /// <returns>An object implementing <see cref="T:System.Collections.Generic.IEqualityComparer`1"/> using <see cref="M:Microsoft.FSharp.Core.Operators.op_Equality"/> and <see cref="M:Microsoft.FSharp.Core.Operators.hash"/>.</returns>
         val inline Structural<'T> : IEqualityComparer<'T>  when 'T : equality
 
-        /// <summary>Non-structural hashing.  Equality using NonStructuralComparison.(=) and NonStructuralComparison.hash.</summary>
+        /// <summary>Get an implementation of equality semantics using non-structural equality and non-structural hashing.</summary>
+        ///
+        /// <returns>
+        ///  An object implementing <see cref="T:System.Collections.Generic.IEqualityComparer`1"/> using <see cref="M:Microsoft.FSharp.Core.Operators.NonStructuralComparison.op_Equality"/>
+        ///  and <see cref="M:Microsoft.FSharp.Core.Operators.NonStructuralComparison.hash"/>.
+        /// </returns>
         val inline NonStructural<'T> : IEqualityComparer< ^T >  when ^T : equality and ^T  : (static member ( = ) : ^T * ^T    -> bool) 
 
+        /// <summary>Get an implementation of equality semantics semantics using structural equality and structural hashing.</summary>
+        ///
+        /// <returns>An object implementing <see cref="T:System.Collections.Generic.IEqualityComparer`1"/>.</returns>
         val inline LimitedStructural<'T> : limit: int -> IEqualityComparer<'T>  when 'T : equality
 
-        /// <summary>Physical hashing (hash on reference identity of objects, and the contents of value types).  
-        /// Hash using LanguagePrimitives.PhysicalEquality and LanguagePrimitives.PhysicalHash,
-        /// That is, for value types use GetHashCode and Object.Equals (if no other optimization available),
-        /// and for reference types use System.Runtime.CompilerServices.RuntimeHelpers.GetHashCode and 
-        /// reference equality.</summary>
+        /// <summary>Get an implementation of equality semantics using reference equality and reference hashing.</summary>
+        ///
+        /// <returns>
+        ///  An object implementing <see cref="T:System.Collections.Generic.IEqualityComparer`1"/> using <see cref="M:Microsoft.FSharp.Core.LanguagePrimitives.PhysicalEquality"/>
+        ///  and <see cref="M:Microsoft.FSharp.Core.LanguagePrimitives.PhysicalHash"/>.
+        /// </returns>
         val Reference<'T>   : IEqualityComparer<'T>  when 'T : not struct 
 
-        /// <summary>Hash using the given hashing and equality functions.</summary>
+        /// <summary>Get an implementation of equality semantics using the given functions.</summary>
         ///
         /// <param name="hasher">A function to generate a hash code from a value.</param>
         /// <param name="equality">A function to test equality of two values.</param>
         ///
-        /// <returns>An object implementing IEqualityComparer using the supplied functions.</returns>
-
-        // inline justification: allows inlining of hash functions 
+        /// <returns>An object implementing <see cref="T:System.Collections.Generic.IEqualityComparer`1"/> using the given functions.</returns>
         val inline FromFunctions<'T> : hasher:('T -> int) -> equality:('T -> 'T -> bool) -> IEqualityComparer<'T> 
 
 

src/fsharp/FSharp.Core/map.fsi

@@ -7,10 +7,10 @@ namespace Microsoft.FSharp.Collections
     open Microsoft.FSharp.Core
     open Microsoft.FSharp.Collections
 
-    /// <summary>Immutable maps. Keys are ordered by F# generic comparison.</summary>
+    /// <summary>Immutable maps based on binary trees, where keys are ordered by F# generic comparison. By default
+    /// comparison is the F# structural comparison function or uses implementations of the IComparable interface on key values.</summary>
     /// 
-    /// <remarks>Maps based on generic comparison are efficient for small keys. They are not a suitable choice if keys are recursive data structures 
-    /// or if keys require bespoke comparison semantics.
+    /// <remarks>See the <see cref="T:Microsoft.FSharp.Collections.MapModule"/> module for further operations on maps.
     ///
     /// All members of this class are thread-safe and may be used concurrently from multiple threads.</remarks>
     [<CompiledName("FSharpMap`2")>]
@@ -93,7 +93,7 @@ namespace Microsoft.FSharp.Collections
         interface IReadOnlyDictionary<'Key,'Value>
         override Equals : obj -> bool
 
-    /// <summary>Functional programming operators related to the <c>Map&lt;_,_&gt;</c> type.</summary>
+    /// <summary>Basic operations on values of type <see cref="T:Microsoft.FSharp.Collections.Map`2"/>.</summary>
     [<CompilationRepresentation(CompilationRepresentationFlags.ModuleSuffix)>]
     [<RequireQualifiedAccess>]
     /// <summary>Basic operations on values of type <see cref="T:Microsoft.FSharp.Collections.Map`2"/>.</summary>

src/fsharp/FSharp.Core/prim-types.fsi

@@ -2256,17 +2256,28 @@ namespace Microsoft.FSharp.Collections
         interface IReadOnlyCollection<'T>
         interface IReadOnlyList<'T>
 
-    /// <summary>An abbreviation for the type of immutable singly-linked lists. </summary>
+    /// <summary>The type of immutable singly-linked lists. </summary>
     ///
-    /// <remarks>Use the constructors <c>[]</c> and <c>::</c> (infix) to create values of this type, or
-    /// the notation <c>[1;2;3]</c>. Use the values in the <c>List</c> module to manipulate 
-    /// values of this type, or pattern match against the values directly.</remarks>
+    /// <remarks>See the <see cref="T:Microsoft.FSharp.Collections.ListModule"/> module for further operations related to lists.
+    ///
+    /// Use the constructors <c>[]</c> and <c>::</c> (infix) to create values of this type, or
+    /// the notation <c>[1; 2; 3]</c>. Use the values in the <c>List</c> module to manipulate 
+    /// values of this type, or pattern match against the values directly.
+    ///
+    ///  See also <a href="https://docs.microsoft.com/dotnet/fsharp/language-reference/lists">F# Language Guide - Lists</a>.
+    /// </remarks>
     and 'T list = List<'T>
 
     /// <summary>An abbreviation for the CLI type <see cref="T:System.Collections.Generic.List`1"/></summary>
     type ResizeArray<'T> = System.Collections.Generic.List<'T>
 
     /// <summary>An abbreviation for the CLI type <see cref="T:System.Collections.Generic.IEnumerable`1"/></summary>
+    ///
+    /// <remarks>
+    ///  See the <see cref="T:Microsoft.FSharp.Collections.SeqModule"/> module for further operations related to sequences.
+    ///
+    ///  See also <a href="https://docs.microsoft.com/dotnet/fsharp/language-reference/sequences">F# Language Guide - Sequences</a>.
+    ///</remarks>
     type seq<'T> = IEnumerable<'T>
 
 namespace Microsoft.FSharp.Core