joyent/node — pull request #6995 by thomseddon (2014-01-29 18:54:13+00:00)
Title: Revamp docs with JSDocs (incomplete)

Following on from the brief discussion in #6980 I've build a proof of concept of migrating the core documentation to jsdoc.

You will need to run `npm install` in tools/jsdoc to get the jsdoc library, you can then run `make doc` as usual. I've only added the inline comments to lib/path.js so far and various other pages are broken (all.html) etc. but an example of the output can be seen here: http://node.thomseddon.co.uk/api/path.html

I think there would be incredible value in more tightly coupling the api docs and the actual api code, it is quite common to have cases where the api is updated and the docs get left behind.

Additionally, one angle I really like the idea of is creating a generic node documentation tool (essentially jsdoc + template + simple to use) that others could use to documentation (similar to python's sphinx or java's javadoc). This could help give a very uniform feel to 3rd party library documentation (good and bad).

Again, this is only a proof of concept, if you like the idea then I'm ready to document the entire api + improve the generator.

Also, happy to move this onto the mailing list if that is preferred :)