From 6ab1d7a8dd1f4df4402c726441bb6f36bb5e2f54 Mon Sep 17 00:00:00 2001
From: Catalin Iacob <iacobcatalin@gmail.com>
Date: Thu, 25 Feb 2016 07:02:18 +0100
Subject: [PATCH] Doc improvements

---
 doc/src/sgml/plpython.sgml | 34 +++++++++++++++++++---------------
 1 file changed, 19 insertions(+), 15 deletions(-)

diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index 7d31342..4ed34d6 100644
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -1341,22 +1341,23 @@ $$ LANGUAGE plpythonu;
   <title>Utility Functions</title>
   <para>
    The <literal>plpy</literal> module also provides the functions
-   <literal>plpy.debug(<replaceable>exception_params</>)</literal>,
-   <literal>plpy.log(<replaceable>exception_params</>)</literal>,
-   <literal>plpy.info(<replaceable>exception_params</>)</literal>,
-   <literal>plpy.notice(<replaceable>exception_params</>)</literal>,
-   <literal>plpy.warning(<replaceable>exception_params</>)</literal>,
-   <literal>plpy.error(<replaceable>exception_params</>)</literal>, and
-   <literal>plpy.fatal(<replaceable>exception_params</>)</literal>.<indexterm><primary>elog</><secondary>in PL/Python</></indexterm>
+   <literal>plpy.debug(<replaceable>msg, **kwargs</>)</literal>,
+   <literal>plpy.log(<replaceable>msg, **kwargs</>)</literal>,
+   <literal>plpy.info(<replaceable>msg, **kwargs</>)</literal>,
+   <literal>plpy.notice(<replaceable>msg, **kwargs</>)</literal>,
+   <literal>plpy.warning(<replaceable>msg, **kwargs</>)</literal>,
+   <literal>plpy.error(<replaceable>msg, **kwargs</>)</literal>, and
+   <literal>plpy.fatal(<replaceable>msg, **kwargs</>)</literal>.<indexterm><primary>elog</><secondary>in PL/Python</></indexterm>
    <function>plpy.error</function> and
    <function>plpy.fatal</function> actually raise a Python exception
    which, if uncaught, propagates out to the calling query, causing
    the current transaction or subtransaction to be aborted.
    <literal>raise plpy.Error(<replaceable>msg</>)</literal> and
    <literal>raise plpy.Fatal(<replaceable>msg</>)</literal> are
-   partial equivalent to calling
-   <function>plpy.error</function> and
-   <function>plpy.fatal</function>, respectively.
+   equivalent to calling
+   <literal>plpy.error(<replaceable>msg</>)</literal> and
+   <literal>plpy.fatal(<replaceable>msg</>)</literal>, respectively but
+   the <literal>raise</literal> form does not allow passing keyword arguments.
    The other functions only generate messages of different
    priority levels.
    Whether messages of a particular priority are reported to the client,
@@ -1368,11 +1369,14 @@ $$ LANGUAGE plpythonu;
 
   <para>
 
-   The <replaceable>exception_params</> are
-   <literal>[ <replaceable>message</replaceable> [, <replaceable>detail</replaceable> [, <replaceable>hint</replaceable> [, <replaceable>sqlstate</replaceable>  [, <replaceable>schema</replaceable>  [, <replaceable>table</replaceable>  [, <replaceable>column</replaceable>  [, <replaceable>datatype</replaceable>  [, <replaceable>constraint</replaceable> ]]]]]]]]]</literal>.
-   These parameters kan be entered as keyword parameters.
-   The <replaceable>message</replaceable>, <replaceable>detail</replaceable>, <replaceable>hint</replaceable>
-   are automaticly casted to string, other should be string.
+   The <replaceable>msg</> argument is given as a positional argument.  For
+   backward compatibility, more than one positional argument can be given. In
+   that case, the string representation of the tuple of positional arguments
+   becomes the message reported to the client.
+   The following keyword-only arguments are accepted:
+   <literal><replaceable>detail</replaceable>, <replaceable>hint</replaceable>, <replaceable>sqlstate</replaceable>, <replaceable>schema</replaceable>, <replaceable>table</replaceable>, <replaceable>column</replaceable>, <replaceable>datatype</replaceable> , <replaceable>constraint</replaceable></literal>.
+   The string representation of the objects passed as keyword-only arguments
+   is used to enrich the messages reported to the client. For example:
 
 <programlisting>
 CREATE FUNCTION raise_custom_exception() RETURNS void AS $$
-- 
2.7.1