`Tracking` - Docs - code examples for all members, functions and types in FSharp.Core

[dsyme]

Related to https://twitter.com/dsymetweets/status/1435311963781861376

This is a tracking issue for adding code examples for all functions, members and types in FSharp.Core.

• An example of the kind of thing that needs to be added is here: https://github.com/dotnet/fsharp/blob/main/src/fsharp/FSharp.Core/option.fsi#L136-L142.
• Once integrated, your examples will appear in the F# core library docs here https://fsharp.github.io/fsharp-core-docs/

Modules and types to do:

• [ ] FSharp.Core.Operators (mostly done in https://github.com/dotnet/fsharp/pull/12211)
• [x] FSharp.Core.String
• [x] FSharp.Core.Printf
• [x] FSharp.Core.Result
• [x] FSharp.Collections.Option
• [x] FSharp.Collections.ValueOption
• [x] FSharp.Collections.List
• [x] FSharp.Collections.Array
• [x] FSharp.Collections.Array.Parallel
• [x] FSharp.Collections.Seq
• [x] FSharp.Collections.Map (module)
• [x] FSharp.Collections.Map (type)
• [x] FSharp.Collections.Set
• [x] FSharp.Collections.Array2D
• [x] FSharp.Collections.Array3D
• [x] FSharp.Collections.Array4D
• [x] FSharp.Collections.HashIdentity
• [x] FSharp.Collections.ComparisonIdentity
• [ ] FSharp.Control.Async
• [ ] FSharp.Control.Async.CommonExtensions
• [x] FSharp.Control.Async.WebExtensions
• [ ] FSharp.Control.Event
• [x] FSharp.Control.Observable
• [ ] FSharp.Control.Task
• [x] FSharp.Quotations (started https://github.com/dotnet/fsharp/pull/12233)
• [ ] FSharp.Quotations.BasicPatterns (started https://github.com/dotnet/fsharp/pull/12233)
• [x] FSharp.Quotations.DerivedPatterns (started https://github.com/dotnet/fsharp/pull/12233)
• [ ] FSharp.Reflection.FSharpType
• [ ] FSharp.Reflection.FSharpValue
• [x] FSharp.Core.ExtraTopLevelOperators

[nhirschey]

I could take a stab at the Array module examples over the next several weeks. Some initial attempts: https://github.com/nhirschey/visualfsharp/commit/c9327e18573488a0f34517f9fabc19864c9fc9b4

Quick questions:

1. I see that one line examples are preferred. Should every example fit on one line? For beginners some things might be easier when split across multiple lines:
   • blit

     ///     let source = [| 1; 2; 3 |]
     ///     let sourceIndex = 0
     ///     let target = [| 0; 0; 0 |]
     ///     let targetIndex = 1
     ///     let count = 2
     ///     Array.blit source sourceIndex target targetIndex count 
     ///     target // evaluates to [| 0; 1; 2 |]

   • collect

     ///     let negative xs = xs |> Array.map (fun x -> -1 * x)
     ///     negative [| 1; 2 |] // evaluates to [-1; -2]
     ///     let ys = [| [| 1; 2 |]; [| 3; 4 |] |]
     ///     ys |> Array.collect negative // evaluates to [| -1; -2; -3; -4 |]

2. For functions like Array.averageBy, is it useful to show that it is equivalent to Array.map |> Array.average?

   [| 1.0; 2.0 |] |> Array.averageBy (fun x -> -1.0 * x) // evaluates to -1.5
   // this is equivalent to
   [| 1.0; 2.0 |] |> Array.map (fun x -> -1.0 * x) |> Array.average // evaluates to -1.5 

3. Should there be a column-width limit for examples? Wide examples might be harder to read in tooltips. Here's 2 versions of the same example using different numbers of columns:

[baronfel]

One thing I would really encourage people to do is add a lang=fsharp attribute to your code example XML tags. It's not strictly speaking to-spec (IMO the .Net XML Documentation spec is fairly lacking here), but it is used in several places (like FSharp.Formatting and FsAutoComplete) to provide users with language-aware syntax highlighting. Stealing from @nhirschey's examples a bit:

• blit:

  ///<example>
  /// The following sample shows how to copy the first two elements of an array to the 
  /// second and third positions of another array:
  ///
  ///<code lang="fsharp">
  ///     let source = [| 1; 2; 3 |]
  ///     let sourceIndex = 0
  ///     let target = [| 0; 0; 0 |]
  ///     let targetIndex = 1
  ///     let count = 2
  ///     Array.blit source sourceIndex target targetIndex count 
  ///     target // evaluates to [| 0; 1; 2 |]
  ///</code>
  ///</example>

[dsyme]

@baronfel thank you, yes! Is it used consistently in Fsharp.core today? If not please submit a pr to do that?

We should also mention that here

https://github.com/fsharp/fslang-design/blob/main/tooling/FST-1031-xmldoc-extensions.md

[dsyme]

@nhirschey thank you so much for kicking this off - the examples for Array can be reused for list and seq of course

1. multiline samples are definitely needed. Separate them out and take as much space as you need. For complex functions more discursive text may be needed.

2. Regarding equivalences - I think not.

3. Yes but I'm not sure what it should be. I expect 80. We will move to one-function-per-page docs for fsharp.core fsdocs eventually when much more space will be available so don't restrict up 60

[JYCabello]

Can I take Seq?

[MecuSorin]

I will use those as an exercise for my son in his attempt to learn F#. I am very serious. What he is not able/experienced enough, I will do them myself.

[dsyme]

@JYCabello The same examples should generally be used for Seq, Array, List (with minor adjustment) - so since @nhirschey is starting at the top of Array I recommend you start at the bottom of Seq, alphabetically?

[JYCabello]

I will do. Starting tomorrow.

[MecuStefan]

String is done, working on the List at the moment

[JYCabello]

Got to ask: The examples go between the docs for the params and the return type for any particular reason?

[dsyme]

Got to ask: The examples go between the docs for the params and the return type for any particular reason?

No reason - they should be come after I agree. Please feel free to submit a PR doing a re-ordering

[JYCabello]

Great, will do after that. I just noticed that you specifically mentioned to start on the bottom and I started on the top. Sorry about that. I'll make a PR in a bit to have some progress in and to get some feedback.

[MaxWilson]

I will take Set and Map.

[JustinWick]

I'm going to give FSharp.Control.Async a stab, should be fun. Probably won't be able to get to the extensions, though.

The examples for these modules must necessarily be nontrivial given the differences in timing behavior exhibited by some of the Async functions. I would like to have my documentation peer-reviewed while in progress rather than having it rejected outright as too obtuse, is there an established way to do this? Maybe some kind of WIP PR?

[dsyme]

Thank you Max! Thank you Justin!

[JustinWick]

Alright, I'm up to 13 examples for Async, I'm expecting to create a PR by Thursday. Do I just file the PR and then have peer review there?

[dsyme]

Alright, I'm up to 13 examples for Async, I'm expecting to create a PR by Thursday. Do I just file the PR and then have peer review there?

Fantastic! Yes, that's right

[sgoguen]

I will take FSharp.Core.Operators

[dsyme]

@sgoguen Great!

[dsyme]

https://github.com/dotnet/fsharp/pull/12161 contains work to add <example-tbd> to all the places we need examples, except in Operators.

@justinwick There may be a few minor merge conflicts if you've done more work, e.g. in Async - they should be easy to resolve - perhaps before merging first reduce the indenting in async.fsi to match the change in that PR, then the conflicts will be easy to resolve.

[JustinWick]

https://github.com/dotnet/fsharp/pull/12161 contains work to add <example-tbd> to all the places we need examples, except in Operators.

@justinwick There may be a few minor merge conflicts if you've done more work, e.g. in Async - they should be easy to resolve - perhaps before merging first reduce the indenting in async.fsi to match the change in that PR, then the conflicts will be easy to resolve.

I am just about done with examples but I forgot to transfer them to my laptop before leaving for a trip. I'll be back Tuesday and can merge them into the PR Wednesday, is that going to cause any issues?

[dsyme]

I am just about done with examples but I forgot to transfer them to my laptop before leaving for a trip. I'll be back Tuesday and can merge them into the PR Wednesday, is that going to cause any issues?

@JustinWick It'll be fine, we won't start on Async - thanks!

[JYCabello]

12161 contains work to add <example-tbd> to all the places we need examples, except in Operators.

@JustinWick There may be a few minor merge conflicts if you've done more work, e.g. in Async - they should be easy to resolve - perhaps before merging first reduce the indenting in async.fsi to match the change in that PR, then the conflicts will be easy to resolve.

Yeah, I hit a lot of merge conflicts and each one of them was simple.

[sgoguen]

I've done a number of examples in FSharp.Core.Operators but I'm slow on getting them all finished.

Should I push a PR for what I have so others can add?

https://github.com/sgoguen/fsharp/tree/dev/fsharp-core-examples

[dsyme]

Yes please! those look great!

[JYCabello]

Haven't forgotten about this, will get back on it ending this week.

[dsyme]

Linking https://github.com/dotnet/fsharp/pull/12211

[dsyme]

Also linking https://github.com/dotnet/fsharp/pull/12218 where I'm adding examples to the rest of the Array module

[dsyme]

With this PR we are at:

• 309 examples completed (some multiple per item)
• 766 example-tbd remaining in FSharp.Core

[dsyme]

@JustinWick Do you have the examples for Async in progress? Thanks. I'd love to get those in

[markpattison]

I'll pick up FSharp.Collections.Map.

[dsyme]

I'll pick up FSharp.Collections.Map.

Thank you!

[JYCabello]

I'm continuing with seq, I expect to have a PR next week.

[dsyme]

@JYCabello We may conflict - I'm going through all of list, array, seq and completing them

How many more entries have you done so far?

[dsyme]

Find me on FSSF slack if you want to chat to coordinate

[JustinWick]

@JustinWick Do you have the examples for Async in progress? Thanks. I'd love to get those in

I do indeed! Should I be merging into a PR somewhere, or making my own? I'm a bit new to this part of GH.

[JYCabello]

Taking valueoption instead

[dsyme]

I do indeed! Should I be merging into a PR somewhere, or making my own? I'm a bit new to this part of GH.

Make a new PR to this repo main branch, thanks

[dsyme]

List, Seq, Array are now all complete in #12221. After this PR the status is:

• 514 completed examples
• 618 undocumented <example-tbd>

[dsyme]

HashIdentity and ComparisonIdentity done in https://github.com/dotnet/fsharp/pull/12223

[dsyme]

Printf also done in #12223. After this PR the status is:

• 542 completed examples
• 581 undocumented <example-tbd>

[dsyme]

Map and much of Operators have been compelted in #12228 and #12233. After these PRs the status is:

• 777 completed examples
• 468 undocumented <example-tbd>

To get a feel for what a difference this makes, please check out completed pages linked in the tracking list at the top of the PR

[dsyme]

After #12233 the score is

• 860 completed examples
• 381 undocumented <example-tbd>

[markpattison]

I should be able to do ValueOption quickly.

Noticed in the Option examples (I will fix) that the following actually throws FS0030:

(None, None) ||> Option.orElse // evaluates to None

Same for a few other cases.

[JYCabello]

I was planning to do value option this week precisely due to that, but my days became a comedy flick. Feel free to take over, should be mostly copy pasta from option.

[dsyme]

Thank for doing ValueOption Mark!

The main ones remaining are Async, FSharpType, FSharpValue, plus some more quotation examples, also finishing FSharp.Core.Operators

@JustinWick how are the async samples coming along? If you want to PR what you can have we can help you iterate?

[dsyme]

@JustinWick any progress on the async samples? It would be great to get this whole work item closed out, we've made such good progress in F# 6

[JustinWick]

Sorry for dropping off the face of the earth, work exploded.

And yes, I have the day off finally so I can put my PR together! Will have a candidate in by end of the weekend Boston time.

On Fri, Nov 19, 2021 at 7:47 AM Don Syme @.***> wrote:

@JustinWick https://github.com/JustinWick any progress on the async samples? It would be great to get this whole work item closed out, we've made such good progress in F# 6

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/dotnet/fsharp/issues/12124#issuecomment-974042864, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAQ4TLMSETJANDPT5MH6X3UMZBPPANCNFSM5DS7N3IQ .

[dsyme]

@JustinWick Great! Anything you have would be good, so we can avoid overlap

[JustinWick]

@dsyme: Thank you very much for your patience, I bit off a bit much for my first contribution. Still this was a great way to learn the Async module--at my day job I have to use the Ply library for performance reasons, but Async makes a lot of things neater when that's not an issue.

I've got all my ducks in a row here and filed my PR #12477. It's not complete, as there were a few functions that were not there when I started on F# 5, are legacy functions, or for which I wasn't immediately able to think of an example. Still, I've added 22 examples, which should be a solid start.