Updates library's documentation for v0.14.0 release #11
Conversation
The removed documentation now applies to `purescript-safe-coerce`'s `coerce` function.
src/Unsafe/Coerce.purs
Outdated
| -- | Let's say you have a type you wish to use internally and expose publicly | ||
| -- | but which end-users should not be able to view or modify. Rather, end-users | ||
| -- | can only pass that value around in their code. One way to accomplish this | ||
| -- | is through existentials. Existentials is not always the best solution to |
There was a problem hiding this comment.
What you've described here isn't existentials, it's just hiding the representation of a data type. You don't need unsafeCoerce for that, you can just define the data type the normal way and avoid exporting its constructors.
There was a problem hiding this comment.
What you've described here isn't existentials....
Ah... true. I think I had something more like Halogen Hooks in mind, which uses this pattern to create a heterogeneous array, when I wrote this example. Nate's ShowBox code is a real example of an existential.
On another note, since existentials are usually an anti-pattern, should we cover it here at all?
src/Unsafe/Coerce.purs
Outdated
| -- | mapConjToDisj = unsafeCoerce | ||
| -- | Note: because this function is extraordinarily flexible, type inference | ||
| -- | can greatly suffer. Whenever you use it, you should add type annotations | ||
| -- | to clarify what the type of it's input value is and the type of it's |
There was a problem hiding this comment.
When you're using "its" to indicate possession, there's no apostrophe. You only include the apostrophe in "it's" when you're using "it's" as a contraction of "it is".
There was a problem hiding this comment.
😄 I thought that sentence looked weird when I wrote it. Sorry about that.
There was a problem hiding this comment.
No worries! This is a very common mistake.
src/Unsafe/Coerce.purs
Outdated
| -- | 2. To model the kinds of arguments an FFI function can take if one or | ||
| -- | more of its arguments can be multiple types. | ||
| -- | | ||
| -- | ## Modeling Existentials |
There was a problem hiding this comment.
I think unsafeCoerce is really just an implementation detail of these two ideas; it's not fundamentally tied to either of them. For instance, existentials can also be implemented without any escape hatches like unsafeCoerce, and at some point in the future, we might implement them in the language, which would mean that there would be no need to use this technique at all. Therefore, I'm not sure this repo's API reference is a good place to discuss them in such depth. I think material discussing these techniques would be better placed either in the guides directory of the documentation repo, or in a cookbook recipe.
There was a problem hiding this comment.
Good point. I'll remove these two examples, but keep that note about the type inference.
| -- | to clarify what the type of it's input value is and the type of it's | ||
| -- | output value. | ||
| -- | | ||
| -- | It is highly recommended to define specializations of this function rather than |
There was a problem hiding this comment.
I would like to keep this part in, as I think it's a bit more clear. As for the example, how about:
fromBoolean :: Boolean -> Json
fromBoolean = unsafeCoerce
There was a problem hiding this comment.
Fixed in latest commits.
|
I think this PR is ready to be merged now. |
See #10 for more context.
I tried replacing the original example with examples from Harry's list as to why one would use this. Let me know what I should change and/or whether this should be shortened in general.