Document the field_escape_pattern in the to_json() BiF

This argument, and its corresponding use in Val.cc's BuildJSON(),
were never explained.

src/Val.cc

@@ -329,8 +329,27 @@ TableValPtr Val::GetRecordFields() {
     return rt->GetRecordFieldsVal(rv);
 }
 
-// This is a static method in this file to avoid including rapidjson's headers in Val.h because
+// A predicate to identify those types we render as a string in JSON.
-// they're huge.
+static bool IsQuotedJSONType(const TypePtr& t) {
+    if ( t == nullptr )
+        return false;
+
+    switch ( t->Tag() ) {
+        case TYPE_ADDR:
+        case TYPE_ENUM:
+        case TYPE_FILE:
+        case TYPE_FUNC:
+        case TYPE_INTERVAL:
+        case TYPE_PATTERN:
+        case TYPE_STRING:
+        case TYPE_SUBNET:
+        case TYPE_OPAQUE: return true;
+        default: return false;
+    }
+}
+
+// This is a static method in this file to avoid including rapidjson's headers
+// in Val.h, because they're huge.
 static void BuildJSON(json::detail::NullDoubleWriter& writer, Val* val, bool only_loggable = false,
                       RE_Matcher* re = nullptr, const string& key = "") {
     if ( ! key.empty() )

src/Val.h

@@ -236,6 +236,20 @@ public:
 
     TableValPtr GetRecordFields();
 
+    /**
+     * Renders the Val into JSON string representation. For record values
+     * contained anywhere in the Val, two arguments control the JSON result
+     * (they have no effect on other types):
+     *
+     * @param only_loggable  If true, skips any fields that don't have the &log
+     * attribute.
+     *
+     * @param re  The regular expression matcher, if given, is used to strip the
+     * first match on any record field name in the resulting output.  See the
+     * to_json() BiF for context.
+     *
+     * @return  JSON data representing the Val.
+     */
     StringValPtr ToJSON(bool only_loggable = false, RE_Matcher* re = nullptr);
 
     template<typename T>

src/zeek.bif

@@ -5061,6 +5061,12 @@ function anonymize_addr%(a: addr, cl: IPAddrAnonymizationClass%): addr
 ## only_loggable: If the v value is a record this will only cause
 ##                fields with the &log attribute to be included in the JSON.
 ##
+## field_escape_pattern: If the v value is a record, the given pattern is
+##                       matched against the field names of its type, and
+##                       the first match, if any, is stripped from the
+##                       rendered name. The default pattern strips a leading
+##                       underscore.
+##
 ## returns: a JSON formatted string.
 ##
 ## .. zeek:see:: fmt cat cat_sep string_cat print_raw from_json