http://apiblueprint.org is great. It's not using annotations in the code, but it's documented separately in markdown. What I've done in projects is just put markdown files next to the javascript files that contain API controllers, and then I just concatenate them together in a Grunt task before sending it through API Blueprint tools. I'm not sure it's really a home run to couple API documentation in with the code documentation -- the audiences are really different, and your code & it's comments should be catering towards developers of the API. But being able to put markdown files directly parallel to code I think maintains the same spirit of annotations being close to the code.
That said -- API Blueprint is great because its an open specification with a bunch of great tools built around it. There's tools to generate html documentation, parsers to write your own tools, and tools to verify your documentation against a live instance. That last one was the killer feature for me, as its a great integration point for a CI environment to make sure that developers on the team keep docs up to date.
awinder 3925 days ago. link 1 point ▲ ▼