JSDoc?

[fenwick67]

There are loads of methods in the README . If I were to rewrite these as JSDoc strings in the code, then set up an npm task for building documentation HTML, would that be useful work? It might make developing against this a bit easier (enabling intellisense etc).

[cblgh]

do you have any example of that?

i don't mind, but most of the work with the docs has already been done : ) and adding a new method only takes a few seconds (copy an existing method in the docs and write new words)

commenting them in the source code would be helpful though, and if writing JSDoc strings would help you when working against this lib then i think that would be useful work

sorry if this is a circumspect answer, i just want people to do what's useful for them & create cool stuff hehe

[fenwick67]

Here's a couple of examples:

jsPdf docs
phaser docs
Lodash has their own build system but it's built off of docstrings in a similar manner.

There's also jsdoc-to-markdown which could inject info from docstrings into the README.md instead of making html. That might be what I try first.

[cblgh]

@fenwick67 thanks for the examples! i was still on the fence until i came across ws's way of doing it

https://github.com/websockets/ws/blob/master/doc/ws.md

so the README stays handwritten, and refers to a docs.md, which is generated by the jsdoc strings. it feels like a reasonable balance :)

also what's getting me off the fence is that really nice ToC with links, that's super useful for an overview and getting to where you want to be fast. i think the docs.md approach would be what i want for this repo ^_^

[okdistribute]

might be nice to have this for lower level cabal core as well!

[cblgh]

this has been merged thanks to the excellent @fenwick67 #19! now we also have a great approach to use in cabal-core ^_^