Standardize ItemIdData terminology.

The term "item pointer" should not be used to refer to ItemIdData
variables, since that is needlessly ambiguous.  Only
ItemPointerData/ItemPointer variables should be called item pointers.

To fix, establish the convention that ItemIdData variables should always
be referred to either as "item identifiers" or "line pointers".  The
term "item identifier" already predominates in docs and translatable
messages, and so should be the preferred alternative there.

Discussion: https://postgr.es/m/CAH2-Wz=c=MZQjUzde3o9+2PLAPuHTpVZPPdYxN=E4ndQ2--8ew@mail.gmail.com

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

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.

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

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)