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