Discussion: Remove markdown parsing from dox?

[Twipped]

This issue is for discussion of possibly changing dox to use CommonMark standard markdown parsing, via the commonmark npm package removing markdown parsing from the main library, possibly making it an example or extension module.

The first opportunity to make this change would be for a 1.0 release. I welcome comments either for or against this change. I'll be leaving this open until I hear some feedback or have reached a point that I feel dox is ready for 1.0.

[Twipped]

Another possibility might be simply removing markdown entirely. Split the command line tool out as a separate package and refocus dox as just a jsdoc parser. Let implementers choose their own markdown engine.

[tmcw]

I'd definitely support splitting it out. For documentation we're trying to keep markdown & html as separate concerns to parsing jsdoc & inferring from code.

[puzrin]

https://github.com/markdown-it/markdown-it that's an alternative CM parser.

[trusktr]

👍 to the ability to choose which markdown parser is used.

What about if dox uses some parser by default like commonmark or markdown-it, but make it easy to specify a markdown parser, f.e.

// ...

var someAwesomeMarkdownParser = require('awesome-markdown-parser');

// set the markdown parser that dox will be using anytime parseComments is called
dox.markdownParser(function(input) {
  // assuming someAwesomeMarkdownParser is synchronous:
  return someAwesomeMarkdownParser(input);
});

dox.parseComments(someCode, options);

[Twipped]

Technically there's nothing preventing anyone from using their own parser today. Just pass in raw:true and run the output yourself (that's how I do it on my own doc sites).

That said, it'd be trivial to take a callback option to use for conversion.

On Mar 22, 2015, at 8:46 PM, Joseph Orbegoso Pea notifications@github.com wrote:

to the ability to choose which markdown parser is used.

What about if dox uses some parser by default like commonmark or markdown-it, but make it easy to specify a markdown parser, f.e.

// ...

var someAwesomeMarkdownParser = require('awesome-markdown-parser');

// set the markdown parser that dox will be using anytime parseComments is called
dox.markdownParser(function(input) {
// assuming someAwesomeMarkdownParser is synchronous:
return someAwesomeMarkdownParser(input);
});

dox.parseComments(someCode, options);
—
Reply to this email directly or view it on GitHub.

[tomek-he-him]

For documentation we're trying to keep markdown & html as separate concerns to parsing jsdoc & inferring from code.

...

Just pass in raw:true and run the output yourself (that's how I do it on my own doc sites)

I do so too. Perhaps even most of us do?

To be honest, parsing markdown has seemed a cross-cutting concern to me – from the very beginning I started using dox.

[trusktr]

I'm think removing it from dox itself would be best.

Then, generally speaking, dox could be made pluggable and features could be added via plugin modules, and users could do something like

// ...
var dox = require('dox')
var doxMarkdownIt = require('dox-markdown-it')
var someOtherPluginForDox = require('dox-blahblah')

dox.use(doxMarkdownIt)
dox.use(someOtherPluginForDox)

var comments = dox.parseComments(code, options)

then that might be a nice pattern. Maybe we can get inspiration from jsstyles/jss, which is where I saw that pattern. JSS has a bunch of plugins.

[tomek-he-him]

dox could be made pluggable and features could be added via plugin modules

Great idea! Perhaps even:

var comments = dox.parseComments(code, options)
  .use(doxMarkdownIt())
  .use(someOtherPluginForDox({unicorns: true}))
  ;

var otherComments = dox.parseComments(otherCode, options)
  .use(doxMarkdownIt())
  ;

[Twipped]

Changing the title of this, since it sounds like people are leaning more in that direction. At this point I'm pretty persuaded in favor of it. Now that 0.7 is out the door I'm tentatively planning to deprecate markdown in 0.8 and formally remove it in 1.0.

I don't think a plugin architecture is a good solution, it would just make the library more complicated when it's already more complex than it should be. I do think that more of dox can be refactored into overridable functions, which would accomplish the same goal.

[trusktr]

I do think that more of dox can be refactored into overridable functions, which would accomplish the same goal.

Sounds good to me!