another pass on the documentation of generators

This commit refines the docs contributed in #f074bb6.