Merge pull request #420 from cloudant/memory-leak-readme

Add suggestion of usage regarding Cloudant client instantiation to avoid memory leak

Author: vmatyus

README.md

@@ -145,6 +145,14 @@ style is that `Cloudant` (upper-case) is the **package** you load; whereas
 `cloudant` (lower-case) is your **connection** to your database (i.e. the result of
 calling `Cloudant()`).
 
+The `cloudant` client connection utilizes an agent with a configurable [HTTP
+connection pool](#pool-size-and-open-sockets). As such the performance of the
+client is improved when re-using the `cloudant` client connection throughout
+an application instead of repeatedly re-instantiating. It is important to
+instantiate the `cloudant` _connection_ **only once** during the application
+lifetime to reduce the overheads of memory usage and other resources such as
+unused connections.
+
 You can initialize your client in _one_ of the following ways:
 
 #### 1. Using a URL:
@@ -396,6 +404,8 @@ var cloudant = Cloudant({ url: myurl, maxAttempt: 5, plugins: [ { iamauth: { iam
 
 1. `cookieauth`
 
+   If there is no plugin specified this will be the default plugin.
+
    This plugin will automatically exchange your Cloudant credentials for a
    cookie. It will handle the authentication and ensure that the cookie is
    refreshed as required.
@@ -415,6 +425,11 @@ var cloudant = Cloudant({ url: myurl, maxAttempt: 5, plugins: [ { iamauth: { iam
    If you don't specify a username and password during the client construction
    then cookie authentication is disabled.
 
+   You can turn off automatically refreshing cookie with the following configuration:
+   ```js
+   var cloudant = Cloudant({ url: 'https://user:[email protected]', plugins: [ { cookieauth: { autoRenew: false } } ] });
+   ```
+
 2. `iamauth`
 
    IBM Cloud Identity & Access Management enables you to securely authenticate
@@ -446,6 +461,11 @@ var cloudant = Cloudant({ url: myurl, maxAttempt: 5, plugins: [ { iamauth: { iam
 
    See [IBM Cloud Identity and Access Management](https://cloud.ibm.com/docs/services/Cloudant/guides?topic=cloudant-ibm-cloud-identity-and-access-management-iam-) for more information.
 
+   You can turn off automatically refreshing token with the following configuration:
+   ```js
+   var cloudant = Cloudant({ url: 'https://user:[email protected]', plugins: [ { iamauth: { iamApiKey: 'xxxxxxxxxx', autoRenew: false } } ] });
+   ```
+
 3. `retry`
 
    This plugin will retry requests on error (e.g. connection reset errors) or on