Skip to content

Improve docs for FSharp.Core #9880

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 7, 2020
Merged

Improve docs for FSharp.Core #9880

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4113de0
various doc improvements
dsyme Aug 6, 2020
2e30d90
don't use uppercase since in cref it is shown as text
dsyme Aug 7, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions src/fsharp/FSharp.Core/Linq.fsi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
24 changes: 16 additions & 8 deletions src/fsharp/FSharp.Core/MutableTuple.fs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
21 changes: 20 additions & 1 deletion src/fsharp/FSharp.Core/Query.fsi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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>
Expand All @@ -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>
Expand Down
52 changes: 26 additions & 26 deletions src/fsharp/FSharp.Core/array.fsi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>.
Expand Down Expand Up @@ -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>
///
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
///
Expand All @@ -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>
///
Expand All @@ -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>
Expand Down Expand Up @@ -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>
Expand All @@ -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")>]
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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")>]
Expand Down
2 changes: 1 addition & 1 deletion src/fsharp/FSharp.Core/array2.fsi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
Loading