Note on raw scalar array containment

diff --git a/src/backend/utils/adt/jsonb_util.c b/src/backend/utils/adt/jsonb_util.c
index d02187f93c824fed2064aa62d80bfaec60d2cb2d..3cb05426c74dbb2fbd15be7679baf25159fa5b24 100644 (file)
--- a/src/backend/utils/adt/jsonb_util.c
+++ b/src/backend/utils/adt/jsonb_util.c
@@ -497,6 +497,9 @@ getIthJsonbValueFromSuperHeader(JsonbSuperHeader sheader, uint32 i)
 /*
  * Push JsonbValue into ToJsonbState.
  *
+ * This is used when parsing JSON tokens to form Jsonb, or when converting an
+ * in-memory JsonbValue to a Jsonb.
+ *
  * Initial state of *ToJsonbState is NULL, since it'll be allocated here
  * originally (caller will get ToJsonbState back by reference).
  *
@@ -861,7 +864,9 @@ deepContains(JsonbIterator ** val, JsonbIterator ** mContained)
         * scalar is contained within lhs val.  When that occurs, there will
         * just be one scalar to consider here.  Note that that does not imply
         * that a scalar array is equal to an array of the same scalar value
-        * according to the default B-Tree operator class.
+        * according to the default B-Tree operator class.  However, it does
+        * imply that a raw scalar has contained within it a single-element
+        * scalar array if the scalar values match, and vice-versa.
         */
        JsonbValue *rhsVals = NULL;
        uint32      nElems = vval.array.nElems;
@@ -1089,7 +1094,8 @@ lexicalCompareJsonbStringValue(const void *a, const void *b)
 }
 
 /*
- * Put JsonbValue tree into a preallocated Jsonb buffer
+ * Given a JsonbValue, convert to Jsonb and store in  preallocated Jsonb buffer
+ * sufficiently large to fit the value
  */
 static Size
 convertJsonb(JsonbValue * v, Jsonb *buffer)
@@ -1173,7 +1179,8 @@ walkJsonbValueConversion(JsonbValue * value, convertState * state,
 }
 
 /*
- * Add padding sufficient to int-align our access to conversion buffer
+ * walkJsonbValueConversion() worker.  Add padding sufficient to int-align our
+ * access to conversion buffer.
  */
 static inline
 short addPaddingInt(convertState * state)
@@ -1193,6 +1200,8 @@ short addPaddingInt(convertState * state)
 }
 
 /*
+ * walkJsonbValueConversion() worker.
+ *
  * As part of the process of converting an arbitrary JsonbValue to a Jsonb,
  * copy an arbitrary individual JsonbValue.  This function may copy over any
  * type of value, even containers (Objects/arrays).  However, it is not
@@ -1200,8 +1209,6 @@ short addPaddingInt(convertState * state)
  * Object/array details are handled).  No details about their
  * keys/values/elements are touched.  The function is called separately for the
  * start of an Object/Array, and the end.
- *
- * This is a worker function for walkJsonbValueConversion().
  */
 static void
 putJsonbValueConversion(convertState * state, JsonbValue * value, uint32 flags,
@@ -1505,7 +1512,8 @@ formIterIsContainer(JsonbIterator ** it, JsonbValue * v, JEntry * e,
 }
 
 /*
- * Return parent, while freeing memory for current iterator
+ * JsonbIteratorNext() worker:  Return parent, while freeing memory for current
+ * iterator
  */
 static JsonbIterator *
 freeAndGetParent(JsonbIterator * it)
@@ -1517,7 +1525,7 @@ freeAndGetParent(JsonbIterator * it)
 }
 
 /*
- * Iteration-like forming jsonb
+ * pushJsonbValue() worker:  Iteration-like forming of Jsonb
  */
 static ToJsonbState *
 pushState(ToJsonbState ** state)
@@ -1528,6 +1536,9 @@ pushState(ToJsonbState ** state)
    return ns;
 }
 
+/*
+ * pushJsonbValue() worker:  Append a pair key to state when generating a Jsonb
+ */
 static void
 appendKey(ToJsonbState * state, JsonbValue * v)
 {
@@ -1548,6 +1559,10 @@ appendKey(ToJsonbState * state, JsonbValue * v)
    a->estSize += v->estSize;
 }
 
+/*
+ * pushJsonbValue() worker:  Append a pair value to state when generating a
+ * Jsonb
+ */
 static void
 appendValue(ToJsonbState * state, JsonbValue * v)
 {
@@ -1559,6 +1574,9 @@ appendValue(ToJsonbState * state, JsonbValue * v)
    a->estSize += v->estSize;
 }
 
+/*
+ * pushJsonbValue() worker:  Append an element to state when generating a Jsonb
+ */
 static void
 appendElement(ToJsonbState * state, JsonbValue * v)
 {