another pass on the documentation of generators

This commit refines the docs contributed in f074bb6.
Merge pull request #1592 from fxn/master

another pass on the documentation of generators