Tweak some nbtree-related code comments.

Author: petergeoghegan

contrib/amcheck/verify_nbtree.c

@@ -1975,7 +1975,7 @@ bt_normalize_tuple(BtreeCheckState *state, IndexTuple itup)
 /*
  * Search for itup in index, starting from fast root page.  itup must be a
  * non-pivot tuple.  This is only supported with heapkeyspace indexes, since
- * we rely on having fully unique keys to find a match with only a signle
+ * we rely on having fully unique keys to find a match with only a single
  * visit to a leaf page, barring an interrupted page split, where we may have
  * to move right.  (A concurrent page split is impossible because caller must
  * be readonly caller.)

src/backend/access/nbtree/nbtsearch.c

@@ -182,7 +182,8 @@ _bt_search(Relation rel, BTScanInsert key, Buffer *bufP, int access,
 
 	/*
 	 * If we're asked to lock leaf in write mode, but didn't manage to, then
-	 * relock.  That may happen when the root page appears to be leaf.
+	 * relock.  This should only happen when the root page is a leaf page (and
+	 * the only page in the index other than the metapage).
 	 */
 	if (access == BT_WRITE && page_access == BT_READ)
 	{

src/backend/access/nbtree/nbtsort.c

@@ -835,7 +835,7 @@ _bt_buildadd(BTWriteState *wstate, BTPageState *state, IndexTuple itup)
 	 * the limit on the size of tuples inserted on the leaf level by the same
 	 * small amount.  Enforce the new v4+ limit on the leaf level, and the old
 	 * limit on internal levels, since pivot tuples may need to make use of
-	 * the resered space.  This should never fail on internal pages.
+	 * the reserved space.  This should never fail on internal pages.
 	 */
 	if (unlikely(itupsz > BTMaxItemSize(npage)))
 		_bt_check_third_page(wstate->index, wstate->heap,
@@ -907,8 +907,8 @@ _bt_buildadd(BTWriteState *wstate, BTPageState *state, IndexTuple itup)
 			 * choosing a split point here for a benefit that is bound to be
 			 * much smaller.
 			 *
-			 * Since the truncated tuple is probably smaller than the
-			 * original, it cannot just be copied in place (besides, we want
+			 * Since the truncated tuple is often smaller than the original
+			 * tuple, it cannot just be copied in place (besides, we want
 			 * to actually save space on the leaf page).  We delete the
 			 * original high key, and add our own truncated high key at the
 			 * same offset.  It's okay if the truncated tuple is slightly

src/include/access/nbtree.h

@@ -219,7 +219,6 @@ typedef struct BTMetaPageData
 #define P_FIRSTDATAKEY(opaque)	(P_RIGHTMOST(opaque) ? P_HIKEY : P_FIRSTKEY)
 
 /*
- *
  * Notes on B-Tree tuple format, and key and non-key attributes:
  *
  * INCLUDE B-Tree indexes have non-key attributes.  These are extra
@@ -321,7 +320,7 @@ typedef struct BTMetaPageData
 /*
  * Get/set number of attributes within B-tree index tuple.
  *
- * Note that this does not include an implicit tiebreaker heap-TID
+ * Note that this does not include an implicit tiebreaker heap TID
  * attribute, if any.  Note also that the number of key attributes must be
  * explicitly represented in all heapkeyspace pivot tuples.
  */
@@ -424,10 +423,10 @@ typedef struct BTStackData
 typedef BTStackData *BTStack;
 
 /*
- * BTScanInsert is the btree-private state needed to find an initial position
- * for an indexscan, or to insert new tuples -- an "insertion scankey" (not to
- * be confused with a search scankey).  It's used to descend a B-Tree using
- * _bt_search.
+ * BTScanInsertData is the btree-private state needed to find an initial
+ * position for an indexscan, or to insert new tuples -- an "insertion
+ * scankey" (not to be confused with a search scankey).  It's used to descend
+ * a B-Tree using _bt_search.
  *
  * heapkeyspace indicates if we expect all keys in the index to be physically
  * unique because heap TID is used as a tiebreaker attribute, and if index may