Jsdoc

.eslintignore

@@ -2,3 +2,4 @@ coverage/*
 dist/*
 test/*-test.js
 site/*
+out/*

.eslintrc.yaml

@@ -1,6 +1,7 @@
 extends:
     - sinon
     - 'plugin:prettier/recommended'
+    - 'plugin:jsdoc/recommended'
 
 env:
   browser: true
@@ -13,6 +14,7 @@ globals:
 
 plugins:
   - ie11
+  - jsdoc
   - local-rules
 
 rules:
@@ -31,6 +33,32 @@ overrides:
     env:
         mocha: true
     rules:
+        jsdoc/check-alignment: off
+        jsdoc/check-examples: off
+        jsdoc/check-indentation: off
+        jsdoc/check-param-names: off
+        jsdoc/check-syntax: off
+        jsdoc/check-tag-names: off
+        jsdoc/check-types: off
+        jsdoc/implements-on-classes: off
+        jsdoc/match-description: off
+        jsdoc/newline-after-description: off
+        jsdoc/no-types: off
+        jsdoc/no-undefined-types: off
+        jsdoc/require-description: off
+        jsdoc/require-description-complete-sentence: off
+        jsdoc/require-example: off
+        jsdoc/require-hyphen-before-param-description: off
+        jsdoc/require-jsdoc: off
+        jsdoc/require-param: off
+        jsdoc/require-param-description: off
+        jsdoc/require-param-name: off
+        jsdoc/require-param-type: off
+        jsdoc/require-returns: off
+        jsdoc/require-returns-check: off
+        jsdoc/require-returns-description: off
+        jsdoc/require-returns-type: off
+        jsdoc/valid-types: off
         local-rules/no-prototype-methods: off
         max-nested-callbacks:
             - warn

.gitignore

@@ -4,3 +4,4 @@ site/
 coverage/
 dist/
 .nyc_output/
+out

eslint-local-rules.js

@@ -1,5 +1,12 @@
 "use strict";
 
+/**
+ * Returns an Array of prototype methods for the `prototype`
+ *
+ * @private
+ * @param  {object} prototype A prototype to examine
+ * @returns {Array}           An array of names of prototype methods
+ */
 function getPrototypeMethods(prototype) {
     /* eslint-disable local-rules/no-prototype-methods */
     return Object.getOwnPropertyNames(prototype).filter(function(name) {
@@ -31,8 +38,9 @@ module.exports = {
         create: function(context) {
             /**
              * Reports if a disallowed property is used in a CallExpression
+             *
              * @param {ASTNode} node The CallExpression node.
-             * @returns {void}
+             * @returns {undefined}
              */
             function disallowBuiltIns(node) {
                 if (

jsdoc.conf.json

@@ -0,0 +1,18 @@
+{
+    "plugins": ["plugins/markdown"],
+    "recurseDepth": 10,
+    "source": {
+        "include": "lib/",
+        "includePattern": ".+\\.js(doc)?$",
+        "excludePattern": "(^|\\/|\\\\)_"
+    },
+    "sourceType": "module",
+    "tags": {
+        "allowUnknownTags": true,
+        "dictionaries": ["jsdoc","closure"]
+    },
+    "templates": {
+        "cleverLinks": false,
+        "monospaceLinks": false
+    }
+}

lib/create-set.js

@@ -3,11 +3,17 @@
 var typeOf = require("@sinonjs/commons").typeOf;
 var forEach = require("@sinonjs/commons").prototypes.array.forEach;
 
-// This helper makes it convenient to create Set instances from a
-// collection, an overcomes the shortcoming that IE11 doesn't support
-// collection arguments
-//
-// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
+/**
+ * This helper makes it convenient to create Set instances from a
+ * collection, an overcomes the shortcoming that IE11 doesn't support
+ * collection arguments
+ *
+ * @private
+ * @param  {Array} array An array to create a set from
+ * @returns {Set} A set (unique) containing the members from array
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
+ */
 function createSet(array) {
     if (arguments.length > 0 && !Array.isArray(array)) {
         throw new TypeError(

lib/deep-equal.js

@@ -28,11 +28,7 @@ var keys = Object.keys;
 var getOwnPropertySymbols = Object.getOwnPropertySymbols;
 
 /**
- * @name samsam.deepEqual
- * @param Object actual
- * @param Object expectation
- *
- * Deep equal comparison. Two values are "deep equal" if:
+ * Deep equal comparison. Two values are "deep equal" when:
  *
  *   - They are equal, according to samsam.identical
  *   - They are both date objects representing the same time
@@ -41,6 +37,12 @@ var getOwnPropertySymbols = Object.getOwnPropertySymbols;
  *     in ``actual`` is deepEqual to the corresponding property in ``expectation``
  *
  * Supports cyclic objects.
+ *
+ * @alias module:samsam.deepEqual
+ * @param {*} actual The object to examine
+ * @param {*} expectation The object actual is expected to be equal to
+ * @param {object} match A value to match on
+ * @returns {boolean} Returns true when actual and expectation are considered equal
  */
 function deepEqualCyclic(actual, expectation, match) {
     // used for cyclic comparison

lib/deep-equal.test.js

@@ -11,8 +11,10 @@ var samsam = require("./samsam");
  *
  * IE11 doesn't populate the `stack` property of an Error until it is thrown,
  * making deepEqual misreport equality on that platform.
+ *
+ * @private
  * @param  {String} message
- * @return {Error}
+ * @returns {Error}
  */
 function createError(message) {
     try {

lib/get-class.js

@@ -2,10 +2,16 @@
 
 var toString = require("@sinonjs/commons").prototypes.object.toString;
 
+/**
+ * Returns the internal `Class` by calling `Object.prototype.toString`
+ * with the provided value as `this`. Return value is a `String`, naming the
+ * internal class, e.g. "Array"
+ *
+ * @private
+ * @param  {*} value - Any value
+ * @returns {string} - A string representation of the `Class` of `value`
+ */
 function getClass(value) {
-    // Returns the internal [[Class]] by calling Object.prototype.toString
-    // with the provided value as this. Return value is a string, naming the
-    // internal class, e.g. "Array"
     return toString(value).split(/[ \]]/)[1];
 }
 

lib/identical.js

@@ -4,15 +4,21 @@ var isNaN = require("./is-nan");
 var isNegZero = require("./is-neg-zero");
 
 /**
- * @name samsam.equal
- * @param Object obj1
- * @param Object obj2
+ * Strict equality check according to EcmaScript Harmony's `egal`.
  *
- * Returns ``true`` if two objects are strictly equal. Compared to
- * ``===`` there are two exceptions:
+ * **From the Harmony wiki:**
+ * > An `egal` function simply makes available the internal `SameValue` function
+ * > from section 9.12 of the ES5 spec. If two values are egal, then they are not
+ * > observably distinguishable.
  *
- *   - NaN is considered equal to NaN
- *   - -0 and +0 are not considered equal
+ * `identical` returns `true` when `===` is `true`, except for `-0` and
+ * `+0`, where it returns `false`. Additionally, it returns `true` when
+ * `NaN` is compared to itself.
+ *
+ * @alias module:samsam.identical
+ * @param {*} obj1 The first value to compare
+ * @param {*} obj2 The second value to compare
+ * @returns {boolean} Returns `true` when the objects are *egal*, `false` otherwise
  */
 function identical(obj1, obj2) {
     if (obj1 === obj2 || (isNaN(obj1) && isNaN(obj2))) {

lib/is-arguments.js

@@ -3,11 +3,11 @@
 var getClass = require("./get-class");
 
 /**
- * @name samsam.isArguments
- * @param Object object
+ * Returns `true` when `object` is an `arguments` object, `false` otherwise
  *
- * Returns ``true`` if ``object`` is an ``arguments`` object,
- * ``false`` otherwise.
+ * @alias module:samsam.isArguments
+ * @param  {*}  object - The object to examine
+ * @returns {boolean} `true` when `object` is an `arguments` object
  */
 function isArguments(object) {
     if (getClass(object) === "Arguments") {

lib/is-date.js

@@ -1,5 +1,12 @@
 "use strict";
 
+/**
+ * Returns `true` when `value` is an instance of Date
+ *
+ * @private
+ * @param  {Date}  value The value to examine
+ * @returns {boolean}     `true` when `value` is an instance of Date
+ */
 function isDate(value) {
     return value instanceof Date;
 }

lib/is-element.js

@@ -3,13 +3,15 @@
 var div = typeof document !== "undefined" && document.createElement("div");
 
 /**
- * @name samsam.isElement
- * @param Object object
+ * Returns `true` when `object` is a DOM element node.
  *
- * Returns ``true`` if ``object`` is a DOM element node. Unlike
- * Underscore.js/lodash, this function will return ``false`` if ``object``
- * is an *element-like* object, i.e. a regular object with a ``nodeType``
- * property that holds the value ``1``.
+ * Unlike Underscore.js/lodash, this function will return `false` if `object`
+ * is an *element-like* object, i.e. a regular object with a `nodeType`
+ * property that holds the value `1`.
+ *
+ * @alias module:samsam.isElement
+ * @param {object} object The object to examine
+ * @returns {boolean} Returns `true` for DOM element nodes
  */
 function isElement(object) {
     if (!object || object.nodeType !== 1 || !div) {

lib/is-map.js

@@ -1,5 +1,12 @@
 "use strict";
 
+/**
+ * Returns `true` when `value` is a Map
+ *
+ * @param {*} value A value to examine
+ * @returns {boolean} `true` when `value` is an instance of `Map`, `false` otherwise
+ * @private
+ */
 function isMap(value) {
     return typeof Map !== "undefined" && value instanceof Map;
 }

lib/is-nan.js

@@ -1,11 +1,19 @@
 "use strict";
 
+/**
+ * Compares a `value` to `NaN`
+ *
+ * @private
+ * @param {*} value A value to examine
+ * @returns {boolean} Returns `true` when `value` is `NaN`
+ */
 function isNaN(value) {
-    // Unlike global isNaN, this avoids type coercion
-    // typeof check avoids IE host object issues, hat tip to
+    // Unlike global `isNaN`, this function avoids type coercion
+    // `typeof` check avoids IE host object issues, hat tip to
     // lodash
-    var val = value; // JsLint thinks value !== value is "weird"
-    return typeof value === "number" && value !== val;
+
+    // eslint-disable-next-line no-self-compare
+    return typeof value === "number" && value !== value;
 }
 
 module.exports = isNaN;

lib/is-neg-zero.js

@@ -1,10 +1,11 @@
 "use strict";
 
 /**
- * @name samsam.isNegZero
- * @param Object value
+ * Returns `true` when `value` is `-0`
  *
- * Returns ``true`` if ``value`` is ``-0``.
+ * @alias module:samsam.isNegZero
+ * @param {*} value A value to examine
+ * @returns {boolean} Returns `true` when `value` is `-0`
  */
 function isNegZero(value) {
     return value === 0 && 1 / value === -Infinity;

lib/is-object.js

@@ -1,12 +1,19 @@
 "use strict";
 
-// Returns true when the value is a regular Object and not a specialized Object
-//
-// This helps speeding up deepEqual cyclic checks
-// The premise is that only Objects are stored in the visited array.
-// So if this function returns false, we don't have to do the
-// expensive operation of searching for the value in the the array of already
-// visited objects
+/**
+ * Returns `true` when the value is a regular Object and not a specialized Object
+ *
+ * This helps speed up deepEqual cyclic checks
+ *
+ * The premise is that only Objects are stored in the visited array.
+ * So if this function returns false, we don't have to do the
+ * expensive operation of searching for the value in the the array of already
+ * visited objects
+ *
+ * @private
+ * @param  {object}   value The object to examine
+ * @returns {boolean}       `true` when the object is a non-specialised object
+ */
 function isObject(value) {
     return (
         typeof value === "object" &&

lib/is-set.js

@@ -1,5 +1,12 @@
 "use strict";
 
+/**
+ * Returns `true` when the argument is an instance of Set, `false` otherwise
+ *
+ * @alias module:samsam.isSet
+ * @param  {*}  val - A value to examine
+ * @returns {boolean} Returns `true` when the argument is an instance of Set, `false` otherwise
+ */
 function isSet(val) {
     return (typeof Set !== "undefined" && val instanceof Set) || false;
 }

lib/is-subset.js

@@ -2,6 +2,16 @@
 
 var forEach = require("@sinonjs/commons").prototypes.set.forEach;
 
+/**
+ * Returns `true` when `s1` is a subset of `s2`, `false` otherwise
+ *
+ * @private
+ * @param  {Array|Set}  s1      The target value
+ * @param  {Array|Set}  s2      The containing value
+ * @param  {Function}  compare A comparison function, should return `true` when
+ *                             values are considered equal
+ * @returns {boolean} Returns `true` when `s1` is a subset of `s2`, `false`` otherwise
+ */
 function isSubset(s1, s2, compare) {
     var allContained = true;
     forEach(s1, function(v1) {