Add more docs for populate_existing(); link with_for_update

Add more docs for populate_existing(); link with_for_update

The populate_existing() method is actually changing
to be an execution option, however it has almost no
mention in the narrative docs so add docs in terms of the
1.x version first, including that we mention you almost
definitely want to use this method if you are also using
with_for_update().

Fixes: #5572
Fixes: #4774
Change-Id: Ieca916400622c1ffc1ae81204132a02a0983594c
(cherry picked from commit e78c8f84958a031056684d7056aff0eab6ced226)