Task docs

[rtfeldman]

This revises the Task docs to be more helpful to elm-effects users searching for how to obtain tasks that can never fail.

The resulting docs json file: task-docs.json

[vilterp]

Having a type variable never here and a type Never in elm-effects might be confusing. Maybe an argument for moving the Never type to core and using it here?

[vilterp]

Having a type variable never here and a type Never in elm-effects might be confusing. Maybe an argument for moving the Never type to core and using it here?

[rgrempel]

I might be misunderstanding, but I believe the lower-case never is just documentation -- it essentially means that the error type is unconstrained -- since it never happens, the type system need not care about it. Whereas the upper-case Never is, technically, an actual type. So (and I may be missing something here) it seems like one would be over-constraining the type checker by making Task.toMaybe return a Task Never (Maybe a). Whereas making it return a Task never (Maybe a) is just documentation.

[rgrempel]

I might be misunderstanding, but I believe the lower-case never is just documentation -- it essentially means that the error type is unconstrained -- since it never happens, the type system need not care about it. Whereas the upper-case Never is, technically, an actual type. So (and I may be missing something here) it seems like one would be over-constraining the type checker by making Task.toMaybe return a Task Never (Maybe a). Whereas making it return a Task never (Maybe a) is just documentation.

[evancz]

Yeah, @rtfeldman and I discussed this. Richard, can you give more context on these things? Often when we discuss things offline, that info does not make it into the PR or issue and leads to confusion.

I'd be curious to see @vilterp's thoughts on the reasoning.

[evancz]

Yeah, @rtfeldman and I discussed this. Richard, can you give more context on these things? Often when we discuss things offline, that info does not make it into the PR or issue and leads to confusion.

I'd be curious to see @vilterp's thoughts on the reasoning.

[rtfeldman]

Yep, sorry about that!

My understanding is that @rgrempel's comment is correct as to what the distinction implies.

As for motivation, the reason I wanted to rename it was for searchability; if you are currently working with elm-effects and you think "okay, I need to get to a Never", you reflexively bring up the Task docs and search for "never" to see what comes back. Currently nothing comes back, so I have to hunt function by function until I find one whose docs indicate it'll do what I need.

Changing it to Never would be overly restrictive, but changing it to never makes it searchable. Granted, it could make people wonder "why is it capitalized in one place and not the other?" but that seems like the least painful of the options on the table.

[rtfeldman]

Yep, sorry about that!

My understanding is that @rgrempel's comment is correct as to what the distinction implies.

As for motivation, the reason I wanted to rename it was for searchability; if you are currently working with elm-effects and you think "okay, I need to get to a Never", you reflexively bring up the Task docs and search for "never" to see what comes back. Currently nothing comes back, so I have to hunt function by function until I find one whose docs indicate it'll do what I need.

Changing it to Never would be overly restrictive, but changing it to never makes it searchable. Granted, it could make people wonder "why is it capitalized in one place and not the other?" but that seems like the least painful of the options on the table.