docs: clarify join behavior on objects (#3555)

docs/content/manual/dev/manual.yml

@@ -1865,14 +1865,16 @@ sections:
       - title: "`join(str)`"
         body: |
 
-          Joins the array of elements given as input, using the
+          Joins the values from the input array or object, using the
           argument as separator. It is the inverse of `split`: that is,
           running `split("foo") | join("foo")` over any input string
           returns said input string.
 
           Numbers and booleans in the input are converted to strings.
-          Null values are treated as empty strings. Arrays and objects
+          Null values are treated as empty strings. When the input is
-          in the input are not supported.
+          an object, `join` operates on the values that `.[]`
+          produces. Arrays and objects among the joined values are not
+          supported.
 
         examples:
           - program: 'join(", ")'
@@ -1881,6 +1883,9 @@ sections:
           - program: 'join(" ")'
             input: '["a",1,2.3,true,null,false]'
             output: ['"a 1 2.3 true  false"']
+          - program: 'join(", ")'
+            input: '{"a":1,"b":2}'
+            output: ['"1, 2"']
 
       - title: "`ascii_downcase`, `ascii_upcase`"
         body: |

docs/content/manual/v1.8/manual.yml

@@ -1865,14 +1865,16 @@ sections:
       - title: "`join(str)`"
         body: |
 
-          Joins the array of elements given as input, using the
+          Joins the values from the input array or object, using the
           argument as separator. It is the inverse of `split`: that is,
           running `split("foo") | join("foo")` over any input string
           returns said input string.
 
           Numbers and booleans in the input are converted to strings.
-          Null values are treated as empty strings. Arrays and objects
+          Null values are treated as empty strings. When the input is
-          in the input are not supported.
+          an object, `join` operates on the values that `.[]`
+          produces. Arrays and objects among the joined values are not
+          supported.
 
         examples:
           - program: 'join(", ")'
@@ -1881,6 +1883,9 @@ sections:
           - program: 'join(" ")'
             input: '["a",1,2.3,true,null,false]'
             output: ['"a 1 2.3 true  false"']
+          - program: 'join(", ")'
+            input: '{"a":1,"b":2}'
+            output: ['"1, 2"']
 
       - title: "`ascii_downcase`, `ascii_upcase`"
         body: |

jq.1.prebuilt

@@ -2047,10 +2047,10 @@ jq \'split(", ")\'
 .IP "" 0
 .
 .SS "join(str)"
-Joins the array of elements given as input, using the argument as separator\. It is the inverse of \fBsplit\fR: that is, running \fBsplit("foo") | join("foo")\fR over any input string returns said input string\.
+Joins the values from the input array or object, using the argument as separator\. It is the inverse of \fBsplit\fR: that is, running \fBsplit("foo") | join("foo")\fR over any input string returns said input string\.
 .
 .P
-Numbers and booleans in the input are converted to strings\. Null values are treated as empty strings\. Arrays and objects in the input are not supported\.
+Numbers and booleans in the input are converted to strings\. Null values are treated as empty strings\. When the input is an object, \fBjoin\fR operates on the values that \fB\.[]\fR produces\. Arrays and objects among the joined values are not supported\.
 .
 .IP "" 4
 .
@@ -2063,6 +2063,10 @@ jq \'join(", ")\'
 jq \'join(" ")\'
    ["a",1,2\.3,true,null,false]
 => "a 1 2\.3 true  false"
+
+jq \'join(", ")\'
+   {"a":1,"b":2}
+=> "1, 2"
 .
 .fi
 .

tests/man.test

@@ -643,6 +643,10 @@ join(" ")
 ["a",1,2.3,true,null,false]
 "a 1 2.3 true  false"
 
+join(", ")
+{"a":1,"b":2}
+"1, 2"
+
 ascii_upcase
 "useful but not for é"
 "USEFUL BUT NOT FOR é"