document the flow and do a little bit of doc cleanup.