Improve jsdoc for API return values (#3327)

* Add jsdoc for usePromises, add @link for callbacks

* Update petstore samples

* Improve jsdoc for void return type + usePromises

* Add back curly brackets correctly in model template

* Add link to Promise doc in jsdoc comment

* Fix jsdoc annotation for callApi method

The return type annotation was also broken here.

samples/client/petstore/javascript/README.md

@@ -6,7 +6,7 @@ This SDK is automatically generated by the [Swagger Codegen](https://github.com/
 
 - API version: 1.0.0
 - Package version: 1.0.0
-- Build date: 2016-06-29T13:53:00.479-07:00
+- Build date: 2016-07-11T21:45:28.055-07:00
 - Build package: class io.swagger.codegen.languages.JavascriptClientCodegen
 
 ## Installation
@@ -55,8 +55,23 @@ var SwaggerPetstore = require('swagger_petstore');
 
 var api = new SwaggerPetstore.FakeApi()
 
+var _number = 3.4; // {Number} None
+
+var _double = 1.2; // {Number} None
+
+var _string = "_string_example"; // {String} None
+
+var _byte = "B"; // {String} None
+
 var opts = { 
-  'testCodeInjectEnd': "testCodeInjectEnd_example" // {String} To test code injection  =end
+  'integer': 56, // {Integer} None
+  'int32': 56, // {Integer} None
+  'int64': 789, // {Integer} None
+  '_float': 3.4, // {Number} None
+  'binary': "B", // {String} None
+  '_date': new Date("2013-10-20"), // {Date} None
+  'dateTime': new Date("2013-10-20T19:20:30+01:00"), // {Date} None
+  'password': "password_example" // {String} None
 };
 
 var callback = function(error, data, response) {
@@ -66,7 +81,7 @@ var callback = function(error, data, response) {
     console.log('API called successfully.');
   }
 };
-api.testCodeInjectEnd(opts, callback);
+api.testEndpointParameters(_number, _double, _string, _byte, opts, callback);
 
 ```
 
@@ -76,7 +91,6 @@ All URIs are relative to *http://petstore.swagger.io/v2*
 
 Class | Method | HTTP request | Description
 ------------ | ------------- | ------------- | -------------
-*SwaggerPetstore.FakeApi* | [**testCodeInjectEnd**](docs/FakeApi.md#testCodeInjectEnd) | **PUT** /fake | To test code injection  =end
 *SwaggerPetstore.FakeApi* | [**testEndpointParameters**](docs/FakeApi.md#testEndpointParameters) | **POST** /fake | Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 
 *SwaggerPetstore.FakeApi* | [**testEnumQueryParameters**](docs/FakeApi.md#testEnumQueryParameters) | **GET** /fake | To test enum query parameters
 *SwaggerPetstore.PetApi* | [**addPet**](docs/PetApi.md#addPet) | **POST** /pet | Add a new pet to the store

samples/client/petstore/javascript/docs/FakeApi.md

@@ -4,56 +4,10 @@ All URIs are relative to *http://petstore.swagger.io/v2*
 
 Method | HTTP request | Description
 ------------- | ------------- | -------------
-[**testCodeInjectEnd**](FakeApi.md#testCodeInjectEnd) | **PUT** /fake | To test code injection  =end
 [**testEndpointParameters**](FakeApi.md#testEndpointParameters) | **POST** /fake | Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 
 [**testEnumQueryParameters**](FakeApi.md#testEnumQueryParameters) | **GET** /fake | To test enum query parameters
 
 
-<a name="testCodeInjectEnd"></a>
-# **testCodeInjectEnd**
-> testCodeInjectEnd(opts)
-
-To test code injection  &#x3D;end
-
-### Example
-```javascript
-var SwaggerPetstore = require('swagger_petstore');
-
-var apiInstance = new SwaggerPetstore.FakeApi();
-
-var opts = { 
-  'testCodeInjectEnd': "testCodeInjectEnd_example" // String | To test code injection  =end
-};
-
-var callback = function(error, data, response) {
-  if (error) {
-    console.error(error);
-  } else {
-    console.log('API called successfully.');
-  }
-};
-apiInstance.testCodeInjectEnd(opts, callback);
-```
-
-### Parameters
-
-Name | Type | Description  | Notes
-------------- | ------------- | ------------- | -------------
- **testCodeInjectEnd** | **String**| To test code injection  &#x3D;end | [optional] 
-
-### Return type
-
-null (empty response body)
-
-### Authorization
-
-No authorization required
-
-### HTTP request headers
-
- - **Content-Type**: application/json, */ =end));(phpinfo(
- - **Accept**: application/json, */ end
-
 <a name="testEndpointParameters"></a>
 # **testEndpointParameters**
 > testEndpointParameters(_number, _double, _string, _byte, opts)

samples/client/petstore/javascript/src/ApiClient.js

@@ -154,7 +154,7 @@
   /**
    * Checks whether the given parameter value represents file-like content.
    * @param param The parameter to check.
-   * @returns {Boolean} <code>true</code> if <code>param</code> represents a file. 
+   * @returns {Boolean} <code>true</code> if <code>param</code> represents a file.
    */
   exports.prototype.isFileParam = function(param) {
     // fs.ReadStream in Node.js (but not in runtime like browserify)
@@ -206,7 +206,7 @@
 
   /**
    * Enumeration of collection format separator strategies.
-   * @enum {String} 
+   * @enum {String}
    * @readonly
    */
   exports.CollectionFormatEnum = {

samples/client/petstore/javascript/src/api/FakeApi.js

@@ -56,47 +56,6 @@
     this.apiClient = apiClient || ApiClient.instance;
 
 
-    /**
-     * Callback function to receive the result of the testCodeInjectEnd operation.
-     * @callback module:api/FakeApi~testCodeInjectEndCallback
-     * @param {String} error Error message, if any.
-     * @param data This operation does not return a value.
-     * @param {String} response The complete HTTP response.
-     */
-
-    /**
-     * To test code injection  =end
-     * @param {Object} opts Optional parameters
-     * @param {String} opts.testCodeInjectEnd To test code injection  =end
-     * @param {module:api/FakeApi~testCodeInjectEndCallback} callback The callback function, accepting three arguments: error, data, response
-     */
-    this.testCodeInjectEnd = function(opts, callback) {
-      opts = opts || {};
-      var postBody = null;
-
-
-      var pathParams = {
-      };
-      var queryParams = {
-      };
-      var headerParams = {
-      };
-      var formParams = {
-        'test code inject */ =end': opts['testCodeInjectEnd']
-      };
-
-      var authNames = [];
-      var contentTypes = ['application/json', '*/ =end));(phpinfo('];
-      var accepts = ['application/json', '*/ end'];
-      var returnType = null;
-
-      return this.apiClient.callApi(
-        '/fake', 'PUT',
-        pathParams, queryParams, headerParams, formParams, postBody,
-        authNames, contentTypes, accepts, returnType, callback
-      );
-    }
-
     /**
      * Callback function to receive the result of the testEndpointParameters operation.
      * @callback module:api/FakeApi~testEndpointParametersCallback

samples/client/petstore/javascript/src/api/PetApi.js

@@ -162,7 +162,7 @@
      * Multiple status values can be provided with comma separated strings
      * @param {Array.<module:model/String>} status Status values that need to be considered for filter
      * @param {module:api/PetApi~findPetsByStatusCallback} callback The callback function, accepting three arguments: error, data, response
-     * data is of type: {Array.<module:model/Pet>}
+     * data is of type: {@link Array.<module:model/Pet>}
      */
     this.findPetsByStatus = function(status, callback) {
       var postBody = null;
@@ -208,7 +208,7 @@
      * Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
      * @param {Array.<String>} tags Tags to filter by
      * @param {module:api/PetApi~findPetsByTagsCallback} callback The callback function, accepting three arguments: error, data, response
-     * data is of type: {Array.<module:model/Pet>}
+     * data is of type: {@link Array.<module:model/Pet>}
      */
     this.findPetsByTags = function(tags, callback) {
       var postBody = null;
@@ -254,7 +254,7 @@
      * Returns a single pet
      * @param {Integer} petId ID of pet to return
      * @param {module:api/PetApi~getPetByIdCallback} callback The callback function, accepting three arguments: error, data, response
-     * data is of type: {module:model/Pet}
+     * data is of type: {@link module:model/Pet}
      */
     this.getPetById = function(petId, callback) {
       var postBody = null;
@@ -398,7 +398,7 @@
      * @param {String} opts.additionalMetadata Additional data to pass to server
      * @param {File} opts.file file to upload
      * @param {module:api/PetApi~uploadFileCallback} callback The callback function, accepting three arguments: error, data, response
-     * data is of type: {module:model/ApiResponse}
+     * data is of type: {@link module:model/ApiResponse}
      */
     this.uploadFile = function(petId, opts, callback) {
       opts = opts || {};

samples/client/petstore/javascript/src/api/StoreApi.js

@@ -113,7 +113,7 @@
      * Returns pet inventories by status
      * Returns a map of status codes to quantities
      * @param {module:api/StoreApi~getInventoryCallback} callback The callback function, accepting three arguments: error, data, response
-     * data is of type: {Object.<String, {'String': 'Integer'}>}
+     * data is of type: {@link Object.<String, {'String': 'Integer'}>}
      */
     this.getInventory = function(callback) {
       var postBody = null;
@@ -153,7 +153,7 @@
      * For valid response try integer IDs with value &lt;&#x3D; 5 or &gt; 10. Other values will generated exceptions
      * @param {Integer} orderId ID of pet that needs to be fetched
      * @param {module:api/StoreApi~getOrderByIdCallback} callback The callback function, accepting three arguments: error, data, response
-     * data is of type: {module:model/Order}
+     * data is of type: {@link module:model/Order}
      */
     this.getOrderById = function(orderId, callback) {
       var postBody = null;
@@ -199,7 +199,7 @@
      * 
      * @param {module:model/Order} body order placed for purchasing the pet
      * @param {module:api/StoreApi~placeOrderCallback} callback The callback function, accepting three arguments: error, data, response
-     * data is of type: {module:model/Order}
+     * data is of type: {@link module:model/Order}
      */
     this.placeOrder = function(body, callback) {
       var postBody = body;

samples/client/petstore/javascript/src/api/UserApi.js

@@ -246,7 +246,7 @@
      * 
      * @param {String} username The name that needs to be fetched. Use user1 for testing. 
      * @param {module:api/UserApi~getUserByNameCallback} callback The callback function, accepting three arguments: error, data, response
-     * data is of type: {module:model/User}
+     * data is of type: {@link module:model/User}
      */
     this.getUserByName = function(username, callback) {
       var postBody = null;
@@ -293,7 +293,7 @@
      * @param {String} username The user name for login
      * @param {String} password The password for login in clear text
      * @param {module:api/UserApi~loginUserCallback} callback The callback function, accepting three arguments: error, data, response
-     * data is of type: {'String'}
+     * data is of type: {@link 'String'}
      */
     this.loginUser = function(username, password, callback) {
       var postBody = null;