Points well taken and agreed. MODx 1.0 is in development and will feature a new object-oriented API complete with proper API documentation including descriptions of variables, parameters, and return values. This will be generated automatically when we build a new release of MODx from 1.0 forward, so multiple versions of the documentation can be maintained in archives for back-reference, and the latest will always be available from the site. And since the API documentation will be generated from the code comments, all the information will also be available to programmers who prefer to check out the code.
I’ll try and get some of the current documentation updated for the 0.9.5 release in the interim, but can’t make any promises. If someone wants to volunteer for such a task, feel free to contact me via PM to discuss.