

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

Basically, I&#x27;d like to automate docs and tests as much as possible from comments like this (or something similar):<p><pre><code>    &#x2F;**
     * Adds `b` to `a`.
     *
     * @param a {Number}
     * @param b {Number}
     * @return {Number}
     * @api public
     *&#x2F;
    function add (a, b) {
      return a + b;
    }
</code></pre>
Obviously there are libraries that can do what I&#x27;m asking, but I&#x27;m having trouble finding the best one(s), so I figured I&#x27;d just ask here.  :)
======
trcollinson
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
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
Forgot to add: Compatibility with ES6/ES7 is preferred.

Edit: Found [https://github.com/tj/dox](https://github.com/tj/dox), but surely
there's a way to convert these comments (with maybe a little extra info) to
tests?

