Document paredit

[lread]

I'm digging into the rewrite-clj/paredit ns these days.

To help my future self and others:

• update docstrings to be really clear (if not already)
• explain how to use API in user guide.

[lread]

• [ ] check that docstring mentioned in #256 is corrected