Documentation improvements to jsonpath

Besides cosmetic improvements it removes statement that operators necessary
need to be separated from operands with spaces, which is not really true.

Discussion: https://postgr.es/m/CAEkD-mDUZrRE%3Dk-FznEg4Ed2VdjpZCyHoyo%2Bp0%2B8KvHqR%3DpNVQ%40mail.gmail.com
Author: Liudmila Mantrova, Alexander Lakhin
Reviewed-by: Alexander Korotkov, Alvaro Herrera
Backpatch-through: 12

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 4e3e213fbc66d6a7587c1bc8ae217919872c28e7..17bebc4fe1b05abd02eeb93288496e0ab66e1abb 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -11574,7 +11574,7 @@ table2-mapping
 
   JSON query functions and operators
    pass the provided path expression to the path engine
-   for evaluation. If the expression matches the JSON data to be queried,
+   for evaluation. If the expression matches the queried JSON data,
    the corresponding SQL/JSON item is returned.
    Path expressions are written in the SQL/JSON path language
    and can also include arithmetic expressions and functions.
@@ -11634,7 +11634,7 @@ table2-mapping
 
   
    If the item to retrieve is an element of an array, you have
-   to unnest this array using the [*] operator. For example,
+   to unnest this array using the [*] operator. For example,
    the following path will return location coordinates for all
    the available track segments:
 
@@ -11655,8 +11655,7 @@ table2-mapping
    The result of each path evaluation step can be processed
    by one or more jsonpath operators and methods
    listed in .
-   Each method must be preceded by a dot, while arithmetic and Boolean
-   operators are separated from the operands by spaces. For example,
+   Each method name must be preceded by a dot. For example,
    you can get an array size:
 
 '$.track.segments.size()'
@@ -11937,7 +11936,7 @@ table2-mapping
        
        
         double()
-        Approximate numeric value converted from a string
+        Approximate floating-point number converted from an SQL/JSON number or a string
         {"len": "1.9"}
         $.len.double() * 2
         3.8
@@ -11966,10 +11965,10 @@ table2-mapping
        
         keyvalue()
         
-          Sequence of object's key-value pairs represented as array of objects
+          Sequence of object's key-value pairs represented as array of items
           containing three fields ("key",
           "value", and "id").
-          "id" is an unique identifier of the object
+          "id" is a unique identifier of the object
           key-value pair belongs to.
         
         {"x": "20", "y": 32}
@@ -12091,9 +12090,9 @@ table2-mapping
         like_regex
         
           Tests pattern matching with POSIX regular expressions
-          ().  Supported flags
+          (see ).  Supported flags
           are i, s, m,
-          x and q.
+          x, and q.
         ["abc", "abd", "aBdC", "abdacb", "babc"]
         $[*] ? (@ like_regex "^ab.*c" flag "i")
         "abc", "aBdC", "abdacb"
@@ -12107,7 +12106,7 @@ table2-mapping
        
        
         exists
-        Tests whether a path expression has at least one SQL/JSON item
+        Tests whether a path expression matches at least one SQL/JSON item
         {"x": [1, 2], "y": [2, 4]}
         strict $.* ? (exists (@ ? (@[*] > 2)))
         2, 4
@@ -12332,10 +12331,9 @@ table2-mapping
        
         @@
         jsonpath
-        JSON path predicate check result for the specified JSON value.
-        Only first result item is taken into account.  If there are no results
-        or the first result item is not Boolean, then null
-        is returned.
+        Returns the result of JSON path predicate check for the specified JSON value.
+        Only the first item of the result is taken into account.  If the
+        result is not Boolean, then null is returned.
         '{"a":[1,2,3,4,5]}'::jsonb @@ '$.a[*] > 2'
        
       
@@ -12973,7 +12971,7 @@ table2-mapping
        
         
          
-           jsonb_path_exists(target jsonb, path jsonpath [, vars jsonb, silent bool])
+           jsonb_path_exists(target jsonb, path jsonpath [, vars jsonb [, silent bool]])
          
         
         boolean
@@ -12998,10 +12996,9 @@ table2-mapping
         
         boolean
         
-          Returns JSON path predicate result for the specified JSON value.
-          Only first result item is taken into account.  If there are no results
-          or the first result item is not Boolean, then null
-          is returned.
+          Returns the result of JSON path predicate check for the specified JSON value.
+          Only the first item of the result is taken into account.  If the
+          result is not Boolean, then null is returned.
         
         
          
@@ -13208,18 +13205,18 @@ table2-mapping
   
    
     The jsonb_path_exists, jsonb_path_match,
-    jsonb_path_query, jsonb_path_query_array and
+    jsonb_path_query, jsonb_path_query_array, and
     jsonb_path_query_first
     functions have optional vars and silent
     arguments.
    
    
-    If the <literal>vars> argument is specified, it provides an
+    If the <parameter>vars> argument is specified, it provides an
     object containing named variables to be substituted into a
     jsonpath expression.
    
    
-    If the <literal>silent> argument is specified and has the
+    If the <parameter>silent> argument is specified and has the
     true value, these functions suppress the same errors
     as the @? and @@ operators.
    

diff --git a/doc/src/sgml/json.sgml b/doc/src/sgml/json.sgml
index 2d2f404b73e13faa8afe74481c457e3ec2f5da8b..4f566a4c8d6eca8c1f7283101cbd907e44eb8b3a 100644 (file)
--- a/doc/src/sgml/json.sgml
+++ b/doc/src/sgml/json.sgml
@@ -490,11 +490,11 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"';
 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] ? (@ == "qui")';
 
     GIN index extracts statements of following form out of
-    jsonpath: <literal>accessors_chain = const>.
+    jsonpath: <replaceable>accessors_chain = const>.
     Accessors chain may consist of .key,
-    [*] and [index] accessors.
+    [*], and [index] accessors.
     jsonb_ops additionally supports .*
-    and .** statements.
+    and .** accessors.
   
   
     Another approach to querying is to exploit containment, for example:
@@ -650,12 +650,12 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu
   
    
     
-     Dot . is used for member access.
+     Dot (.) is used for member access.
     
    
    
     
-     Square brackets [] are used for array access.
+     Square brackets ([]) are used for array access.