FSharpPlus
FSharpPlus copied to clipboard
Traverse Lens Documentation Needs more Examples
Description
The documentation around using a lens to update a collection type within a Record or other data structure could be clearer.
Repro steps
- Install FSharpPlus and try to run the code below:
#r "nuget: FSharpPlus"
open FSharpPlus
open FSharpPlus.Lens
open FSharpPlus.Data
let data = (1, ["a";"b";"c"])
// Simple working example
let result1 = over (_2 << List.traverse) String.toUpper data
// The first thing one might try based on the documentation only to be greeted with
// mystifying compiler error
let result2 = over (_2 << traverse) String.toUpper data
Expected behavior
Documentation should remind the user that when trying to use items
or traverse
as part of a lens function composition, they should reference the typed version of traverse
that matches their data structure. It would also be helpful to note that items
is just an alias of traverse
.
Actual behavior
All documentation examples use the polymorphic traverse
function. Even the unit tests barely provide a decent example since the one example use of traverse is with nested lists in lists. I would image that most real world use of traverse would involve a Record or Tuple as the top level Model object (good old Elmish) and if one is just skimming through the tests trying to learn about lenses, they might not make the connection.
Known workarounds
Bang your head against the compiler until you gain insight.
Related information
- Windows 10 / WSL Ubuntiu
- .CoreCLR 6.0
Next Steps
I do not mind creating a PR to update the docs and add some more tests that are basically just examples more so than anything that covers a special corner case. Just let me know if the team is interested in making the changes and I will do the work.