Accept json generated by docchi

Question

Accept json generated by docchi

mhelvens opened this issue 9 years ago · comments

Michiel Helvensteijn commented 9 years ago

I love the way dmd generates Markdown documentation, but jsdoc2md uses JSDoc to parse the code and comments, and JSDoc has very poor ES6 support.

I ran across docchi recently, and I wonder whether it is compatible with dmd, and what would be required to make them work together.

Lloyd Brookes · Answer 1 · Mon May 04 2015 18:09:36 GMT+0800 (China Standard Time)

dmd is intentionally separated to support input from any parser supplying the required data format.. however, i haven't written the spec for this format yet! It's on the todo list..

we need to write an adapter (a Transform stream to sit between docchi and dmd).. the adapter will take docchi input and output data resembling the current jsdoc-parse format..

Michiel Helvensteijn · Answer 2 · Mon May 04 2015 18:12:58 GMT+0800 (China Standard Time)

Is it possible docchi already generates compatible output? The first sentence in their README.md states: "Docchi [...] outputs the structure and context of the comments in any particular format, JSDoc is the default."

Lloyd Brookes · Answer 3 · Mon May 04 2015 18:20:23 GMT+0800 (China Standard Time)

the default output is not compatible, but i can see a resemblance to jsdoc output.. we could write an adapter for this.. i'll have a play with that soon, to get the ball rolling.. but more importantly, i should write that data spec.. do you have a documented ES6 project i could test docchi against, to see some varied output?

Michiel Helvensteijn · Answer 4 · Mon May 04 2015 18:23:43 GMT+0800 (China Standard Time)

Try graph.js. However, note that I annotated it with the quirks of JSDoc in mind. For example, I'm annotating the class and its constructor in the same comment block, explicitly stating its name and the fact that it is a class, etc.

Lloyd Brookes · Answer 5 · Mon May 04 2015 18:48:55 GMT+0800 (China Standard Time)

nice project and docs.. will have a look.. are there other doc parsers suitable for ES6 we should also consider?

Michiel Helvensteijn · Answer 6 · Mon May 04 2015 18:52:05 GMT+0800 (China Standard Time)

I've been looking for an 'ES6 JSDoc' for a couple of months now, on and off, and docchi is the first I've come across that seems promising.

Lloyd Brookes · Answer 7 · Fri Jan 08 2016 18:41:12 GMT+0800 (China Standard Time)

are you still using docchi? what was your solution? jsdoc (and jsdoc2md) have pretty comprehensive ES6 support these days..

Michiel Helvensteijn · Answer 8 · Sat Jan 09 2016 02:09:41 GMT+0800 (China Standard Time)

I actually never used Docchi. I just coped with JSDoc's ES6 support.

I do feel like JSDoc will always be behind. If only it could keep up with the likes of Babel, at least with regard to what it can swallow without complaining. For example, I'm already using async, await and :: from ES2016. (I'm not sure if Docchi supports them either, though.)