Ask HN: Best libraries for converting JavaScript comments to both docs and tests?
Basically, I'd like to automate docs and tests as much as possible from comments like this (or something similar):
/**
* Adds `b` to `a`.
*
* @param a {Number}
* @param b {Number}
* @return {Number}
* @api public
*/
function add (a, b) {
return a + b;
}
How exactly would you like to be able to turn these into tests? I can see how this would turn into some sort of rudimentary documentation. However, the testing is a bit harder. Looking at your example, from the comments we know that your method accepts two numbers and returns a number. So what should the test framework do? @param a = 5, @param b = -23482739, @return = 9038745. Wait, no that's not right, the test failed. I guess you could run some rudimentary tests like "Does @param a only accept numbers?" or "Does @return only return a number?" or even "Is the add method in the @api public?" but I am not sure I see the value of that.
Now what you might want is something like:
/**
* Adds `b` to `a`.
*
* @param a {Number}
* @param b {Number}
* @return {Number}
* @api public
* @test https://github.com/blah/something/blob/master/test/add_test.js#L53
*
*/
The comment block I provided was just an example. It can be changed to anything that would make the most sense for generating tests.
Forgot to add: Compatibility with ES6/ES7 is preferred.
Edit: Found https://github.com/tj/dox, but surely there's a way to convert these comments (with maybe a little extra info) to tests?