doc cleanup
criticism on critical sections
Merge pull request #47 from froj/master

criticism on critical sections