Fixes jsdoc generation, adds jsdoc support (#512)

* Fixes jsdoc generation, adds jsdoc support

* Better jsdoc config

* fixup! Better jsdoc config

* Adds better return types on some objects

* Update .travis.yml

Author: flovilmart

.gitignore

@@ -9,4 +9,5 @@ integration/test_logs
 .DS_Store
 .idea/
 integration/test_logs
+out/
 

.travis.yml

@@ -1,7 +1,7 @@
 ---
 language: node_js
 node_js:
-- '5'
+- '6.11.4'
 
 branches:
   only:

jsdoc-conf.json

@@ -0,0 +1,20 @@
+{
+  "plugins": ["node_modules/jsdoc-babel"],
+  "babel": {
+      "plugins": ["transform-flow-strip-types"]
+  },
+  "source": {
+    "include": ["./package.json", "./README.md"],
+    "excludePattern": "(^|\\/|\\\\)_"
+  },
+  "templates": {
+    "default": {
+      "outputSourceFiles": false
+    },
+    "cleverLinks": false,
+    "monospaceLinks": false
+  },
+  "opts": {
+    "recurse": true
+  }
+}

package.json

@@ -53,12 +53,15 @@
     "gulp-uglify": "^2.1.2",
     "jasmine-reporters": "~2.2.1",
     "jest-cli": "^19.0.2",
+    "jsdoc": "^3.5.5",
+    "jsdoc-babel": "^0.3.0",
     "vinyl-source-stream": "^1.1.0"
   },
   "scripts": {
     "build": "./build_releases.sh",
     "release": "./build_releases.sh && npm publish",
-    "test": "PARSE_BUILD=node jest"
+    "test": "PARSE_BUILD=node jest",
+    "docs": "jsdoc -c ./jsdoc-conf.json ./src"
   },
   "jest": {
     "automock": true,

src/Analytics.js

@@ -19,6 +19,7 @@ import type ParsePromise from './ParsePromise';
  *
  * @class Parse.Analytics
  * @static
+ * @hideconstructor
  */
 
  /**
@@ -44,6 +45,7 @@ import type ParsePromise from './ParsePromise';
   * There is a default limit of 8 dimensions per event tracked.
   *
   * @method track
+  * @name Parse.Analytics.track
   * @param {String} name The name of the custom event to report to Parse as
   * having happened.
   * @param {Object} dimensions The dictionary of information by which to

src/Cloud.js

@@ -24,11 +24,13 @@ import ParsePromise from './ParsePromise';
  *
  * @class Parse.Cloud
  * @static
+ * @hideconstructor
  */
 
  /**
   * Makes a call to a cloud function.
   * @method run
+  * @name Parse.Cloud.run
   * @param {String} name The function name.
   * @param {Object} data The parameters to send to the cloud function.
   * @param {Object} options A Backbone-style options object

src/CoreManager.js

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (c) 2015-present, Parse, LLC.
  * All rights reserved.
  *

src/FacebookUtils.js

@@ -93,6 +93,7 @@ var provider = {
  * Provides a set of utilities for using Parse with Facebook.
  * @class Parse.FacebookUtils
  * @static
+ * @hideconstructor
  */
 var FacebookUtils = {
   /**
@@ -105,6 +106,7 @@ var FacebookUtils = {
    * with these arguments.
    *
    * @method init
+   * @name Parse.FacebookUtils.init
    * @param {Object} options Facebook options argument as described here:
    *   <a href=
    *   "https://developers.facebook.com/docs/reference/javascript/FB.init/">
@@ -141,6 +143,7 @@ var FacebookUtils = {
    * Gets whether the user has their account linked to Facebook.
    *
    * @method isLinked
+   * @name Parse.FacebookUtils.isLinked
    * @param {Parse.User} user User to check for a facebook link.
    *     The user must be logged in on this device.
    * @return {Boolean} <code>true</code> if the user has their account
@@ -156,13 +159,15 @@ var FacebookUtils = {
    * creates, in the case where it is a new user) a Parse.User.
    *
    * @method logIn
-   * @param {String, Object} permissions The permissions required for Facebook
+   * @name Parse.FacebookUtils.logIn
+   * @param {(String|Object)} permissions The permissions required for Facebook
    *    log in.  This is a comma-separated string of permissions.
    *    Alternatively, supply a Facebook authData object as described in our
    *    REST API docs if you want to handle getting facebook auth tokens
    *    yourself.
    * @param {Object} options Standard options object with success and error
    *    callbacks.
+   * @returns {Parse.Promise}
    */
   logIn(permissions, options) {
     if (!permissions || typeof permissions === 'string') {
@@ -191,15 +196,17 @@ var FacebookUtils = {
    * the account to the Parse.User.
    *
    * @method link
+   * @name Parse.FacebookUtils.link
    * @param {Parse.User} user User to link to Facebook. This must be the
    *     current user.
-   * @param {String, Object} permissions The permissions required for Facebook
+   * @param {(String|Object)} permissions The permissions required for Facebook
    *    log in.  This is a comma-separated string of permissions.
    *    Alternatively, supply a Facebook authData object as described in our
    *    REST API docs if you want to handle getting facebook auth tokens
    *    yourself.
    * @param {Object} options Standard options object with success and error
    *    callbacks.
+   * @returns {Parse.Promise}
    */
   link(user, permissions, options) {
     if (!permissions || typeof permissions === 'string') {
@@ -226,10 +233,12 @@ var FacebookUtils = {
    * Unlinks the Parse.User from a Facebook account.
    *
    * @method unlink
+   * @name Parse.FacebookUtils.unlink
    * @param {Parse.User} user User to unlink from Facebook. This must be the
    *     current user.
    * @param {Object} options Standard options object with success and error
    *    callbacks.
+   * @returns {Parse.Promise}
    */
   unlink: function(user, options) {
     if (!initialized) {

src/LiveQueryClient.js

@@ -78,16 +78,6 @@ let generateInterval = (k) => {
  *
  * javascriptKey and masterKey are used for verifying the LiveQueryClient when it tries
  * to connect to the LiveQuery server
- * 
- * @class Parse.LiveQueryClient
- * @constructor
- * @param {Object} options
- * @param {string} options.applicationId - applicationId of your Parse app
- * @param {string} options.serverURL - <b>the URL of your LiveQuery server</b>
- * @param {string} options.javascriptKey (optional)
- * @param {string} options.masterKey (optional) Your Parse Master Key. (Node.js only!)
- * @param {string} options.sessionToken (optional)
- *
  *
  * We expose three events to help you monitor the status of the LiveQueryClient.
  *
@@ -119,10 +109,9 @@ let generateInterval = (k) => {
  * client.on('error', (error) => {
  * 
  * });</pre>
- * 
- * 
+ * @alias Parse.LiveQueryClient
  */
-export default class LiveQueryClient extends EventEmitter {
+class LiveQueryClient extends EventEmitter {
   attempts: number;
   id: number;
   requestId: number;
@@ -136,6 +125,14 @@ export default class LiveQueryClient extends EventEmitter {
   socket: any;
   state: string;
 
+  /**
+   * @param {Object} options
+   * @param {string} options.applicationId - applicationId of your Parse app
+   * @param {string} options.serverURL - <b>the URL of your LiveQuery server</b>
+   * @param {string} options.javascriptKey (optional)
+   * @param {string} options.masterKey (optional) Your Parse Master Key. (Node.js only!)
+   * @param {string} options.sessionToken (optional)
+   */
   constructor({
     applicationId,
     serverURL,
@@ -177,7 +174,6 @@ export default class LiveQueryClient extends EventEmitter {
    * <a href="https://github.com/ParsePlatform/parse-server/wiki/Parse-LiveQuery-Protocol-Specification">here</a> for more details. The subscription you get is the same subscription you get 
    * from our Standard API.
    * 
-   * @method subscribe
    * @param {Object} query - the ParseQuery you want to subscribe to
    * @param {string} sessionToken (optional) 
    * @return {Object} subscription
@@ -218,7 +214,6 @@ export default class LiveQueryClient extends EventEmitter {
   /**
    * After calling unsubscribe you'll stop receiving events from the subscription object.
    * 
-   * @method unsubscribe
    * @param {Object} subscription - subscription you would like to unsubscribe from.
    */ 
   unsubscribe(subscription: Object) {
@@ -240,7 +235,6 @@ export default class LiveQueryClient extends EventEmitter {
    * After open is called, the LiveQueryClient will try to send a connect request
    * to the LiveQuery server.
    * 
-   * @method open
    */ 
   open() {
     let WebSocketImplementation = this._getWebSocketImplementation();
@@ -303,7 +297,6 @@ export default class LiveQueryClient extends EventEmitter {
    * This method will close the WebSocket connection to this LiveQueryClient, 
    * cancel the auto reconnect and unsubscribe all subscriptions based on it.
    * 
-   * @method close
    */ 
   close() {
     if (this.state === CLIENT_STATE.INITIALIZED || this.state === CLIENT_STATE.DISCONNECTED) {
@@ -448,3 +441,5 @@ export default class LiveQueryClient extends EventEmitter {
     }).bind(this), time);
   }
 }
+
+export default LiveQueryClient;

src/LiveQuerySubscription.js

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright (c) 2015-present, Parse, LLC.
  * All rights reserved.
  *
@@ -16,10 +16,6 @@ import CoreManager from './CoreManager';
  * Extends events.EventEmitter
  * <a href="https://nodejs.org/api/events.html#events_class_eventemitter">cloud functions</a>.
  * 
- * @constructor
- * @param {string} id - subscription id
- * @param {string} query - query to subscribe to
- * @param {string} sessionToken - optional session token
  *
  * <p>Open Event - When you call query.subscribe(), we send a subscribe request to 
  * the LiveQuery server, when we get the confirmation from the LiveQuery server,
@@ -88,9 +84,14 @@ import CoreManager from './CoreManager';
  * 
  * });</pre></p>
  *
- * 
+ * @alias Parse.LiveQuerySubscription
  */
-export default class Subscription extends EventEmitter {
+class Subscription extends EventEmitter {
+  /*
+   * @param {string} id - subscription id
+   * @param {string} query - query to subscribe to
+   * @param {string} sessionToken - optional session token
+   */
   constructor(id, query, sessionToken) {
     super();
     this.id = id;
@@ -99,7 +100,7 @@ export default class Subscription extends EventEmitter {
   }
 
   /**
-   * @method unsubscribe
+   * closes the subscription
    */
   unsubscribe() {
     let _this = this;
@@ -110,3 +111,5 @@ export default class Subscription extends EventEmitter {
     });
   }
 }
+
+export default Subscription;