Small wording improvement and clarification in PL/pgSQL trigger documentation

diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 66731734396bba4e028e69e1089ba52f3d78f8b6..493e96e8662d90dd9b394d0b48ac122a86586571 100644 (file)
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -1,4 +1,4 @@
-
+
 
 
   <application>PL/pgSQL</application> - <acronym>SQL</acronym> Procedural Language
@@ -3197,16 +3197,26 @@ RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
     for this row).  If a nonnull
     value is returned then the operation proceeds with that row value.
     Returning a row value different from the original value
-    of NEW alters the row that will be inserted or updated
-    (but has no direct effect in the DELETE case).
-    To alter the row to be stored, it is possible to replace single values
-    directly in NEW and return the modified NEW,
-    or to build a complete new record/row to return.
+    of NEW alters the row that will be inserted or
+    updated.  Thus, if the trigger function wants the triggering
+    action to succeed normally without altering the row
+    value, NEW (or a value equal thereto) has to be
+    returned.  To alter the row to be stored, it is possible to
+    replace single values directly in NEW and return the
+    modified NEW, or to build a complete new record/row to
+    return.  In the case of a before-trigger
+    on DELETE, the returned value has no direct
+    effect, but it has to be nonnull to allow the trigger action to
+    proceed.  Note that NEW is null
+    in DELETE triggers, so returning that is
+    usually not sensible.  A useful idiom in DELETE
+    triggers might be to return OLD.
    
 
    
-    The return value of a BEFORE or AFTER
-    statement-level trigger or an AFTER row-level trigger is
+    The return value of a row-level trigger
+    fired AFTER or a statement-level trigger
+    fired BEFORE or AFTER is
     always ignored; it might as well be null. However, any of these types of
     triggers might still abort the entire operation by raising an error.