Show Either's "do notation" similarity to nested if-then-else statement

[JordanMartinez]

No description provided.

[hdgarrood]

I think this is probably more suitable for the Bind (Either e) instance. I would say that it's really the Bind instance which enables do notation, as for do notation all you really need is bind. Personally, I think the Monad instance docs should be left at "The Monad instance guarantees that there are both Applicative and Bind instances for Either, and the rest of these docs should be on the Bind instance.

[hdgarrood]

I agree that a more intuitive explanation of what the Bind instance does would be good, but I'm not sure pseudocode is the best way of achieving that; I think prose would probably be preferable.

[hdgarrood]

The reason that I prefer prose over pseudocode is mostly that not everyone is that familiar with whatever language your pseudocode is based on, and even if they were, they might not be able to work out what e.g. unwrapRight or wrapIntoRight are supposed to be doing, or might get hung up on the fact that unwrapRight doesn't have parens to indicate that it's a function. In general I think prose explanations are less likely to accidentally introduce this kind of inaccessibility where you make assumptions about what the reader knows, or how they are likely to interpret something.

[JordanMartinez]

Not using pseudo code makes sense. However, I'm not sure how to write that without it being just as confusing. I feel like a visual of some sorts would explain this much better. Is it possible to include images in documentation?

[JordanMartinez]

Also, I explained how the Array monad works in purescript-prelude via purescript/purescript-prelude#217. It's currently on the Monad instance rather than the Bind instance. So, I should update it there to be consistent with what we do here. Edit: that's been done.

[JordanMartinez]

Rather than using pseudo-code, I explained it using regular PureScript.

I also moved the explanation to the Bind instance.

[JordanMartinez]

I had to force-push this because CI was not pulling in the v0.14.0-rc3 binary

[JordanMartinez]

CI now builds. Harry, this is the same approach you previously approved regarding Maybe's do notation documentation.

[hdgarrood]

Looks great!