Add JSDoc Validation (parse-community#1240)

* Add JSDoc Validator

* fix build

* Make globals private

* remove warnings

* fix tests

Author: dplewis

.eslintrc.json

@@ -1,34 +1,69 @@
 {
-    "root": true,
-    "extends": "eslint:recommended",
-    "env": {
-        "node": true,
-        "es6": true
-    },
-    "parser": "babel-eslint",
-    "globals": { 
-        "wx": true 
-    },
-    "plugins": [
-        "flowtype"
+  "root": true,
+  "extends": [
+    "eslint:recommended",
+    "plugin:jsdoc/recommended"
+  ],
+  "env": {
+    "node": true,
+    "es6": true
+  },
+  "parser": "babel-eslint",
+  "globals": { 
+    "wx": true 
+  },
+  "plugins": [
+    "flowtype",
+    "jsdoc"
+  ],
+  "parserOptions": {
+    "ecmaVersion": 6,
+    "sourceType": "module"
+  },
+  "rules": {
+    "indent": ["error", 2],
+    "linebreak-style": ["error", "unix"],
+    "no-trailing-spaces": 2,
+    "eol-last": 2,
+    "space-in-parens": ["error", "never"],
+    "no-multiple-empty-lines": 1,
+    "prefer-const": "error",
+    "space-infix-ops": "error",
+    "no-useless-escape": "off",
+    "no-var": "error",
+    "no-console": 0,
+    "no-prototype-builtins": "off",
+    "require-atomic-updates": "off",
+    "jsdoc/require-jsdoc": 0,
+    "jsdoc/require-returns-description": 0,
+    "jsdoc/require-param-description": 0,
+    "jsdoc/require-property-description": 0,
+    "jsdoc/require-param-type": 0,
+    "jsdoc/check-param-names": [
+      "error",
+      {
+        "allowExtraTrailingParamDocs": true
+      }
     ],
-    "parserOptions": {
-        "ecmaVersion": 6,
-        "sourceType": "module"
-    },
-    "rules": {
-        "indent": ["error", 2],
-        "linebreak-style": ["error", "unix"],
-        "no-trailing-spaces": 2,
-        "eol-last": 2,
-        "space-in-parens": ["error", "never"],
-        "no-multiple-empty-lines": 1,
-        "prefer-const": "error",
-        "space-infix-ops": "error",
-        "no-useless-escape": "off",
-        "no-var": "error",
-        "no-console": 0,
-        "no-prototype-builtins": "off",
-        "require-atomic-updates": "off"
-    }
+    "jsdoc/check-tag-names": [
+      "error",
+      {
+        "definedTags": [
+          "flow",
+          "flow-weak"
+        ]
+      }
+    ],
+    "jsdoc/no-undefined-types": [
+      "error",
+      {
+        "definedTypes": [
+          "AuthProvider",
+          "AsyncStorage",
+          "LocalDatastoreController",
+          "Parse"
+        ]
+      }
+    ]
+  }
 }

integration/test/clear.js

@@ -5,6 +5,7 @@ const Parse = require('../../node');
  * Calls /clear route in integration/test/server.js
  *
  * @param {boolean} fast set to true if it's ok to just drop objects and not indexes.
+ * @returns {Promise} A promise that is resolved when database is deleted.
  */
 module.exports = function(fast = true) {
   return Parse._ajax('GET', `http://localhost:1337/clear/${fast}`, '');

package-lock.json

@@ -56,6 +56,7 @@
     "cross-env": "7.0.2",
     "eslint": "6.8.0",
     "eslint-plugin-flowtype": "5.1.2",
+    "eslint-plugin-jsdoc": "30.7.3",
     "express": "4.17.1",
     "gulp": "4.0.2",
     "gulp-babel": "8.0.0",

package.json

@@ -21,36 +21,36 @@ import CoreManager from './CoreManager';
  */
 
 /**
-  * Tracks the occurrence of a custom event with additional dimensions.
-  * Parse will store a data point at the time of invocation with the given
-  * event name.
-  *
-  * Dimensions will allow segmentation of the occurrences of this custom
-  * event. Keys and values should be {@code String}s, and will throw
-  * otherwise.
-  *
-  * To track a user signup along with additional metadata, consider the
-  * following:
-  * <pre>
-  * var dimensions = {
-  *  gender: 'm',
-  *  source: 'web',
-  *  dayType: 'weekend'
-  * };
-  * Parse.Analytics.track('signup', dimensions);
-  * </pre>
-  *
-  * 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
-  * segment this event.
-  * @return {Promise} A promise that is resolved when the round-trip
-  * to the server completes.
-  */
+ * Tracks the occurrence of a custom event with additional dimensions.
+ * Parse will store a data point at the time of invocation with the given
+ * event name.
+ *
+ * Dimensions will allow segmentation of the occurrences of this custom
+ * event. Keys and values should be {@code String}s, and will throw
+ * otherwise.
+ *
+ * To track a user signup along with additional metadata, consider the
+ * following:
+ * <pre>
+ * var dimensions = {
+ *  gender: 'm',
+ *  source: 'web',
+ *  dayType: 'weekend'
+ * };
+ * Parse.Analytics.track('signup', dimensions);
+ * </pre>
+ *
+ * There is a default limit of 8 dimensions per event tracked.
+ *
+ * @function 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
+ * segment this event.
+ * @returns {Promise} A promise that is resolved when the round-trip
+ * to the server completes.
+ */
 export function track(
   name: string,
   dimensions: { [key: string]: string }

src/Analytics.js

@@ -8,9 +8,10 @@
  *
  * @flow-weak
  */
+
 import ParseUser from './ParseUser';
-const uuidv4 = require('uuid/v4');
 import type { RequestOptions } from './RESTController';
+const uuidv4 = require('uuid/v4');
 
 let registered = false;
 
@@ -38,18 +39,19 @@ let registered = false;
  *  <li>Service linking (e.g. Facebook, Twitter) will convert the anonymous user
  *  into a standard user by linking it to the service.</li>
  * </ul>
+ *
  * @class Parse.AnonymousUtils
  * @static
  */
 const AnonymousUtils = {
   /**
    * Gets whether the user has their account linked to anonymous user.
    *
-   * @method isLinked
+   * @function isLinked
    * @name Parse.AnonymousUtils.isLinked
    * @param {Parse.User} user User to check for.
    *     The user must be logged in on this device.
-   * @return {Boolean} <code>true</code> if the user has their account
+   * @returns {boolean} <code>true</code> if the user has their account
    *     linked to an anonymous user.
    * @static
    */
@@ -61,28 +63,28 @@ const AnonymousUtils = {
   /**
    * Logs in a user Anonymously.
    *
-   * @method logIn
+   * @function logIn
    * @name Parse.AnonymousUtils.logIn
-   * @param {Object} options MasterKey / SessionToken.
-   * @returns {Promise}
+   * @param {object} options MasterKey / SessionToken.
+   * @returns {Promise} Logged in user
    * @static
    */
-  logIn(options?: RequestOptions) {
+  logIn(options?: RequestOptions): Promise<ParseUser> {
     const provider = this._getAuthProvider();
     return ParseUser.logInWith(provider.getAuthType(), provider.getAuthData(), options);
   },
 
   /**
    * Links Anonymous User to an existing PFUser.
    *
-   * @method link
+   * @function link
    * @name Parse.AnonymousUtils.link
    * @param {Parse.User} user User to link. This must be the current user.
-   * @param {Object} options MasterKey / SessionToken.
-   * @returns {Promise}
+   * @param {object} options MasterKey / SessionToken.
+   * @returns {Promise} Linked with User
    * @static
    */
-  link(user: ParseUser, options?: RequestOptions) {
+  link(user: ParseUser, options?: RequestOptions): Promise<ParseUser> {
     const provider = this._getAuthProvider();
     return user.linkWith(provider.getAuthType(), provider.getAuthData(), options);
   },