Fix typo and add comments about code paths

While Pierre was giving his talk, I noticed a typo and Prof Fig noted that some
more comments would be nice here.
Merge pull request #11 from PiPeep/master

Fix typo and add comments about code paths
This commit adds much needed documentation
Merge pull request #12 from ptony82/feature/documentation

This commit adds much needed documentation