[julianlam]

I personally find auto-generated documentation based off of code is just awful, unless all you're looking for is the function signature and/or type. Every time I see auto-generated docs, I back out immediately.

The problem I see here is that writing docs when writing code is a different kind of mental activity, and requires some amount of context switching which developers by-and-large are loathe to do.

At least for NodeBB's API[1], we wanted documentation that kept up with changes, so we put in the hours to get a handwritten OpenAPI v3 spec written, and added a rigorous test suite[2] that not only checked syntax, but ensured that all routes defined actually returned a response with the expected schema.

We extended this later on to do the reverse; to check the mounted routes and ensure it is defined in the spec.

It's a pain in the butt when your feature gets pushed and immediately fails API tests, but the tradeoff of having guaranteed up-to-date docs is well worth it.

[1] https://docs.nodebb.org/api/ [2] https://github.com/NodeBB/NodeBB/blob/master/test/api.js