Perhaps it is too early to change the documentation, as the new method may still undergo changes.

For the moment it might be better to keep the old example and add a link to the new preferred way.

But for now, this patch might be good for reference and discussion of changes.

Also it helps with tests.