Updates library to v0.14.0-rc2 #29
Conversation
src/Effect/Ref.purs
Outdated
| -- | Create a new mutable reference containing the specified value. | ||
| -- | | ||
| -- | ## Why This Type Signature Cannot Be `forall s. s -> Ref s` |
There was a problem hiding this comment.
I'd prefer to avoid Markdown subheadings, because it requires us to make assumptions about the markup the compiler generates for API documentation. At the moment each declaration in the module is introduced with an <h3>, but this gives us an <h2>, so we have a larger heading under a smaller one, which is no good.
Regarding the actual content here, beginners will occasionally think that all Ref operations ought to be pure, so I think the fact that most Ref operations have to run in Effect is something that deserves discussing at the top of the module.
There was a problem hiding this comment.
That is: it will come across a bit strange to devote so much effort to explaining why new specifically is effectful when almost everything in this module is effectful as well and none of the other functions have had the same treatment.
There was a problem hiding this comment.
If you could split the docs changes into a separate PR we can get this one merged and discuss this further there?
There was a problem hiding this comment.
Yeah, will do. I should have done it that way in the first place.
|
I've updated this PR to remove the doc commit and ported it to #30 |
|
CI is failing because a test is failing. I'll need to look into this more. |
|
I think there's an infinite loop arising from |
|
Yup, done! |
See also #23, #29 I thought about this a bit more, and I think the reasoning for why refs are effectful is more persuasive when viewed through the lens of purity rather than of referential transparency, so I've updated the docs accordingly. I am reluctant to include code examples illustrating why Refs are effectful here, because I think people may skim the page looking for code examples, and in the absence of code examples which describe the real API, I think code examples which illustrate a hypothetical version of the API which doesn't actually exist may do more harm than good. I am also leaning towards not including @natefaubion's example (where you can violate the type system by defining a reference with a polymorphic type and specializing it after the fact), since it's hard to illustrate without a code example, and I think it's unlikely to be useful to most people who just want to make use of the Ref API, which is the group I think we should be considering to be our target audience here.
See also #23, #29 I thought about this a bit more, and I think the reasoning for why refs are effectful is more persuasive when viewed through the lens of purity rather than of referential transparency, so I've updated the docs accordingly. I am reluctant to include code examples illustrating why Refs are effectful here, because I think people may skim the page looking for code examples, and in the absence of code examples which describe the real API, I think code examples which illustrate a hypothetical version of the API which doesn't actually exist may do more harm than good. I am also leaning towards not including @natefaubion's example (where you can violate the type system by defining a reference with a polymorphic type and specializing it after the fact), since it's hard to illustrate without a code example, and I think it's unlikely to be useful to most people who just want to make use of the Ref API, which is the group I think we should be considering to be our target audience here.
Includes #28. Also fixes #23