Review all current XML doc content for FSharp.Core

[dsyme]

The quality of content coming from FSharp.Core.XML is not where it needs to be.

I'd recommend we go over every type, module, function, property and method in FSharp.Core and review its XML content, and adjust the XML /// comments if needed. We should do this even if the original hand-written documentation for FSharp.Core is restored by Microsoft as it improves intellisense in any case

I believe an important addition is to systematically add links back to the F# Language Guide, e.g.

/// <remarks>
///  See also <a href="https://docs.microsoft.com/dotnet/fsharp/language-reference/arrays">F# Language Guide - Arrays</a>.
/// </remarks>

This helps guide people who want to learn back to the best quality documentation for an area. Almost every part of FSharp.Core relates to some part of the language guide.

Here's a review list.

FSharp.Collections

• Array
• Array2D
• Array3D
• Array4D
• ComparisonIdentity
• HashIdentity
• 'T list
• Map
• Map<'Key, 'Value>
• ResizeArray<'T>
• Seq
• seq<'T>
• Set
• Set<'T>

FSharp.Control

• Async
• Async<'T>
• AsyncActivation<'T>
• AsyncBuilder
• AsyncPrimitives
• AsyncReplyChannel<'Reply>
• AsyncReturn
• CommonExtensions
• DelegateEvent<'Delegate>
• Event  
• Event<'T>
• Event<'Delegate, 'Args>
• Handler<'T>
• IDelegateEvent<'Delegate>
• IEvent<'T>
• IEvent<'Delegate, 'Args>
• Lazy<'T>
• LazyExtensions
• MailboxProcessor<'Msg>
• Observable
• WebExtensions

FSharp.Core (excluding attributes and abbreviations)

• ExtraTopLevelOperators
• Format<'Printer, 'State, 'Residue, 'Result>
• FSharpFunc<'T, 'U>
• FSharpTypeFunc
• FuncConvert
• LanguagePrimitives
• MatchFailureException
• Operators
• OptimizedClosures
• Option
• 'T option
• Option<'T>
• OptionalArgumentAttribute
• outref<'T>
• Printf
• 'T ref
• Ref<'T>
• Result
• Result<'T, 'TError>
• String
• ValueOption
• ValueOption<'T>
• voidptr
• 'T voption

FSharp.Core.CompilerServices

• GeneratedSequenceBase<'T>
• IProvidedNamespace
• ITypeProvider
• ITypeProvider2
• MeasureInverse<'Measure>
• MeasureOne
• MeasureProduct<'Measure1, 'Measure2>
• RuntimeHelpers
• TypeProviderConfig

FSharp.Linq

• Nullable
• NullableOperators
• QueryBuilder
• QuerySource<'T, 'Q>

FSharp.Linq.RuntimeHelpers Namespace

• Grouping<'K, 'T>
• LeafExpressionConverter

FSharp.NativeInterop Namespace

• NativePtr

FSharp.Quotations

• DerivedPatterns
• Expr
• Expr<'T>
• ExprShape
• Patterns
• Var

FSharp.Reflection

• FSharpReflectionExtensions  
• FSharpType
• FSharpValue
• UnionCaseInfo

[jmhickman]

I'm quite new and don't have tons and tons of time, but what could I do to help improve this exactly? If it's just a matter of going through a file and correcting formatting to some guideline, I think I could handle that.

[cartermp]

@jmhickman The repo for them is here: https://github.com/dotnet/fsharp

And the files where the xml docs content lives is int he *.fsi files here: https://github.com/dotnet/fsharp/tree/main/src/fsharp/FSharp.Core

[cartermp]

You can see an example of some of the more uniform changes that could be made here: https://github.com/dotnet/fsharp/blob/main/src/fsharp/FSharp.Core/array.fsi#L10

[dsyme]

@jmhickman Another place to start is #63

If you follow the instructions in the README.md then the list of diagnostics is produced and you can iterate. You can then edit under fsharp/src/fsharp/FSharp.Core/... in your build to improve things. Then submit the fixes to dotnet/fsharp and we iterate.

[dsyme]

This is all being tracked here now. dotnet/fsharp#12124

Huge progress has been made and 60% of public entry points to FSharp.Core now have examples, with the rest in progress