search

ericblade / mws-advanced

Javascript (node) Amazon Merchant Web Services (MWS) code with mws-simple as it's underpinnings
Apache License 2.0
41 stars 11 forks source link

need to find a new doc generator #108

Open ericblade opened 5 years ago

ericblade commented 5 years ago

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.

ericblade commented 5 years ago

https://areknawo.com/lets-talk-js-documentation/

ericblade commented 5 years ago

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.

ericblade commented 5 years ago

... 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

ericblade commented 5 years ago

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.