docs: add simple and nested update-assignment examples (#3664)

docs/content/manual/dev/manual.yml

@@ -3572,6 +3572,12 @@ sections:
           releases, it used to be that only the last one was used).
 
         examples:
+          - program: '.foo |= . + 1'
+            input: '{"foo": 41, "bar": "unchanged"}'
+            output: ['{"foo": 42, "bar": "unchanged"}']
+          - program: '.user.age |= . + 1'
+            input: '{"user": {"name": "alice", "age": 30}, "active": true}'
+            output: ['{"user": {"name": "alice", "age": 31}, "active": true}']
           - program: '(..|select(type=="boolean")) |= if . then 1 else 0 end'
             input: '[true,false,[5,true,[true,[false]],false]]'
             output: ['[1,0,[5,1,[1,[0]],0]]']

jq.1.prebuilt

@@ -3942,6 +3942,14 @@ If the right\-hand side outputs multiple values, only the first one will be used
 .
 .nf
 
+jq \'\.foo |= \. + 1\'
+   {"foo": 41, "bar": "unchanged"}
+=> {"foo": 42, "bar": "unchanged"}
+
+jq \'\.user\.age |= \. + 1\'
+   {"user": {"name": "alice", "age": 30}, "active": true}
+=> {"user": {"name": "alice", "age": 31}, "active": true}
+
 jq \'(\.\.|select(type=="boolean")) |= if \. then 1 else 0 end\'
    [true,false,[5,true,[true,[false]],false]]
 => [1,0,[5,1,[1,[0]],0]]

tests/man.test

@@ -978,6 +978,14 @@ null
 [0,[1,{"a":1},{"b":2}]]
 true
 
+.foo |= . + 1
+{"foo": 41, "bar": "unchanged"}
+{"foo": 42, "bar": "unchanged"}
+
+.user.age |= . + 1
+{"user": {"name": "alice", "age": 30}, "active": true}
+{"user": {"name": "alice", "age": 31}, "active": true}
+
 (..|select(type=="boolean")) |= if . then 1 else 0 end
 [true,false,[5,true,[true,[false]],false]]
 [1,0,[5,1,[1,[0]],0]]