Add JSDoc to public properties

eslint-local-rules.js

@@ -1,3 +1,4 @@
+/* eslint-disable jsdoc/require-jsdoc, jsdoc/no-undefined-types */
 "use strict";
 
 function getPrototypeMethods(prototype) {
@@ -31,6 +32,7 @@ module.exports = {
         create: function(context) {
             /**
              * Reports if a disallowed property is used in a CallExpression
+             *
              * @param {ASTNode} node The CallExpression node.
              * @returns {void}
              */

lib/called-in-order.js

@@ -2,6 +2,9 @@
 
 var every = require("./prototypes/array").every;
 
+/**
+ * @private
+ */
 function hasCallsLeft(callMap, spy) {
     if (callMap[spy.id] === undefined) {
         callMap[spy.id] = 0;
@@ -10,6 +13,9 @@ function hasCallsLeft(callMap, spy) {
     return callMap[spy.id] < spy.callCount;
 }
 
+/**
+ * @private
+ */
 function checkAdjacentCalls(callMap, spy, index, spies) {
     var calledBeforeNext = true;
 
@@ -25,10 +31,27 @@ function checkAdjacentCalls(callMap, spy, index, spies) {
     return false;
 }
 
-module.exports = function calledInOrder(spies) {
+/**
+ * A Sinon proxy object (fake, spy, stub)
+ *
+ * @typedef {object} SinonProxy
+ * @property {Function} calledBefore - A method that determines if this proxy was called before another one
+ * @property {string} id - Some id
+ * @property {number} callCount - Number of times this proxy has been called
+ */
+
+/**
+ * Returns true when the spies have been called in the order they were supplied in
+ *
+ * @param  {SinonProxy[] | SinonProxy} spies An array of proxies, or several proxies as arguments
+ * @returns {boolean} true when spies are called in order, false otherwise
+ */
+function calledInOrder(spies) {
     var callMap = {};
     // eslint-disable-next-line no-underscore-dangle
     var _spies = arguments.length > 1 ? arguments : spies;
 
     return every(_spies, checkAdjacentCalls.bind(null, callMap));
-};
+}
+
+module.exports = calledInOrder;

lib/class-name.js

@@ -2,7 +2,13 @@
 
 var functionName = require("./function-name");
 
-module.exports = function className(value) {
+/**
+ * Returns a display name for a value from a constructor
+ *
+ * @param  {object} value A value to examine
+ * @returns {(string|null)} A string or null
+ */
+function className(value) {
     return (
         (value.constructor && value.constructor.name) ||
         // The next branch is for IE11 support only:
@@ -16,4 +22,6 @@ module.exports = function className(value) {
             functionName(value.constructor)) ||
         null
     );
-};
+}
+
+module.exports = className;

lib/deprecated.js

@@ -1,8 +1,14 @@
 /* eslint-disable no-console */
 "use strict";
 
-// wrap returns a function that will invoke the supplied function and print a deprecation warning to the console each
-// time it is called.
+/**
+ * Returns a function that will invoke the supplied function and print a
+ * deprecation warning to the console each time it is called.
+ *
+ * @param  {Function} func
+ * @param  {string} msg
+ * @returns {Function}
+ */
 exports.wrap = function(func, msg) {
     var wrapped = function() {
         exports.printWarning(msg);
@@ -14,8 +20,14 @@ exports.wrap = function(func, msg) {
     return wrapped;
 };
 
-// defaultMsg returns a string which can be supplied to `wrap()` to notify the user that a particular part of the
-// sinon API has been deprecated.
+/**
+ * Returns a string which can be supplied to `wrap()` to notify the user that a
+ * particular part of the sinon API has been deprecated.
+ *
+ * @param  {string} packageName
+ * @param  {string} funcName
+ * @returns {string}
+ */
 exports.defaultMsg = function(packageName, funcName) {
     return (
         packageName +
@@ -27,6 +39,12 @@ exports.defaultMsg = function(packageName, funcName) {
     );
 };
 
+/**
+ * Prints a warning on the console, when it exists
+ *
+ * @param  {string} msg
+ * @returns {undefined}
+ */
 exports.printWarning = function(msg) {
     // Watch out for IE7 and below! :(
     /* istanbul ignore next */

lib/every.js

@@ -1,6 +1,13 @@
 "use strict";
 
-// This is an `every` implementation that works for all iterables
+/**
+ * Returns true when fn returns true for all members of obj.
+ * This is an every implementation that works for all iterables
+ *
+ * @param  {object}   obj
+ * @param  {Function} fn
+ * @returns {boolean}
+ */
 module.exports = function every(obj, fn) {
     var pass = true;
 

lib/function-name.js

@@ -1,5 +1,11 @@
 "use strict";
 
+/**
+ * Returns a display name for a function
+ *
+ * @param  {Function} func
+ * @returns {string}
+ */
 module.exports = function functionName(func) {
     if (!func) {
         return "";

lib/global.js

@@ -1,6 +1,12 @@
 "use strict";
 
+/**
+ * A reference to the global object
+ *
+ * @type {object} globalObject
+ */
 var globalObject;
+
 /* istanbul ignore else */
 if (typeof global !== "undefined") {
     // Node

lib/order-by-first-call.js

@@ -3,6 +3,9 @@
 var sort = require("./prototypes/array").sort;
 var slice = require("./prototypes/array").slice;
 
+/**
+ * @private
+ */
 function comparator(a, b) {
     // uuid, won't ever be equal
     var aCall = a.getCall(0);
@@ -13,6 +16,21 @@ function comparator(a, b) {
     return aId < bId ? -1 : 1;
 }
 
-module.exports = function orderByFirstCall(spies) {
+/**
+ * A Sinon proxy object (fake, spy, stub)
+ *
+ * @typedef {object} SinonProxy
+ * @property {Function} getCall - A method that can return the first call
+ */
+
+/**
+ * Sorts an array of SinonProxy instances (fake, spy, stub) by their first call
+ *
+ * @param  {SinonProxy[] | SinonProxy} spies
+ * @returns {SinonProxy[]}
+ */
+function orderByFirstCall(spies) {
     return sort(slice(spies), comparator);
-};
+}
+
+module.exports = orderByFirstCall;

lib/type-of.js

@@ -2,6 +2,12 @@
 
 var type = require("type-detect");
 
+/**
+ * Returns the lower-case result of running type from type-detect on the value
+ *
+ * @param  {*} value
+ * @returns {string}
+ */
 module.exports = function typeOf(value) {
     return type(value).toLowerCase();
 };

lib/value-to-string.js

@@ -1,5 +1,11 @@
 "use strict";
 
+/**
+ * Returns a string representation of the value
+ *
+ * @param  {*} value
+ * @returns {string}
+ */
 function valueToString(value) {
     if (value && value.toString) {
         /* eslint-disable-next-line local-rules/no-prototype-methods */

package.json

@@ -33,8 +33,9 @@
     "@studio/changes": "^2.0.0",
     "eslint": "^6.1.0",
     "eslint-config-prettier": "^6.3.0",
-    "eslint-config-sinon": "^3.0.0",
+    "eslint-config-sinon": "^4.0.0",
     "eslint-plugin-ie11": "^1.0.0",
+    "eslint-plugin-jsdoc": "^21.0.0",
     "eslint-plugin-local-rules": "^0.1.0",
     "eslint-plugin-mocha": "^6.1.1",
     "eslint-plugin-prettier": "^3.0.0",