From 57ae71fe4e69d72a97c50980c84c333fcbf02447 Mon Sep 17 00:00:00 2001
From: Jason Volk <jason@zemos.net>
Date: Wed, 25 Oct 2017 09:30:04 -0700
Subject: [PATCH] ircd::json: Add additional commentary.

---
 include/ircd/json/iov.h  | 5 +++++
 include/ircd/json/json.h | 5 ++++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/include/ircd/json/iov.h b/include/ircd/json/iov.h
index cc662256a..798bdf3c1 100644
--- a/include/ircd/json/iov.h
+++ b/include/ircd/json/iov.h
@@ -68,6 +68,7 @@ struct ircd::json::iov
 	friend size_t serialized(const iov &);
 };
 
+/// Unconditionally append a member to the object vector
 struct ircd::json::iov::push
 :protected ircd::json::iov::node
 {
@@ -78,6 +79,7 @@ struct ircd::json::iov::push
 	push() = default;
 };
 
+/// Add a new member to the object vector; throws if exists
 struct ircd::json::iov::add
 :protected ircd::json::iov::node
 {
@@ -85,6 +87,7 @@ struct ircd::json::iov::add
 	add() = default;
 };
 
+/// iov::add only if the bool argument is true for your condition
 struct ircd::json::iov::add_if
 :protected ircd::json::iov::node
 {
@@ -92,6 +95,7 @@ struct ircd::json::iov::add_if
 	add_if() = default;
 };
 
+/// Add or overwrite a member in the object vector.
 struct ircd::json::iov::set
 :protected ircd::json::iov::node
 {
@@ -99,6 +103,7 @@ struct ircd::json::iov::set
 	set() = default;
 };
 
+/// iov::set only if the bool argument is true for your condition
 struct ircd::json::iov::set_if
 :protected ircd::json::iov::node
 {
diff --git a/include/ircd/json/json.h b/include/ircd/json/json.h
index b126d47e9..8364482bf 100644
--- a/include/ircd/json/json.h
+++ b/include/ircd/json/json.h
@@ -123,7 +123,10 @@ struct ircd::json::buffer
 ///
 /// Convenience template for const rvalue mutable_buffers or basically
 /// allowing a bracket initialization of a mutable_buffer in the argument
-/// to stringify()
+/// to stringify(). The const rvalue reference is on purpose. The stringify()
+/// family of friends all use a non-const lvalue mutable_buffer as an append
+/// only "stream" buffer. We don't want to modify any non-const instances of
+/// the mutable_buffer you pass here by offering a `mutable_buffer &` overload
 ///
 template<class... T>
 ircd::string_view