Consider using JSDoc for inline documentation

[KevinGrandon]

Currently we have really documentation inside of the README, but this is disconnected from the actual code. One thing we could do is to move the comments into the controllers, and populate the readme content using JSDoc. There would likely need to be a build step to generate the doc, but this could be a pre-commit hook, or part of the gulp command.

The benefits would be that the comments would be there with the source code, and the current README would stay the same.

@mrose17 - Thoughts?

[mrose17]

i am told that https://github.com/hapijs/lout is the "official" documentation generator for hapi servers. i don't have a problem with JSDoc, but everytime i've needed to add something to the vault, my first step has been to see if there is an "official" hapi module, and if so use that.

i think the best approach is to do a trial with one .js file using lout and see how it works... if we don't like it, then do the same trial with JSDoc... does that make sense?

[KevinGrandon]

Let's try lout then, and see how far we get, though it does seem a bit harder to read than some of the JSDoc generators I've seen. Also not sure about the best way of adding a description to these routes?

[KevinGrandon]

Also found this: https://github.com/glennjones/hapi-swagger

It's not the official plugin, but it works with Hapi and has clear ways about how to document description and notes. It could be an option as well.

[KevinGrandon]

Fixed via https://github.com/brave/vault/commit/54a662723b856da136e6f86ae91ac990b531a667