Add generator consumption warnings and improve examples

Expand generators section with warnings about one-time consumption,
add detailed explanations about generator return values with examples,
adjust TOC, and add test for the 'once'
decorator.

Author: edoardob90