clean-up and add docs stub

the reason it's one big chunk is that i changed indentation to match zack's style, sorry!
lines 136-157 are really similar to the ones for the inTrans, perhaps we can refactor this to be more DRY?