Expand documentation section on comment parsing

Patch by Jonathan Sauer, with a little editing by me.