WIP: document parley

[nicoburns]

This is very early and currently just adds comments to (a subset of) the code I happen to have read. But wanted to put this up early:

• In case it is helpful to anyone else trying to understand the parley codebase
• To check whether you would be willing to accept PR(s) adding this kind of documentation

UPDATE: this now contains a bunch of extra stuff not in the original PR: we'll probably want to split this into separate PRs. But just dumping everything here for now.