Ask HN: Best libraries for converting JavaScript comments to both docs and tests?

3 points by tfb 10 years ago | 3 comments

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;
    }

Obviously there are libraries that can do what I'm asking, but I'm having trouble finding the best one(s), so I figured I'd just ask here. :)

trcollinson 10 years ago |

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
   *
   */

Then the documentation could link out to the specific test or tests for this method. Though if you are going to go this route you will probably want some sort of automated code analysis to find the test locations and link them in. Creating rudimentary documentation from these comments should be trivial.

tfb 10 years ago | |

The comment block I provided was just an example. It can be changed to anything that would make the most sense for generating tests.

tfb 10 years ago |

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?