Changes to generate type-definitions from jsdoc comments

.jsdoc-config-type-def-sandbox.json

@@ -0,0 +1,33 @@
+{
+  "tags": {
+    "allowUnknownTags": true,
+    "dictionaries": [
+      "jsdoc",
+      "closure"
+    ]
+  },
+  "source": {
+    "include": [
+      "lib/sandbox/pmapi.js",
+      "lib/sandbox/execute-context.js",
+      "lib/sandbox/cookie-jar.js"
+    ],
+    "includePattern": ".+\\.js(doc)?$",
+    "excludePattern": "(^|\\/|\\\\)_"
+  },
+  "plugins": [
+    "tsd-jsdoc/dist/plugin"
+  ],
+  "templates": {
+    "cleverLinks": true,
+    "default": {
+      "outputSourceFiles": false
+    }
+  },
+  "opts": {
+    "destination": "./types/sandbox/",
+    "template": "tsd-jsdoc/dist",
+    "outFile": "index.d.ts",
+    "recurse": true
+  }
+}

.jsdoc-config-type-def.json

@@ -0,0 +1,31 @@
+{
+  "tags": {
+    "allowUnknownTags": true,
+    "dictionaries": [
+      "jsdoc",
+      "closure"
+    ]
+  },
+  "source": {
+    "include": [
+      "lib/sandbox"
+    ],
+    "includePattern": ".+\\.js(doc)?$",
+    "excludePattern": "(^|\\/|\\\\)_"
+  },
+  "plugins": [
+    "tsd-jsdoc/dist/plugin"
+  ],
+  "templates": {
+    "cleverLinks": true,
+    "default": {
+      "outputSourceFiles": false
+    }
+  },
+  "opts": {
+    "destination": "./types",
+    "template": "tsd-jsdoc/dist",
+    "outFile": "index.d.ts",
+    "recurse": true
+  }
+}

lib/sandbox/cookie-jar.js

@@ -168,6 +168,10 @@ var CookieJar = require('tough-cookie').CookieJar,
 
     PostmanCookieJar;
 
+/**
+ * @typeof PostmanCookieJar
+ * @interface
+ */
 PostmanCookieJar = function PostmanCookieJar (cookieStore) {
     this.store = cookieStore;
     this.jar = new CookieJar(cookieStore, {

lib/sandbox/execute-context.js

@@ -32,6 +32,12 @@ module.exports = function (scope, code, execution, console, timers, pmapi) {
         // forward console
         console: console,
         // forward pm-api instance
+        /**
+         * The pm object encloses all information pertaining to the script being executed and
+         * allows one to access a copy of the request being sent or the response received.
+         * It also allows one to get and set environment and global variables.
+         * @type {Postman}
+         */
         pm: pmapi,
         // import the timers
         setTimeout: timers.setTimeout,

lib/sandbox/pmapi.js

@@ -65,15 +65,51 @@ Postman = function Postman (bridge, execution, onRequest, cookieStore) {
 
     _assignDefinedReadonly(this, /** @lends Postman.prototype */ {
         /**
-         * Contains information pertaining to the script execution
+        * Contains information pertaining to the script execution
          *
-         * @type {Object}
+         * @interface Info
          */
-        info: _assignDefinedReadonly({}, {
+
+        /**
+         * The pm.info object contains information pertaining to the script being executed.
+         * Useful information such as the request name, request Id, and iteration count are
+         * stored inside of this object.
+         * @type {Info}
+         */
+        info: _assignDefinedReadonly({}, /** @lends Info */ {
+            /**
+             * Contains information whether the script being executed is a "prerequest" or a "test" script.
+             * @type {string}
+             * @instance
+             */
             eventName: execution.target,
+
+            /**
+             * Is the value of the current iteration being run.
+             * @type {number}
+             * @instance
+             */
             iteration: execution.cursor.iteration,
+
+            /**
+             * Is the total number of iterations that are scheduled to run.
+             * @type {number}
+             * @instance
+             */
             iterationCount: execution.cursor.cycles,
+
+            /**
+             * The saved name of the individual request being run.
+             * @type {string}
+             * @instance
+             */
             requestName: execution.legacy._itemName,
+
+            /**
+             * The unique guid that identifies the request being run.
+             * @type {string}
+             * @instance
+             */
             requestId: execution.legacy._itemId
         }),
 
@@ -98,32 +134,44 @@ Postman = function Postman (bridge, execution, onRequest, cookieStore) {
         variables: execution._variables,
 
         /**
+         * The iterationData object contains data from the data file provided during a collection run.
          * @type {VariableScope}
          */
         iterationData: iterationData,
 
         /**
+         * The request object inside pm is a representation of the request for which this script is being run.
+         * For a pre-request script, this is the request that is about to be sent and when in a test script,
+         * this is the representation of the request that was sent.
          * @type {Request}
          */
         request: execution.request,
 
         /**
+         * Inside the test scripts, the pm.response object contains all information pertaining
+         * to the response that was received.
          * @type {Response}
+         * @customexclude true
          */
         response: execution.response,
 
         /**
+         * The cookies object contains a list of cookies that are associated with the domain
+         * to which the request was made.
          * @type {CookieList}
          */
         cookies: execution.cookies,
 
         /**
-         * @type {Object}
+         * @interface Visualizer
+         */
+        /**
+         * @type {Visualizer}
          */
-        visualizer: {
+        visualizer: /** @lends Visualizer */ {
             /**
              * Set visualizer template and its options
-             *
+             * @instance
              * @param {String} template - visualisation layout in form of template
              * @param {Object} [data] - data object to be used in template
              * @param {Object} [options] - options to use while processing the template
@@ -142,7 +190,6 @@ Postman = function Postman (bridge, execution, onRequest, cookieStore) {
                 }
 
                 /**
-                 * @typedef {Object} Visualizer
                  *
                  * @property {String} template - template string
                  * @property {Object} data - data to use while processing template
@@ -157,6 +204,7 @@ Postman = function Postman (bridge, execution, onRequest, cookieStore) {
 
             /**
              * Clear all visualizer data
+             * @instance
              */
             clear: function () {
                 execution.return.visualizer = undefined;
@@ -190,7 +238,7 @@ Postman = function Postman (bridge, execution, onRequest, cookieStore) {
     }
 
     /**
-     * Allows one to send request from script.
+     * Allows one to send request from script asynchronously.
      *
      * @param {Request|String} req
      * @param {Function} callback
@@ -218,6 +266,9 @@ Postman = function Postman (bridge, execution, onRequest, cookieStore) {
 };
 
 // expose chai assertion library via prototype
+/**
+ * @type {Chai.ExpectStatic}
+ */
 Postman.prototype.expect = chai.expect;
 
 // make chai use postman extension