Update docs #31
Update docs #31
Conversation
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.
|
I think that for module documentation, it's preferable to only include information we think the people who are using the API in question are likely to need in order to use that API effectively, and I don't think knowing that a version of Ref which didn't use Effect could be used to violate the type system is information you need to use Ref effectively. If we spend too much effort talking about an issue which people don't need to understand in order to make effective use of an API, we risk giving the false impression that it is needed. This means that it takes people longer to get to where they wanted to be, and it can be confusing or frustrating to expend effort getting your head around something because you thought you needed to, and then later realise that it wasn't really relevant to you. (By comparison, if a specific question has been asked in a separate Q&A forum or a GitHub issue, it is much less likely to mislead people; people will assume it's optional extra knowledge, and they probably won't find it unless they went looking for it because they were interested.) In general, I would argue that content from places like GitHub issues, Slack, or Discourse usually won't be appropriate for moving straight into API documentation as-is: it's usually necessary to go back over the content from the perspective of "do people need to know this to make use of this API effectively?" and edit accordingly. |
| -- | effects, and should return the same result when called with the same | ||
| -- | arguments. If a `Ref` could be written to without using `Effect`, that | ||
| -- | would cause a side effect (the effect of changing the result of subsequent | ||
| -- | reads for that `Ref`). If there were a function for reading the current |
There was a problem hiding this comment.
the effect of changing the result of subsequent reads for that
Ref
Good simple and clear explanation. Well 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.