Add API documentation - Githubissues

chadxz / awry

An Asterisk REST Interface (ARI) websocket and API client library

MIT License

21 stars 9 forks source link

Add API documentation #6

Closed chadxz closed 6 years ago

chadxz commented 8 years ago

Most everything is documented thoroughly with JSDoc, but this documentation needs to be more visible. Probably need to generate it using a tool.

chadxz commented 8 years ago

documentationjs: ran into an error related to nested properties in a namespace declaration https://github.com/documentationjs/documentation/issues/559
esdoc: doesn't support node.js require() https://github.com/esdoc/esdoc/issues/258

chadxz commented 8 years ago

the jsdoc3/jsdoc project's cli does the best job so far of the three I've tried. Moving forward with that project seems like the best bet, although the default template leaves a lot to be desired. I really like the documentationjs default template the best, but I had misc issues getting it to generate the correct docs for es6 classes and regular node modules.

chadxz commented 8 years ago

the documentationjs issue referenced above has been fixed. Might be worth looking back at that project to see if it would work.

chadxz commented 6 years ago

Took a look at the jsdoc generated documentation landscape again this weekend. documentationjs does the best job "out of the box" at generating documentation, but the default template is not great.

esdoc requires the esdoc-node plugin to parse node.js style module.exports syntax. An alternative to this module would be to use @std/esm https://github.com/standard-things/esm which introduces the es modules syntax to node.js https://github.com/nodejs/node-eps/blob/master/002-es-modules.md with compatibility back to Node 4. However, even with only using esdoc-node plugin, it had trouble parsing the entire project. I say all this because I think the default template for esdoc is nicer than that of documentationjs. I really like the linked source in each section.

chadxz commented 6 years ago

I got a start on this with the es-modules branch here. It's looking really promising. I need to figure out the way it's showing directories instead of the actual public api, and a deployment strategy for hosting the docs (probably on project.github.io on a gh-pages branch.

chadxz commented 6 years ago

The directory showing on the docs is part of the default template. To get those to go away is have to build a custom template which I'm not excited about.

esdoc has hosting one I merge the es-modules branch to master.

I want to try out the changes in an app before I merge to master. Will try it out on call-control