I think we're going in the right direction as we are now, for the simple reason we all seem to forget - it *works*. Can it be better? No doubt about it, and better and up-to-date Zend API documentation would have helped. Perhaps when we change the license of the engine a flock of people will start documenting every bit. We'll just have to wait and see.
What license is the engine being changed to?
I've often wanted to work on documenting the PHP/Zend extension API, but the major stumbling block is the same major hassle I face as an occasional extension author: between php-4.0.4 and 4.0.6, I've had to alter my extensions 3 times to accomodate for (API only) changes which broke build. It's hard to document something which changes (even if only slightly) between minor version changes.
George