Add examples for all library functions

[dsyme]

This was suggested in the F# community dugnad today

[dsyme]

One way to approach this is to add examples directly to the FSHarp.Core signature files, e.g. https://github.com/dotnet/fsharp/blob/master/src/fsharp/FSharp.Core/array2.fsi

There are pros and cons to doing this and you might that find that on your first PR to submit examples there is a discussion with the dotnet/fsharp engineers about whether this is the right place for examples to live.

Pro: right at the core of the ecosystem
Con: it takes a really long time for examples to flow through to generated docs because a new FSharp.Core is needed

Therefore we need a way to mix these examples in on an earlier path

[yvern]

Another kind of useful documentation/examples is using tests, as having "trivial" use cases of library functions tested, and have a way to look for these to insert as examples in final documentation, which doubles as consistency checks on api

[baronfel]

Just a note that the Con above might be mitigated somewhat by generating these docs from a self-built version of FSharp.Core, or pulled from a nightly feed or such. We just need the dll + associated XML file to generate the docs, and we've just defaulted to nuget for ease of acquisition.

[dsyme]

Yup agreed

[dsyme]

This is being tracked in dotnet/fsharp#12124