Some small doc changes based on user issues and questions

Author: cjbj

doc/api.md

@@ -2614,15 +2614,29 @@ sales =
 The `tnsnames.ora` file can be in a default location such as
 `$ORACLE_HOME/network/admin/tnsnames.ora` or
 `/etc/tnsnames.ora`. Alternatively set the `TNS_ADMIN` environment
-variable and put the file in `$TNS_ADMIN/tnsnames.ora`.
+variable and put the file in `$TNS_ADMIN/tnsnames.ora`.  For more
+information on `tnsnames.ora` files see
+[General Syntax of tnsnames.ora](https://docs.oracle.com/database/122/NETRF/local-naming-parameters-in-tnsnames-ora-file.htm#NETRF1361) in
+the Oracle documentation.
 
-Applications that request [DRCP](#drcp) connections, for example where
-the `tnsnames.ora` connection description contains `(SERVER=POOLED)`,
-must use local [Connection Pooling](#connpooling).
 
-For more information on `tnsnames.ora` files see
-[General Syntax of tnsnames.ora](https://docs.oracle.com/database/122/NETRF/local-naming-parameters-in-tnsnames-ora-file.htm#NETRF1361)
-in the Oracle documentation.
+Full connection strings can be embedded in applications:
+
+```javascript
+var oracledb = require('oracledb');
+
+oracledb.getConnection(
+  {
+    user          : "hr",
+    password      : "welcome",
+    connectString : "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=mymachine.example.com)(PORT=1521))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=orcl)))"
+  },
+  . . .
+```
+
+Applications that request [DRCP](#drcp) connections, for example where
+the connection description contains `(SERVER=POOLED)`, must use
+local [Connection Pooling](#connpooling).
 
 #### <a name="notjdbc"></a> 8.1.3 JDBC and Node-oracledb Connection Strings Compared
 
@@ -3580,7 +3594,9 @@ connection.execute(
 ```
 
 When using a [`ResultSet`](#resultsetclass), metadata is also
-available in [`result.resultSet.metaData`](#rsmetadata).
+available in [`result.resultSet.metaData`](#rsmetadata).  For queries
+using [`queryStream()`](#querystream), metadata is available via the
+`metadata` event.
 
 The metadata is an array of objects, one per column.  By default each
 object has a `name` attribute:
@@ -3723,7 +3739,7 @@ connection.execute(
 ```
 
 To do this without requiring the overhead of a 'round trip' to execute
-the `ALTER` statement, you could use a trigger:
+the `ALTER` statement, you could use a PL/SQL trigger:
 
 ```sql
 CREATE OR REPLACE TRIGGER my_logon_trigger
@@ -4749,7 +4765,7 @@ conn.execute(
   });
 ```
 
-When the LOB is no longer needed, it should be closed
+When the LOB is no longer needed, it must be closed
 with [`lob.close()`](#lobclose):
 
 ```javascript
@@ -4911,8 +4927,8 @@ text of the statement.  Bind parameters are also called bind
 variables.
 
 Using bind parameters is recommended in preference to constructing SQL
-or PL/SQL statements by string concatenation.  This is for performance
-and security.
+or PL/SQL statements by string concatenation or template literals.
+This is for performance and security.
 
 Inserted data that is bound is passed to the database separately from
 the statement text.  It can never be executed.  This means there is no
@@ -5146,7 +5162,44 @@ No duplicate binds are allowed in a DML statement with a `RETURNING`
 clause, and no duplication is allowed between bind variables in the
 DML section and the `RETURNING` section of the statement.
 
-An example of DML RETURNING binds is:
+One common use case is to return an 'auto incremented' key values.
+Given a table:
+
+```sql
+CREATE TABLE itinerary (
+    id NUMBER(11) GENERATED BY DEFAULT ON NULL AS IDENTITY(START WITH 1),
+    city VARCHAR2(40))
+```
+
+(Note: versions of Oracle Database prior to 12.1 use a SEQUENCE and
+PL/SQL TRIGGER to auto generate key values.)
+
+The auto-generated key values can be returned like:
+
+```javascript
+var oracledb = require('oracledb');
+. . .
+connection.execute(
+   "INSERT INTO itinerary (city) VALUES (:cbv)"
+ + "RETURNING id INTO :idbv",
+  {
+    cbv:  "Melbourne",
+    idbv: { type: oracledb.NUMBER, dir: oracledb.BIND_OUT }
+  },
+  function(err, result)
+  {
+    if (err) { console.error(err); return; }
+    console.log(result.outBinds);
+  });
+```
+
+This would produce output similar to:
+
+```
+{ idbv: [ 1 ] }
+```
+
+A second example of DML RETURNING binds is:
 
 ```javascript
 var oracledb = require('oracledb');