Traverse Lens Documentation Needs more Examples

[mortalapeman]

Description

The documentation around using a lens to update a collection type within a Record or other data structure could be clearer.

Repro steps

1. 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.

[gusty]

@mortalapeman

Thanks for reporting this.

Actually, this is a general problem, not specific to lenses: the (single) generic traverse functions have better type inference than the bigeneric one, for obvious reasons.

I agree, we should somehow reflect this in the docs to hint users hitting these problems to use the less generic versions.

Updating the lens docs is a good starting point. Go ahead and create a PR, it will be much appreciated.