Explain how the Record Builder is safe

[chexxor]

despite appearing to cheat by using the FFI to effect effectful behavior.

I had to ask in the chat room how this "cheating" can be considered as safe.
This builder seems to handle these effectful operations like ST does -
by wrapping/hiding the effectful stuff in a HKT, and ensuring the types
are correct.

[MonoidMusician]

Good idea :) I think I would just talk about mutation here instead of effects, especially since that explains why copying the record at the start makes it safe, you know?

[justinwoo]

I think it's otherwise important that people know you can't access the "intermediate" states and that it actually does make a clone to build to. Maybe some short explanation like this is missing: https://twitter.com/jusrin00/status/988414714093948929

In addition, how do you teach people about "operations with evidence" overall?

[chexxor]

Thanks for the review! I think the tweet is roughly equivalent to the docs I wrote here, but the info in the tweet is more verbose (I like to be concise, for better or worse).

[hdgarrood]

See #32. I think this is possibly to do with the fact that all of the operations which are exposed as Builder values are linear (they use their argument exactly once). I don't know this well enough to be able to review this PR, though.

[LiamGoodacre]

This sounds good. I'd prefer them to be doc-comments: either for the module or integrated into the existing doc-comment for the Builder type.

[chexxor]

I think that's a great idea.

I moved to doc-comments for the Builder type, and I also simplified the explanation. I hope it didn't lose too much of the information I had before. I think the difference between the new docs and the previous docs I had written is that the new docs just say "this is safe because X" whereas the previous docs said "this is safe because X. They are only used in builder function, and also worth noting is blah-blah."

[LiamGoodacre]

LGTM

[LiamGoodacre]

LGTM

[chexxor]

Thanks for maintaining, @LiamGoodacre and @kRITZCREEK !