I posted an update on one of the development projects going on to the asterisk-dev mailing list. We are restructuring the way documentation is managed for the interfaces inside of Asterisk and the first phase of the project will likely be merged soon. Check out the update here.
From the update:
===== Project Background =====
Writing documentation is a huge job. Every time that someone has gone to write documentation on Asterisk, part of the task is always to take the information from “core show application <foo>” or “core show function <bar>” and convert it to some other format. This documentation has been maintained in the source code in a raw string format, and there has been no programmatic way to extract it from the source. This project aimed to improve that situation.
Russell Bryant 
A suggestion – I’m working on a similar project for an api provided by our product to our partners. I found that XML imposed such a high readability barrier that actually writing documentation was problematic. We’ve switched to YAML instead, and it’s turned out to be much more effective. (And simple, since we can even embed XML fragments in the documentation without any special escaping.)