Jsdoc

[mroderick]

This PR is, an exploration of how we might go about solving sinonjs/sinon#2003

Purpose (TL;DR)

Cover all of the public methods, and most of the internals (not anonymous functions) with JSDoc comments.

This allows us to generate API documentation, as requested in sinonjs/sinon#2003 and will also allow us to publish API documentation as suggested in sinonjs/sinon#1651.

It will also allow users of advanced IDEs to use the JSDoc for autocompletion and type checking. See Type Safe JavaScript with JSDoc

Solution

• Add jsdoc to generate documentation site
• Add eslint-plugin-jsdoc
• Add jsdoc to functions

How to verify

1. Check out this branch
2. npm install
3. npm run lint
4. Observe only one lint warning (I don't yet know how to model that one, nor am I sure we should worry about it, since it's in eslint-local-rules.js, which should be in shared package sometime soon)
5. npm run jsdoc
6. Open out/index.html
7. Observe some API documentation, that only lists the public methods currently exposed by samsam.

Checklist for author

• npm run lint passes
• References to standard library functions are cached.

[mroderick]

I can confirm that VSCode is able to read these annotations just fine.

"javascript.implicitProjectConfig.checkJs": true

Result

[codecov]

Codecov Report

Merging #82 into master will decrease coverage by <.01%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master      #82      +/-   ##
==========================================
- Coverage   98.52%   98.51%   -0.01%     
==========================================
  Files          17       17              
  Lines         473      472       -1     
==========================================
- Hits          466      465       -1     
  Misses          7        7

Flag	Coverage Δ
#unit	98.51% <100%> (-0.01%)	⬇️

Impacted Files	Coverage Δ
lib/identical.js	100% <ø> (ø)	⬆️
lib/is-subset.js	100% <ø> (ø)	⬆️
lib/is-object.js	100% <ø> (ø)	⬆️
lib/is-date.js	100% <ø> (ø)	⬆️
lib/get-class.js	100% <ø> (ø)	⬆️
lib/samsam.js	100% <ø> (ø)	⬆️
lib/match.js	96.77% <ø> (ø)	⬆️
lib/create-set.js	100% <ø> (ø)	⬆️
lib/deep-equal.js	97% <ø> (ø)	⬆️
lib/is-arguments.js	92.3% <ø> (ø)	⬆️
... and 6 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 04dfbbc...a104b10. Read the comment docs.

[mantoni]

👍