From e8ba17e68a5fda0e75084c2f7a4e8eee55a928f3 Mon Sep 17 00:00:00 2001
From: Andres Freund <andres@anarazel.de>
Date: Wed, 19 Mar 2014 17:19:10 +0100
Subject: [PATCH] Denote some pieces of code with FIXMEs that should be
 improved.

---
 src/backend/utils/adt/jsonb.c      |  3 +++
 src/backend/utils/adt/jsonb_util.c |  3 +++
 src/include/utils/jsonb.h          | 27 ++++++++++++++++++++++++++-
 3 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/src/backend/utils/adt/jsonb.c b/src/backend/utils/adt/jsonb.c
index c9e6cd1210..aef665198a 100644
--- a/src/backend/utils/adt/jsonb.c
+++ b/src/backend/utils/adt/jsonb.c
@@ -164,6 +164,8 @@ jsonb_typeof(PG_FUNCTION_ARGS)
  * Turn json text into a jsonb Datum.
  *
  * Uses the json parser with hooks to contruct a jsonb.
+ *
+ * FIXME: rename to jsonb_from_cstring() or such.
  */
 static inline Datum
 cstring_with_len_to_jsonb(char *json, int len)
@@ -383,6 +385,7 @@ JsonbToCString(StringInfo out, char *in, int estimated_len)
 
 	if (in == NULL)
 	{
+		/* FIXME: Huh? */
 		appendStringInfoString(out, "");
 		return out->data;
 	}
diff --git a/src/backend/utils/adt/jsonb_util.c b/src/backend/utils/adt/jsonb_util.c
index cf326f8504..6f8e1aa1d9 100644
--- a/src/backend/utils/adt/jsonb_util.c
+++ b/src/backend/utils/adt/jsonb_util.c
@@ -23,6 +23,7 @@
  * State used while converting an arbitrary JsonbValue into a Jsonb value
  * (4-byte varlena uncompressed representation of a Jsonb)
  *
+ * FIXME: what's ConvertLevel referring to? Wrong struct and case?
  * ConvertLevel: Bookkeeping around current level when converting.
  */
 typedef struct convertLevel
@@ -276,6 +277,8 @@ compareJsonbSuperHeaderValue(JsonbSuperHeader a, JsonbSuperHeader b)
  * pointed to by the superheader, immediately fall through and return NULL.  If
  * we cannot find the value, return NULL.  Otherwise, return palloc()'d copy of
  * value.
+ *
+ * FIXME: lowbound should be documented.
  */
 JsonbValue *
 findJsonbValueFromSuperHeader(JsonbSuperHeader sheader, uint32 flags,
diff --git a/src/include/utils/jsonb.h b/src/include/utils/jsonb.h
index ae45beea12..74288e79da 100644
--- a/src/include/utils/jsonb.h
+++ b/src/include/utils/jsonb.h
@@ -105,6 +105,10 @@ typedef	char*  JsonbSuperHeader;
  * first int32 of the object contains the total object size in bytes.  Be sure
  * to use VARSIZE() and SET_VARSIZE() to access it, though!
  *
+ * FIXME: Explanation imo starts at the wrong abstraction level. There should
+ * be sensible documentation about the whole data structure here. Mabye even
+ * some ascii-art.
+ *
  * We have an abstraction called a "superheader".  This is a pointer that
  * conventionally points to the first item after our 4-byte uncompressed
  * varlena header, from which we can read flags using bitwise operations.
@@ -123,7 +127,7 @@ typedef	char*  JsonbSuperHeader;
 typedef struct
 {
 	int32		vl_len_;		/* varlena header (do not touch directly!) */
-	uint32		superheader;
+	uint32		superheader;	/* FIXME: meh, so we have a superheader type, but don't use it */
 	/* (array of JEntry follows, size determined using uint32 superheader) */
 } Jsonb;
 
@@ -134,12 +138,25 @@ typedef struct
  * The position offset points to the _end_ so that we can get the length by
  * subtraction from the previous entry.	 The JENTRY_ISFIRST flag indicates if
  * there is a previous entry.
+ *
+ * FIXME: tentatively I'd say the name is a bit generic.
  */
 typedef struct
 {
 	uint32		header;			/* May be accessed as superheader */
 }	JEntry;
 
+/*
+ * FIXME: There needs to be documentation about the struct's raison
+ * d'etre. Specifically that this is (IIUC) the in-memory representation, in
+ * constrast to Jsonb, which is the on-disk format. Imo a better typename
+ * could make that much clearer as well.
+ *
+ * FIXME: jbvBinary needs explanation somewhere.
+ *
+ * FIXME: maybe it makes sense to treat type as a bitmask, so you'd be able to
+ * have JSONBV_IS_SCALAR instead of v->type >= jbvNull && v->type < jbvArray.
+ */
 struct JsonbValue
 {
 	enum
@@ -156,6 +173,10 @@ struct JsonbValue
 		jbvBinary
 	} type;		/* Influences sort order */
 
+	/*
+	 * FIXME: minor: does this have to be 8byte on 64bit machines? Doesn't
+	 * varlena limit the size to a far bit below this?
+	 */
 	Size		estSize;		/* Estimated size of node (including
 								 * subnodes) */
 
@@ -198,6 +219,7 @@ struct JsonbValue
  * benefit of doing so in a well-defined way with respect to the original
  * observed order (which is "last observed wins").  This is only stored when
  * originally constructing a Jsonb.
+ * FIXME: Hm, how can there be a need for this when its deduplicated.
  */
 struct JsonbPair
 {
@@ -218,6 +240,7 @@ typedef struct ToJsonbState
  * JsonbIterator holds details of the type for each iteration. It also stores a
  * Jsonb varlena buffer, which can be directly accessed without deserialization
  * in some contexts.
+ * FIXME: another too generic name.
  */
 typedef enum
 {
@@ -305,8 +328,10 @@ extern JsonbIterator *JsonbIteratorInit(JsonbSuperHeader buffer);
 extern int JsonbIteratorNext(JsonbIterator **it, JsonbValue *v,
 							 bool skipNested);
 extern Jsonb *JsonbValueToJsonb(JsonbValue *v);
+/* FIXME: too generic name for public symbol header */
 extern bool deepContains(JsonbIterator ** val, JsonbIterator ** mContained);
 extern JsonbValue *arrayToJsonbSortedArray(ArrayType *a);
+/* FIXME: too generic name for public symbol header */
 extern void hash_scalar_value(const JsonbValue * v, uint32 * hash_state);
 
 /* jsonb.c support function */
-- 
2.39.5