David, I have some suggestions.
but first i want to show how the current version of doc may look like for new readers. and why.
I am sure that it looks pretty logical if you KNOW how it works, but it is not so clear if you WANT to learn that from documentation.
explanation:
first sentence: "they will only find target rows that were committed as of the command start time."
how a naive user (me) read that: "okay. at the start of command we find only committed rows. LETS SEE WHAT HAPPENS NEXT!".
second sentence: "The search condition of the command (the WHERE
clause) is re-evaluated to see if the updated version of the row still matches the search condition."
how it looks: "The command will be RE-EVALUATED for all rows in the current snapshot (i.e. against new state of db after first updater commits) to RE-CHECK the WHERE condition. AT THE SAME TIME (AS AN EFFECT) we see if the updated version of the row still matches the search condition."
For me RE-evaluating is an ACTION and "to see..that still matches" is ONE of the accompanying options.
As if I said: "I mowed all the grass to avoid seeing the dandelions again."
suggestion:
change sentence: "The search condition of the command (the WHERE
clause) is re-evaluated to see if the updated version of the row still matches the search condition."
with sentence: "The search condition of the command (the WHERE
clause) is re-evaluated only for updated versions of rows to see if they still match the search condition. Note that this is different from re-executing the command."
I tried to explain as best I could.
Of course, I dare not insist on anything.
thanks!