Here's a revised patch for the doc only.
I added a footnote about side effects, and
followed your other suggestions.