improving warnings stack + docs.

Author: vitaly-t

lib/database.js

@@ -11,7 +11,8 @@ var $npm = {
     task: require('./task')
 };
 
-var $arr = require('./array');
+var $arr = require('./array'),
+    EOL = require('os').EOL;
 
 /**
  * @constructor Database
@@ -22,16 +23,28 @@ var $arr = require('./array');
  *
  * **IMPORTANT:**
  *
- * For any given connection, you should only create a single database object in a separate module,
- * to be shared in your application. If instead you keep creating the database object dynamically,
- * your application will suffer from loss in performance and memory leaks because of event handlers
- * that each database object needs to set up.
+ * For any given connection, you should only create a single {@link Database} object in a separate module,
+ * to be shared in your application (see the code example below). If instead you keep creating the {@link Database}
+ * object dynamically, your application will suffer from loss in performance and memory leaks because of event
+ * handlers that each {@link Database} object needs to set up.
  *
- * Starting with version 4.7.0, if you create more than one database object for the same connection,
- * you will see the following warning in a development environment (`NODE_ENV` = `development`):
- * `WARNING: Creating a duplicate database object for the same connection.`
+ * **Starting with v.4.7.0:**
+ * 
+ * If you create more than one {@link Database} object for the same connection, you will see the following warning
+ * in a development environment (when `NODE_ENV` = `development`):
+ * 
+ * `WARNING: Creating a duplicate database object for the same connection`.
+ * 
+ * And since every {@link Database} object needs to set up its own event listeners, you are likely to see the following
+ * warning in the console also:
+ * 
+ * `Warning: Possible EventEmitter memory leak detected. 11 error listeners added. Use emitter.setMaxListeners() to increase limit`.
+ * 
+ * If you ever see any of those warnings, do not try increasing the limit, this won't help you.
+ * Instead, rectify your {@link Database} object initialization, so there is only one object per connection details.
+ * See the example provided below.
  *
- * See also property `noWarnings` in {@link module:pg-promise Initialization Options}.
+ * See also: property `noWarnings` in {@link module:pg-promise Initialization Options}.
  *
  * @param {String|Object} cn
  * Database connection details, which can be:
@@ -73,7 +86,7 @@ var $arr = require('./array');
  * {@link event:extend extend}
  *
  * @example
- * 'use strict';
+ * // Proper way to initialize and share the Database object
  *
  * // Loading and initializing the library:
  * var pgp = require('pg-promise')({
@@ -86,7 +99,7 @@ var $arr = require('./array');
  * // Creating a new database instance from the connection details:
  * var db = pgp(cn);
  *
- * // Exporting the database object:
+ * // Exporting the database object for shared use:
  * module.exports = db;
  */
 function Database(cn, dc, config) {
@@ -1201,8 +1214,11 @@ function checkForDuplicates(cn, config) {
     var cnKey = JSON.stringify(cn);
     if (cnKey in dbObjects) {
         if (!config.options.noWarnings) {
-            var msg = "WARNING: Creating a duplicate database object for the same connection.\n" +
-                new Error().stack.split('\n').slice(4, 9).join('\n') + '\n';
+            var stack = new Error().stack.split('\n').slice(4).filter(function (line) {
+                return line.match(/\(.*(\\+|\/+).*\)/);
+            }).join('\n');
+            var msg = "WARNING: Creating a duplicate database object for the same connection." +
+                EOL + stack + EOL;
             $npm.utils.printWarning(msg);
         }
     } else {

lib/index.js

@@ -71,7 +71,7 @@ var $npm = {
  * @param {boolean} [options.noWarnings]
  * **Added in v.4.7.0**
  *
- * Disables all diagnostic warnings in the library.
+ * Disables all diagnostic warnings in the library (which is ill-advised).
  *
  * If it is not set (missing or `undefined`), it will default to the following:
  * - `true`, if `NODE_ENV` != `development`