Tracking issues for code examples for all members, functions and types in FSharp...
source link: https://github.com/dotnet/fsharp/issues/12124
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
New issue
Tracking issues for code examples for all members, functions and types in FSharp.Core #12124
1 of 25 tasks
dsyme opened this issue 6 days ago · 14 comments
Comments
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.
Modules and types to do:
- FSharp.Core.Operators
- FSharp.Core.String
- FSharp.Core.Printf
- FSharp.Collections.Option
- FSharp.Collections.List
- FSharp.Collections.Array
- FSharp.Collections.Seq
- FSharp.Collections.Map
- FSharp.Collections.Set
- FSharp.Collections.Array2D
- FSharp.Collections.Array3D
- FSharp.Collections.Array4D
- FSharp.Collections.HashIdentity
- FSharp.Collections.ComparisonIdentity
- FSharp.Control.Async
- FSharp.Control.Async.CommonExtensions
- FSharp.Control.Async.WebExtensions
- FSharp.Control.Event
- FSharp.Control.Observable
- FSharp.Control.Task
- FSharp.Quotations
- FSharp.Quotations.BasicPatterns
- FSharp.Quotations.DerivedPatterns
- FSharp.Reflection.FSharpType
- FSharp.Reflection.FSharpValue
I could take a stab at the Array module examples over the next several weeks. Some initial attempts: nhirschey@c9327e1
Quick questions:
- 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 |]
- blit
- For functions like
Array.averageBy
, is it useful to show that it is equivalent toArray.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
- 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:
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>
@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
@nhirschey thank you so much for kicking this off - the examples for Array can be reused for list and seq of course
-
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.
-
Regarding equivalences - I think not.
-
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
Can I take Seq?
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.
@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?
I will do. Starting tomorrow.
String
is done, working on the List
at the moment
Got to ask: The examples go between the docs for the params and the return type for any particular reason?
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
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.
I will take Set and Map.
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?
No one assigned
None yet
No milestone
Successfully merging a pull request may close this issue.
None yet
Recommend
-
12
FSharp.SystemTextJson This library provides support for F# types to System.Text.Json. It adds support for the following types: ...
-
5
Jimmy Byrd on Twitter: "FsToolkit.ErrorHandling 2.6.0 is out! Adds orElse and orElseWith functions! #fsharp #dotnet #dotnetcore https://t.co/vp5zTQIYcL"Don’t miss what’s happeningPeople on Twitter are the first to know.
-
18
Conversation#fsharp folk, I have approved this F# library suggestion. Would anyone like to implement and perf test these for FSharp.Core?
-
5
Issues · dotnet/fsharp · GitHub Clear current search query, filters, and sorts Author Label...
-
3
Issues · fsprojects/FSharp.Formatting · GitHub Clear current search query, filters, and sorts Author...
-
0
Issues · MatrixSolutions/FSharp.Data.JsonValidation · GitHub Clear current search query, filters, and sorts ...
-
5
Issues · theburningmonk/FSharp.Markdown.Pdf · GitHub Clear current search query, filters, and sorts Auth...
-
6
Issues · ionide/ionide-vscode-fsharp · GitHub Clear current search query, filters, and sorts Author...
-
5
Issues · fslaborg/FSharp.Charting · GitHub Clear current search query, filters, and sorts Author L...
-
5
logf - printf-style functions for ILogger This library implements printf-style logging functions for any Microsoft.Extensions.Logging.ILogger, allowing you to log in an F# style with the full power of structured logging. Here's an example...
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK