Programmatic JsDoc fork.

[mnaughto]

I forked jsdoc and refactored it to create a way to use it programmatically. For me, this fixed a problem I was having with jsdoc3-parser where, frequently, there would be an issue logging the output of jsdoc to the console (even if it worked by running jsdoc <filename>).

You can see more information on the changes at jsdoc/jsdoc#812 (comment), and below are the changes I made to the jsdocParser() function of index.js to get things working:

var JsDoc = require('jsdoc');
function jsdocParser(filename, cb) {  
  var jsdoc = new JsDoc(filename);
  var parsed, error;

  try {
    parsed = JSON.parse(jsdoc.dumpResults());
  } catch(ex){
    parsed = null;
    error = ex;
  }

  cb(error, parsed);


  //var cmd = path.join(__dirname, 'node_modules', '.bin', win32 ? 'jsdoc.cmd' : 'jsdoc');

  //execFile(cmd, ['-X', filename], { maxBuffer: 5120 * 1024 }, jsdocParser._onComplete.bind(null, cb));
}

[mrjoelkemp]

Hey @mnaughto. Thanks for contributing!

Glad to hear you made the effort to provide a require interface for jsdoc. I'm saddened to hear that it won't be pushed upstream to jsdoc proper.

If I were to merge your idea of switching to your fork, then I'd have to rely on your ability to stay up to date with jsdoc proper (which seems hardpressed given that you've had to make some big changes). Supporting your efforts as a custom parser to jsdox tackles the issue more appropriately.

The implementation could be something along the lines of: have your fork as a dependency in your project, require jsdoc, and supply the function as a property to grunt-jsdox. Then, grunt-jsdox could supply the parser function to jsdox. We've spoken about supporting custom parsers in jsdox (sutoiku/jsdox#39), and your issue is another reason to support it.

• To do this, you'd have to issue a PR to grunt-jsdox for supporting a new parser (should be very straightforward)
• You'd then have to submit at PR to jsdox to use a custom parser (not as straightforward, but not bad).

What are your thoughts on this approach?