Improve documentation for COALESCE and NULLIF. Add references for NVL

and IFNULL.

Backpatch to 8.1.X.

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index b6f1a40b4a0a46c293b852be5a352d1e1d43a943..7d603ef97822848a61f278ca0331aabfe6e0e3cd 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,5 +1,5 @@
 
 
@@ -7227,6 +7227,14 @@ SELECT ... WHERE CASE WHEN x <> 0 THEN y/x > 1.5 ELSE false END;
    COALESCE
   
 
+  
+   NVL
+  
+
+  
+   IFNULL
+  
+
 
 COALESCE(value , ...)
 
@@ -7234,9 +7242,8 @@ SELECT ... WHERE CASE WHEN x <> 0 THEN y/x > 1.5 ELSE false END;
   
    The COALESCE function returns the first of its
    arguments that is not null.  Null is returned only if all arguments
-   are null.  This is often useful to substitute a
-   default value for null values when data is retrieved for display,
-   for example:
+   are null.  It is often used to substitute a default value for 
+   null values when data is retrieved for display, for example:
 
 SELECT COALESCE(description, short_description, '(none)') ...
 
@@ -7246,7 +7253,9 @@ SELECT COALESCE(description, short_description, '(none)') ...
     Like a CASE expression, COALESCE will
     not evaluate arguments that are not needed to determine the result;
     that is, arguments to the right of the first non-null argument are
-    not evaluated.
+    not evaluated.  This SQL-standard function provides capabilities similar
+    to NVL and IFNULL, which are used in some other
+    database systems.
    
   
 
@@ -7262,16 +7271,19 @@ SELECT COALESCE(description, short_description, '(none)') ...
 
 
   
-   The NULLIF function returns a null value if and only
-   if value1 and
-   value2 are equal.  Otherwise it returns
-   value1.  This can be used to perform the
-   inverse operation of the COALESCE example
-   given above:
+   The NULLIF function returns a null value if
+   value1 and value2
+   are equal;  otherwise it returns value1.
+   This can be used to perform the inverse operation of the
+   COALESCE example given above:
 
 SELECT NULLIF(value, '(none)') ...
 
   
+  
+   If value1 is (none), return a null,
+   otherwise return value1.
+