This is what we’ve done with Mapbox.js and Leaflet does it in HTML. Heck, node takes this approach. But I’ve felt the burn of the “just do it manually” approach:
table element, but it means some HTML structure more complex than an ordered list.This is popular in other languages, like Go and Python: you write some ‘magic comments’ in your code and a tool analyses your code to extract them as data and turn them into readable formats. A neat bonus is that fancy coding environments can read these docs too and give inline help: the most famous example is Intellisense, which ranks just below Word For Mac 98 as Microsoft’s best work.
The literate programming approach is of historical and linguistic interest: instead of documenting the outside interface of a program, you try to make all of the guts understandable, documenting individual loops and variables in crazy detail. I’ve tinkered with this, building literate-raytracer, simple-statistics, and literate-game-of-life in this style. It’s a fantastic exercise in questioning your confidence: is this really good code, and do I really understand what I’m writing at a deep level? But it’s the highest work level of any documentation style, and it fails dramatically at being skimmable: I’ve never seen literate programming as an effective API doc.