need to find a new doc generator
ericblade opened this issue · 4 comments
esdoc had decent looking output, but is very opinionated -- it required a 3rd party plugin to work with require(), which is kind of ridiculous, and it treated everything as if it was an ES module. After the recent structural changes to this library, it no longer fits our needs at all -- and I had to make code changes to even get the files to parse. esdoc does not receive updates in a timely fashion. Therefore, I conclude, that either we maintain our own esdoc-plugin to deal with things, or we find a better generator.
Seems there are a pretty fair number of them out there. jsdoc has reasonably styled output, but doesn't seem to understand very well that the primary interface to this library is through the MwsAdvanced class. I'm not sure if there's a possible way to get it to give me the MwsAdvanced docs in one set, and the rest of the docs (internal stuff) as a second set -- then we could have "public" and "internal/private" docs, one set for users, one set for people who want to hack on the lib.
There might be other generators out there that might more naturally understand this.
It looks like I can use documentation.js to perform the second idea above.
I'll be checking into that over the next several days, and see if I can put something together that has a "public" and an "internal" documentation setup. I suspect there's going to be one JS file, or a directory, that documents all of the data types we can return, and one for all the datatypes that MWS can return. The public documentation will need the first, and the private documentation will want both.
... I am coming to the conclusion that every one of the documentation generators out there are not really useful. Including the one produced by jsdoc. :-S
It seems that "documentation" used to output Markdown, followed by "mkdocs" can produce quite a nice little output, See https://sharp.dimens.io/en/stable/
I've done a little bit of work towards this, and it looks quite nicer than the existing one.