From 77ba8696d92cbc8807670dd4843d4fec47d03409 Mon Sep 17 00:00:00 2001
From: Jason Volk <jason@zemos.net>
Date: Fri, 8 Sep 2017 03:43:11 -0700
Subject: [PATCH] ircd::json: Commentary / minor cleanup.

---
 include/ircd/json/member.h | 15 ++++++++++++---
 include/ircd/json/value.h  | 18 +++++++++++++-----
 2 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/include/ircd/json/member.h b/include/ircd/json/member.h
index 6635709f3..5cfbc8676 100644
--- a/include/ircd/json/member.h
+++ b/include/ircd/json/member.h
@@ -22,6 +22,15 @@
 #pragma once
 #define HAVE_IRCD_JSON_MEMBER_H
 
+// json::member is a pair of values. The key value (member.first) should always
+// be a STRING type. We don't use string_view directly in member.first because
+// json::value can take ownership of a string or use a literal depending on
+// the circumstance and it's more consistent this way.
+//
+// json::member, like json::value, is a runtime construct though still very
+// lightweight and useful for non-deterministic composition to and extraction
+// from JSON strings.
+//
 namespace ircd::json
 {
 	struct member;
@@ -117,17 +126,17 @@ ircd::json::operator==(const member &a, const member &b)
 inline bool
 ircd::json::operator<(const member &a, const string_view &b)
 {
-	return string_view(a.first.string, a.first.len) < b;
+	return string_view{a.first.string, a.first.len} < b;
 }
 
 inline bool
 ircd::json::operator!=(const member &a, const string_view &b)
 {
-	return string_view(a.first.string, a.first.len) != b;
+	return string_view{a.first.string, a.first.len} != b;
 }
 
 inline bool
 ircd::json::operator==(const member &a, const string_view &b)
 {
-	return string_view(a.first.string, a.first.len) == b;
+	return string_view{a.first.string, a.first.len} == b;
 }
diff --git a/include/ircd/json/value.h b/include/ircd/json/value.h
index 302f5dbc0..60c5620b3 100644
--- a/include/ircd/json/value.h
+++ b/include/ircd/json/value.h
@@ -22,11 +22,19 @@
 #pragma once
 #define HAVE_IRCD_JSON_VALUE_H
 
-// The ircd::json::value is used if we have to keep state in machine-form
-// rather than directly computing JSON strings. This class ends up being useful
-// for recursive initializer_lists to compose JSON from machine values. It
-// is lightweight, consuming the space of two pointers which is the same size
-// as a string_view.
+// The ircd::json::value is used if we have to keep non-deterministic runtime
+// state of values apropos a JSON object. In other words, value is runtime-
+// typed rather than the json::tuple which is compile-time typed. The cost of
+// using this value structure is in the switching based on the type enum it
+// stores as well as a branch in the destructor to deallocate owned resources.
+// This is still very lightweight. The structure itself is the same size as
+// a string_view (two pointers). It is also not template-based, allowing us
+// to keep logic in the definition files and out of the headers. Nevertheless,
+// this class should not be abused over an alternative compile-time solution.
+//
+// Value cannot be copied because it can own resources, and recursively. The
+// resource ownership is necessary in cases like nested initializer_lists
+// and other such complex compositions.
 //
 struct ircd::json::value
 {