4 files changed, 19 insertions, 14 deletions
diff --git a/src/include/access/htup_details.h b/src/include/access/htup_details.h
index 6d51f9062ba..8c9cc374829 100644
--- a/src/include/access/htup_details.h
+++ b/src/include/access/htup_details.h
@@ -564,7 +564,7 @@ do { \
  * MaxHeapTuplesPerPage is an upper bound on the number of tuples that can
  * fit on one heap page.  (Note that indexes could have more, because they
  * use a smaller tuple header.)  We arrive at the divisor because each tuple
- * must be maxaligned, and it must have an associated item pointer.
+ * must be maxaligned, and it must have an associated line pointer.
  *
  * Note: with HOT, there could theoretically be more line pointers (not actual
  * tuples) than this on a heap page.  However we constrain the number of line
diff --git a/src/include/access/itup.h b/src/include/access/itup.h
index 2f90cc0142d..8c3a57a8eba 100644
--- a/src/include/access/itup.h
+++ b/src/include/access/itup.h
@@ -131,7 +131,7 @@ typedef IndexAttributeBitMapData * IndexAttributeBitMap;
  * fit on one index page.  An index tuple must have either data or a null
  * bitmap, so we can safely assume it's at least 1 byte bigger than a bare
  * IndexTupleData struct.  We arrive at the divisor because each tuple
- * must be maxaligned, and it must have an associated item pointer.
+ * must be maxaligned, and it must have an associated line pointer.
  *
  * To be index-type-independent, this does not account for any special space
  * on the page, and is thus conservative.
diff --git a/src/include/storage/bufpage.h b/src/include/storage/bufpage.h
index 85cd0abb972..87f16557ba5 100644
--- a/src/include/storage/bufpage.h
+++ b/src/include/storage/bufpage.h
@@ -53,14 +53,18 @@
  *
  * NOTES:
  *
- * linp1..N form an ItemId array.  ItemPointers point into this array
- * rather than pointing directly to a tuple.  Note that OffsetNumbers
+ * linp1..N form an ItemId (line pointer) array.  ItemPointers point
+ * to a physical block number and a logical offset (line pointer
+ * number) within that block/page.  Note that OffsetNumbers
  * conventionally start at 1, not 0.
  *
- * tuple1..N are added "backwards" on the page.  because a tuple's
- * ItemPointer points to its ItemId entry rather than its actual
+ * tuple1..N are added "backwards" on the page.  Since an ItemPointer
+ * offset is used to access an ItemId entry rather than an actual
  * byte-offset position, tuples can be physically shuffled on a page
- * whenever the need arises.
+ * whenever the need arises.  This indirection also keeps crash recovery
+ * relatively simple, because the low-level details of page space
+ * management can be controlled by standard buffer page code during
+ * logging, and during recovery.
  *
  * AM-generic per-page information is kept in PageHeaderData.
  *
@@ -233,7 +237,7 @@ typedef PageHeaderData *PageHeader;
 
 /*
  * PageGetContents
- *		To be used in case the page does not contain item pointers.
+ *		To be used in cases where the page does not contain line pointers.
  *
  * Note: prior to 8.3 this was not guaranteed to yield a MAXALIGN'd result.
  * Now it is.  Beware of old code that might think the offset to the contents
diff --git a/src/include/storage/itemid.h b/src/include/storage/itemid.h
index 30a51931326..ad232fb706f 100644
--- a/src/include/storage/itemid.h
+++ b/src/include/storage/itemid.h
@@ -1,7 +1,7 @@
 /*-------------------------------------------------------------------------
  *
  * itemid.h
- *	  Standard POSTGRES buffer page item identifier definitions.
+ *	  Standard POSTGRES buffer page item identifier/line pointer definitions.
  *
  *
  * Portions Copyright (c) 1996-2019, PostgreSQL Global Development Group
@@ -15,16 +15,17 @@
 #define ITEMID_H
 
 /*
- * An item pointer (also called line pointer) on a buffer page
+ * A line pointer on a buffer page.  See buffer page definitions and comments
+ * for an explanation of how line pointers are used.
  *
- * In some cases an item pointer is "in use" but does not have any associated
- * storage on the page.  By convention, lp_len == 0 in every item pointer
+ * In some cases a line pointer is "in use" but does not have any associated
+ * storage on the page.  By convention, lp_len == 0 in every line pointer
  * that does not have storage, independently of its lp_flags state.
  */
 typedef struct ItemIdData
 {
 	unsigned	lp_off:15,		/* offset to tuple (from start of page) */
-				lp_flags:2,		/* state of item pointer, see below */
+				lp_flags:2,		/* state of line pointer, see below */
 				lp_len:15;		/* byte length of tuple */
 } ItemIdData;
 
@@ -72,7 +73,7 @@ typedef uint16 ItemLength;
 
 /*
  *		ItemIdGetRedirect
- * In a REDIRECT pointer, lp_off holds the link to the next item pointer
+ * In a REDIRECT pointer, lp_off holds offset number for next line pointer
  */
 #define ItemIdGetRedirect(itemId) \
    ((itemId)->lp_off)