Discussion: Use a different documentation module

[FezVrasta]

Right now we are using JSDoc but it doesn't seem to be maintained anymore.

jsdoc/jsdoc#1239

The current documentation isn't the nicest so if someone has some good name to suggest which could improve our documentation please share with us.

Alternatives

• jsdoc2md

[75lb]

have you considered jsdoc2md?

version 2 is in alpha..

[FezVrasta]

I tried it initially but I ditched it because I needed a way to customize the template and there wasn't a way with jsdoc2md

[75lb]

it's fully customisable, see the dmd docs (dmd is the handlebars template for the jsdoc2md output).. maybe it's not documented well enough..

[75lb]

let me know if there's any specific help you need.

[FezVrasta]

Thanks I missed it. I don't see any real advantage tho, under the hood we would still use jsdoc so there wouldn't be any real improvement.

[75lb]

what are the improvements you need? Just curious as i have both jsdoc2md v2 and a jsdoc replacement tool in development..

[FezVrasta]

Not sure if it's just me not able to use the tool properly, but I would like to make the documentation more readable, right now it's pretty limited, expecially the doc of the options, I'm limited to a short description displayed inside the table.

[75lb]

was that generated with jsdoc2md? If so, try the list param-list format.. i.e.

jsdoc2md --param-list-format list lib/my-app.js

It's a better format in cases like yours

[FezVrasta]

No it's generated with the custom template I written, I will try jsdoc2md again soon.

[75lb]

here is an example of --param-list-format list output.. the descriptions are given much more space, params are indented to indicate depth.

[FezVrasta]

I see, but it doesn't seem clearer than what I have now.. By the way I guess I could just tweak my template to dedicate a whole row for the description, in this way everything would look better.

[FezVrasta]

@75lb ok so, I have created the doc with jsdoc2md grunt and it works, the problem is that the links are wrapped by <code> tags and Jekyll doesn't render the inner URL properly.

I need a way to create the URLs as foobar. I can't find a way to edit the template with the grunt wrapper tho.

[75lb]

Hi, sorry for the delay - busy day.. I will write a tutorial for how to use jsdoc2md to create Jekyll sites and get back to you..

Also, a pre-release is now available for jsdocmd v2..

[75lb]

ok so, I have created the doc with jsdoc2md grunt and it works, the problem is that the links are wrapped by tags and Jekyll doesn't render the inner URL properly

can i see this for myself on a branch somewhere? Can i reproduce this myself, if so which branch do i checkout and what command should i run to generate docs?

[FezVrasta]

The branch is v1-dev, the task is doc, right now I'm performing a replace using the jekyll utils inside doc/documentation.html

[FezVrasta]

Closing since the current task seems to work quite good, even if it's a bit hacky. Feel free to give me insights on how to improve it.

[75lb]

hi @FezVrasta, sorry i didn't get back to you yet.. i've been working to complete jsdoc2md v2 - i thought i should tackle that first to get it out of the way.. will let you know once it's done and i've written a guide of how to use with Jekyll. Glad you're getting satisfactory results in the meantime.