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.
2016-07-20 05:14:51 -07:00
parent 8818cf9ff4
commit c888434580
18 changed files with 97 additions and 211 deletions
--- a/samples/client/petstore/javascript-promise/README.md
+++ b/samples/client/petstore/javascript-promise/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:04.955-07:00
+- Build date: 2016-07-11T21:45:36.147-07:00
 - Build package: class io.swagger.codegen.languages.JavascriptClientCodegen

 ## Installation
@@ -55,10 +55,25 @@ 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
 };
-api.testCodeInjectEnd(opts).then(function() {
+api.testEndpointParameters(_number, _double, _string, _byte, opts).then(function() {
  console.log('API called successfully.');
 }, function(error) {
  console.error(error);
@@ -73,7 +88,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  &#x3D;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
--- a/samples/client/petstore/javascript-promise/docs/FakeApi.md
+++ b/samples/client/petstore/javascript-promise/docs/FakeApi.md
@@ -4,53 +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  &#x3D;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
-};
-apiInstance.testCodeInjectEnd(opts).then(function() {
-  console.log('API called successfully.');
-}, function(error) {
-  console.error(error);
-});
-
-```
-
-### 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)
--- a/samples/client/petstore/javascript-promise/src/ApiClient.js
+++ b/samples/client/petstore/javascript-promise/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 = {
@@ -342,7 +342,8 @@
   * @param {Array.<String>} contentTypes An array of request MIME types.
   * @param {Array.<String>} accepts An array of acceptable response MIME types.
   * @param {(String|Array|ObjectFunction)} returnType The required type to return; can be a string for simple types or the
-   * constructor for a complex type.   * @returns {Promise} A Promise object.
+   * constructor for a complex type.
+   * @returns {Promise} A {@link https://www.promisejs.org/|Promise} object.
   */
  exports.prototype.callApi = function callApi(path, httpMethod, pathParams,
      queryParams, headerParams, formParams, bodyParam, authNames, contentTypes, accepts,
--- a/samples/client/petstore/javascript-promise/src/api/FakeApi.js
+++ b/samples/client/petstore/javascript-promise/src/api/FakeApi.js
@@ -57,39 +57,6 @@



-    /**
-     * To test code injection  &#x3D;end
-     * @param {Object} opts Optional parameters
-     * @param {String} opts.testCodeInjectEnd To test code injection  &#x3D;end
-     */
-    this.testCodeInjectEnd = function(opts) {
-      opts = opts || {};
-      var postBody = null;
-
-
-      var pathParams = {
-      };
-      var queryParams = {
-      };
-      var headerParams = {
-      };
-      var formParams = {
-        'test code inject */ &#x3D;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
-      );
-    }
-
-
    /**
     * Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 
     * Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 
@@ -106,6 +73,7 @@
     * @param {Date} opts._date None
     * @param {Date} opts.dateTime None
     * @param {String} opts.password None
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}
     */
    this.testEndpointParameters = function(_number, _double, _string, _byte, opts) {
      opts = opts || {};
@@ -172,6 +140,7 @@
     * @param {module:model/String} opts.enumQueryString Query parameter enum test (string) (default to -efg)
     * @param {Number} opts.enumQueryInteger Query parameter enum test (double)
     * @param {Number} opts.enumQueryDouble Query parameter enum test (double)
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}
     */
    this.testEnumQueryParameters = function(opts) {
      opts = opts || {};
--- a/samples/client/petstore/javascript-promise/src/api/PetApi.js
+++ b/samples/client/petstore/javascript-promise/src/api/PetApi.js
@@ -61,6 +61,7 @@
     * Add a new pet to the store
     * 
     * @param {module:model/Pet} body Pet object that needs to be added to the store
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}
     */
    this.addPet = function(body) {
      var postBody = body;
@@ -99,6 +100,7 @@
     * @param {Integer} petId Pet id to delete
     * @param {Object} opts Optional parameters
     * @param {String} opts.apiKey 
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}
     */
    this.deletePet = function(petId, opts) {
      opts = opts || {};
@@ -138,7 +140,7 @@
     * Finds Pets by status
     * 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
-     * data is of type: {Array.<module:model/Pet>}
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}, with data of type {@link Array.<module:model/Pet>}
     */
    this.findPetsByStatus = function(status) {
      var postBody = null;
@@ -176,7 +178,7 @@
     * Finds Pets by tags
     * Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
     * @param {Array.<String>} tags Tags to filter by
-     * data is of type: {Array.<module:model/Pet>}
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}, with data of type {@link Array.<module:model/Pet>}
     */
    this.findPetsByTags = function(tags) {
      var postBody = null;
@@ -214,7 +216,7 @@
     * Find pet by ID
     * Returns a single pet
     * @param {Integer} petId ID of pet to return
-     * data is of type: {module:model/Pet}
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}, with data of type {@link module:model/Pet}
     */
    this.getPetById = function(petId) {
      var postBody = null;
@@ -252,6 +254,7 @@
     * Update an existing pet
     * 
     * @param {module:model/Pet} body Pet object that needs to be added to the store
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}
     */
    this.updatePet = function(body) {
      var postBody = body;
@@ -291,6 +294,7 @@
     * @param {Object} opts Optional parameters
     * @param {String} opts.name Updated name of the pet
     * @param {String} opts.status Updated status of the pet
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}
     */
    this.updatePetWithForm = function(petId, opts) {
      opts = opts || {};
@@ -334,7 +338,7 @@
     * @param {Object} opts Optional parameters
     * @param {String} opts.additionalMetadata Additional data to pass to server
     * @param {File} opts.file file to upload
-     * data is of type: {module:model/ApiResponse}
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}, with data of type {@link module:model/ApiResponse}
     */
    this.uploadFile = function(petId, opts) {
      opts = opts || {};
--- a/samples/client/petstore/javascript-promise/src/api/StoreApi.js
+++ b/samples/client/petstore/javascript-promise/src/api/StoreApi.js
@@ -61,6 +61,7 @@
     * Delete purchase order by ID
     * For valid response try integer IDs with value &lt; 1000. Anything above 1000 or nonintegers will generate API errors
     * @param {String} orderId ID of the order that needs to be deleted
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}
     */
    this.deleteOrder = function(orderId) {
      var postBody = null;
@@ -97,7 +98,7 @@
    /**
     * Returns pet inventories by status
     * Returns a map of status codes to quantities
-     * data is of type: {Object.<String, {'String': 'Integer'}>}
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}, with data of type {@link Object.<String, {'String': 'Integer'}>}
     */
    this.getInventory = function() {
      var postBody = null;
@@ -129,7 +130,7 @@
     * Find purchase order by ID
     * 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
-     * data is of type: {module:model/Order}
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}, with data of type {@link module:model/Order}
     */
    this.getOrderById = function(orderId) {
      var postBody = null;
@@ -167,7 +168,7 @@
     * Place an order for a pet
     * 
     * @param {module:model/Order} body order placed for purchasing the pet
-     * data is of type: {module:model/Order}
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}, with data of type {@link module:model/Order}
     */
    this.placeOrder = function(body) {
      var postBody = body;
--- a/samples/client/petstore/javascript-promise/src/api/UserApi.js
+++ b/samples/client/petstore/javascript-promise/src/api/UserApi.js
@@ -61,6 +61,7 @@
     * Create user
     * This can only be done by the logged in user.
     * @param {module:model/User} body Created user object
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}
     */
    this.createUser = function(body) {
      var postBody = body;
@@ -97,6 +98,7 @@
     * Creates list of users with given input array
     * 
     * @param {Array.<module:model/User>} body List of user object
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}
     */
    this.createUsersWithArrayInput = function(body) {
      var postBody = body;
@@ -133,6 +135,7 @@
     * Creates list of users with given input array
     * 
     * @param {Array.<module:model/User>} body List of user object
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}
     */
    this.createUsersWithListInput = function(body) {
      var postBody = body;
@@ -169,6 +172,7 @@
     * Delete user
     * This can only be done by the logged in user.
     * @param {String} username The name that needs to be deleted
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}
     */
    this.deleteUser = function(username) {
      var postBody = null;
@@ -206,7 +210,7 @@
     * Get user by user name
     * 
     * @param {String} username The name that needs to be fetched. Use user1 for testing. 
-     * data is of type: {module:model/User}
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}, with data of type {@link module:model/User}
     */
    this.getUserByName = function(username) {
      var postBody = null;
@@ -245,7 +249,7 @@
     * 
     * @param {String} username The user name for login
     * @param {String} password The password for login in clear text
-     * data is of type: {'String'}
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}, with data of type {@link 'String'}
     */
    this.loginUser = function(username, password) {
      var postBody = null;
@@ -288,6 +292,7 @@
    /**
     * Logs out current logged in user session
     * 
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}
     */
    this.logoutUser = function() {
      var postBody = null;
@@ -320,6 +325,7 @@
     * This can only be done by the logged in user.
     * @param {String} username name that need to be deleted
     * @param {module:model/User} body Updated user object
+     * @return {Promise} a {@link https://www.promisejs.org/|Promise}
     */
    this.updateUser = function(username, body) {
      var postBody = body;