The attached patches adds an "Example Result" column to the json/jsonb
operators table[1] that has the evaluated result of each example. I
think this makes it much easy to reason what each operator does. The
two patches are mutually exclusive and I recommend using the -better
patch.
The patches only touches the json and jsonb operators table, the
additional jsonb operators table is left without example results. All
the results for those examples are "true" so I don't think it's
needed. Maybe wouldn't hurt though.
[1]: http://www.postgresql.org/docs/devel/static/functions-json.html
The first file (docs-json-operator-example.diff) adds results for the
existing operator examples.
The other file (docs-json-operator-example-better.diff) replaces some
of the examples that return JSON objects so that the result is an
object (not a scalar). I like this one better.
For the operator examples that return json (as opposed to text), I
think the result should be a non-scalar. It makes it easier for
someone new reading the operator docs to understand which situations
they are used for.
For example, both of the following return "3" as a result but they
mean different things that are only apparent if you understand the
difference between the > and >> operators (ie look at the PG return
type).
=> SELECT x->'a'
-> , pg_typeof(x->'a')
-> , x->>'a'
-> , pg_typeof(x->>'a')
-> FROM (SELECT '{"a":3}'::json as x) t;
?column? | pg_typeof | ?column? | pg_typeof
----------+-----------+----------+-----------
3 | json | 3 | text
(1 row)
Whereas, the following clearly shows that it's returning an JSON
object with a PG type of json, not a scalar:
=> SELECT '{"a": {"b":"foo"}}'::json->'a';
?column?
-------------
{"b":"foo"}
(1 row)
A related thought is changing the scalar results for the remaining
examples to something other than a single digit integer. Again, this
is to avoid confusion as someone new looking at it may not immediately
understand that it's actually a text string. Either that or showing it
in quotes so that it's apparent that it's text and not a number.
Regards,
-- Sehrope Sarkuni
Founder & CEO | JackDB, Inc. | http://www.jackdb.com/