Inconsistent type signature of map(N) functions

[rl-king]

Overview

All map functions in core which have an any return value

Array.map : (a -> b) -> Array a -> Array b
Dict.map : (comparable -> a -> b) -> Dict comparable a -> Dict comparable b
Decode.map : (a -> value) -> Decoder a -> Decoder value
List.map : (a -> b) -> List a -> List b
Maybe.map : (a -> b) -> Maybe a -> Maybe b
Cmd.map : (a -> msg) -> Cmd a -> Cmd msg
Sub.map : (a -> msg) -> Sub a -> Sub msg
Random.map : (a -> b) -> Generator a -> Generator b
Result.map : (a -> value) -> Result x a -> Result x value
Set.map : (comparable -> comparable2) -> Set comparable -> Set comparable2
Task.map : (a -> b) -> Task x a -> Task x b

Map(N)

Decode.map2 : (a -> b -> value) -> Decoder a -> Decoder b -> Decoder value
List.map2 : (a -> b -> result) -> List a -> List b -> List result
Maybe.map2 : (a -> b -> value) -> Maybe a -> Maybe b -> Maybe value
Random.map2 : (a -> b -> c) -> Generator a -> Generator b -> Generator c
Result.map2 : (a -> b -> value) -> Result x a -> Result x b -> Result x value
Task.map2 : (a -> b -> result) -> Task x a -> Task x b -> Task x result

Notes

• Some named any types are actually helpful, like msg
• There is a difference in naming between map and map(N)
• Having result as a return value in List.map(N) and Task.map(N) could be confusing since a Result type exists
• Random.map(N) is the only map(N) that returns a single character any

[process-bot]

Thanks for the issue! Make sure it satisfies this checklist. My human colleagues will appreciate it!

Here is what to expect next, and if anyone wants to comment, keep these things in mind.

[process-bot]

Thanks for the issue! Make sure it satisfies this checklist. My human colleagues will appreciate it!

Here is what to expect next, and if anyone wants to comment, keep these things in mind.

[rl-king]

I noticed this when making a PR for the List.map(N) functions but then realised it's not the only place this occurs. I filled this issue quite specific but this might be part of a larger revision where It's best to find a default way of defining these throughout core in general.

[rl-king]

I noticed this when making a PR for the List.map(N) functions but then realised it's not the only place this occurs. I filled this issue quite specific but this might be part of a larger revision where It's best to find a default way of defining these throughout core in general.

[evancz]

I'm not sure I understand this issue. Are you saying you were personally confused? Or that other people might be confused?

[evancz]

I'm not sure I understand this issue. Are you saying you were personally confused? Or that other people might be confused?

[rl-king]

Other people might be confused,

Focussing on just the List signatures.

I noticed that that List.map returns a List b but List.map2 returns a List result. That got me wondering if it would be more helpful to understand if the signatures are more similar?
List.map : (a -> b) -> List a -> List b
List.map2 : (a -> b -> c) -> List a -> List b -> List c
vs
List.map : (a -> b) -> List a -> List b
List.map2 : (a -> b -> result) -> List a -> List b -> List result

Also, I can imagine someone that hasn't gotten used to how to read the type signatures yet might read the docs and interpret
List.map2 : (a -> b -> result) -> List a -> List b -> List result
as
List.map2 : (a -> b -> Result) -> List a -> List b -> List Result

[rl-king]

Other people might be confused,

Focussing on just the List signatures.

I noticed that that List.map returns a List b but List.map2 returns a List result. That got me wondering if it would be more helpful to understand if the signatures are more similar?
List.map : (a -> b) -> List a -> List b
List.map2 : (a -> b -> c) -> List a -> List b -> List c
vs
List.map : (a -> b) -> List a -> List b
List.map2 : (a -> b -> result) -> List a -> List b -> List result

Also, I can imagine someone that hasn't gotten used to how to read the type signatures yet might read the docs and interpret
List.map2 : (a -> b -> result) -> List a -> List b -> List result
as
List.map2 : (a -> b -> Result) -> List a -> List b -> List Result

[evancz]

I'd want to find such a person before making the change.

When I first wrote the docs, I did the traditional a b c thing, and I thought it was really weird looking to see them all in a row. "This one returns c but in that one c is an argument! What?" I also think that people seeing most of these functions will not know about Result yet, so they will just read it as "the result of the function"

Point is, it is that way based on a learning theory, and I would want to disprove the theory by seeing beginners struggle with this before changing. It may be that none of the suggestions that make sense to us actually help with the confusion they are (or are not) experiencing.

[evancz]

I'd want to find such a person before making the change.

When I first wrote the docs, I did the traditional a b c thing, and I thought it was really weird looking to see them all in a row. "This one returns c but in that one c is an argument! What?" I also think that people seeing most of these functions will not know about Result yet, so they will just read it as "the result of the function"

Point is, it is that way based on a learning theory, and I would want to disprove the theory by seeing beginners struggle with this before changing. It may be that none of the suggestions that make sense to us actually help with the confusion they are (or are not) experiencing.