Why the stream interface?

[vvo]

Hi, nice project! We use it internally at Algolia.

I was wondering, it seems like jsdoc2md() return a stream but this stream actually only send one data event. So I was wondering what was the reasoning behind making this a stream interface while it's only having a single data event?

As we use it in a programmatic way and output one file per function we document, we had to use a weird construct where we write to a file and then require the file. I am currently doing another hack like storing the "chunks" of data (there's only one) and then doing JSON.parse on top of it.

Why not have a simple callback interface receiving the JSON object and maybe expose a stream one for other use cases?

Thanks for your insights

[75lb]

version 2.0.0 (dev to start soon) will have multiple interfaces, not only stream..

a synchronous interface will be added for users of node >=0.12 (thanks to child_process.spawnSync).. There'll be an async method too which node 0.10 users can use.

the stream interface was initially implemented as the jsdoc2md output was typically piped to either file or stdout.. there are many modules to collect stream data, concat-stream is a classic example.. i have my own lib for collecting json..

but this stream actually only send one data event

it depends on the size of the jsdoc2md() output and the OS.. large output on Win98 (for example) would definitely be received in multiple chunks.

we write to a file and then require the file... storing the "chunks" of data (there's only one) and then doing JSON.parse...

wow.. are you talking about the raw jsdoc-parse, json data here? could you send code examples of these hacks? It would be useful for me, to improve the API.

[vvo]

Thanks a lot for your openness about my question on the stream interface.

You can see how we use you here: https://github.com/algolia/instantsearch.js/blob/master/scripts/doc/gen-widget-doc.js a lil bit hacky :) (cc @bobylito who did the original script and used the module first).

[75lb]

i agree, we need sync and async interfaces too - not only stream.. I'm leaving this issue open until it is addressed.. for async use, a Promises interface might be better, for example

jsdoc2md({ src: 'lib.js', json: true })
  .then(extractClassNames)
  .then(writeOneFilePerClass)

meanwhile, i tidied the example script (on which @bobylito 's script is based) here.. you can see i replaced the use of the intermediary file with collectJson.

Merci pour votre participation :+1: :fr:

[75lb]

to give a taste of the direction the modules are going, i created a new module jsdoc-api which gives direct, programmatic access to the raw jsdoc output.. it has sync, async and streaming interfaces.. the next versions of jsdoc-parse, dmd, jsdoc2md etc. will have the same options.

[bobylito]

:+1: Nice @75lb :)

[vvo]

Awesome, I am currently using your modified script version with collectJson

[75lb]

Closing now as the streaming interface has been replaced by sync and async interfaces in jsdoc2md v2.