Clarify documentation

Hopefully fixed some ambiguous language; added illustrative code.