Find tools for documentation

[jonahkagan]

First, there's the issue of documenting the code.

A brief survey of existing documentation generating libraries yielded almost nothing worthwhile. The leaders seem to be Dox (which uses JSDoc syntax that I find pretty unappealing) and Docco (which doesn't have any syntax and as far as I can tell simply puts your comments next to your code in HTML...).

I'm almost tempted to just write my own...

Then there's the issue of documenting the APIs.

There's Swagger, which seems a bit intrusive, since it actual gets all up in your code. But it does seem to also be able to generate docs from JSON schema specs. We should look into it. There's also I/O Docs. Their example page is pretty ugly though, so I dunno if I wanna go there.

I wonder if we should just write a quick little program that parses a JSON schema and renders it in a Markdown or HTML template. I like the idea of having schemas so that we can test against them as well.

[sumnerwarren]

Swagger will definitely do what we want, but I'd say it's more than intrusive, at least if we use their node package. I would be fine with writing our own quick and easy one though.

[jonahkagan]

I played around with writing my own a bit. I don't think it will be too hard once we want to start working on it, but it's probably not first priority. Although having schemas might also be good for testing.