Adds some documentation/examples

[kritzcreek]

Currently making a pass over some of the modules until I run out of steam...

[crusso]

Suggested change

	/// Motoko does not have exceptions, so we use a datatype to encode these
	/// outcomes.
	/// Motoko does not have exceptions, so we use a datatype to encode these
	/// outcomes.
	/// Motoko's exception handling is limited to `async` contexts.
	/// For other contexts, Motoko provides a variant type to encode exceptional results.

[nomeata]

Instead of making that rather confusing statement, maybe just delete the reference to exceptions, and justify the existence of Result otherwise?

[kritzcreek]

I agree we shouldn't be bringing exceptions into this, maybe we should say something about error handling in general.

[kritzcreek]

Allright, I basically copied https://doc.rust-lang.org/std/result/ because I thought the description was on point.

[kritzcreek]

Thanks for all the comments and review, I'll merge this and if we think the Result introduction needs more improvement we can still do that.

[matthewhammer]

I have some minor copyediting nits that you can ignore if you wish.

LGTM.

[matthewhammer]

so keep that in mind when sharing iterators between consumers.

I'm more confused than helped by this warning.

Are you effectively saying that "an iterator is a mutable object; when shared, multiple users calling next will interfere"?

[matthewhammer]

passive voice. I prefer active voice, when possible. For instance: "A for loop expression consumes an iterator by using its body to consume each item produced by the iterator. The variable x (bound in the for body) ranges over these items. "