from Hacker News

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

by tfb on 8/4/15, 4:22 PM with 3 comments

    /**
     * Adds `b` to `a`.
     *
     * @param a {Number}
     * @param b {Number}
     * @return {Number}
     * @api public
     */
    function add (a, b) {
      return a + b;
    }

• by trcollinson on 8/4/15, 8:06 PM

  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.

• by tfb on 8/4/15, 4:26 PM

  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?