another pass on the documentation of generators

This commit refines the docs contributed in f074bb6.