pgsql: Doc: fix out-of-date example of SPI usage.

Doc: fix out-of-date example of SPI usage.

The "count" argument of SPI_exec() only limits execution when
the query is actually returning rows.  This was not the case
before PG 9.0, so this example was correct when written; but
we missed updating it in commit 2ddc600f8.  Extend the example
to show the behavior both with and without RETURNING.

While here, improve the commentary and markup for the rest
of the example.

David G. Johnston and Tom Lane, per report from Curt Kolovson.
Back-patch to all supported branches.

Discussion: https://postgr.es/m/CANhYJV6HWtgz_qjx_APfK0PAgLUzY-2vjLuj7i_o=TZF1LAQew@mail.gmail.com

Branch
------
master

Details
-------
https://git.postgresql.org/pg/commitdiff/137b131d6fbd29b4acf740aba3f74220faef2678

Modified Files
--------------
doc/src/sgml/spi.sgml | 48 +++++++++++++++++++++++++++++++++---------------
1 file changed, 33 insertions(+), 15 deletions(-)