Fix code comments regarding logical decoding

Back in 3b02ea4f0780 I added some comments in various places to explain
how logical decoding and other things worked.  Not all of the changes
were welcome, because they were misleading or wrong.  This changes them
a little bit to make them more accurate.

Some other comments are also changed to be more accurate.  Also, fix a
bunch of typos.

Author: Álvaro Herrera, Craig Ringer

Andres Freund reviewed some parts of this.

1 files changed, 4 insertions, 11 deletions

diff --git a/src/backend/replication/logical/logicalfuncs.c b/src/backend/replication/logical/logicalfuncs.c
index 84b4d573e77..99112ac1b4d 100644
--- a/src/backend/replication/logical/logicalfuncs.c
+++ b/src/backend/replication/logical/logicalfuncs.c
@@ -238,10 +238,7 @@ pg_logical_slot_get_changes_guts(FunctionCallInfo fcinfo, bool confirm, bool bin
 
 	PG_TRY();
 	{
-		/*
-		 * Passing InvalidXLogRecPtr here causes replay to start at the slot's
-		 * confirmed_flush.
-		 */
+		/* restart at slot's confirmed_flush */
 		ctx = CreateDecodingContext(InvalidXLogRecPtr,
 									options,
 									logical_read_local_xlog_page,
@@ -265,13 +262,9 @@ pg_logical_slot_get_changes_guts(FunctionCallInfo fcinfo, bool confirm, bool bin
 		ctx->output_writer_private = p;
 
 		/*
-		 * We start reading xlog from the restart lsn, even though in
-		 * CreateDecodingContext we set the snapshot builder up using the
-		 * slot's confirmed_flush. This means we might read xlog we don't
-		 * actually decode rows from, but the snapshot builder might need it
-		 * to get to a consistent point. The point we start returning data to
-		 * *users* at is the confirmed_flush lsn set up in the decoding
-		 * context.
+		 * Decoding of WAL must start at restart_lsn so that the entirety of
+		 * xacts that committed after the slot's confirmed_flush can be
+		 * accumulated into reorder buffers.
 		 */
 		startptr = MyReplicationSlot->data.restart_lsn;