One reason for source code comments (actually the biggest reason for my personal projects!) which I haven't seen mentioned much here is that if you are a productive programmer with lots of projects, you simply forget yourself why you wrote some code 12 months ago in one of hundreds of files you've written...
I always write exhaustive comments in my own projects, even if it means mentioning things that seemed trivial at the moment, because I *know* that I will waste time later figuring out if the internal parameter X was supposed to be positive or negative or if there are exceptions or limitations to some small algorithm used.
There is a lot of talk here about documenting the API, but for a skilled programmer starting to use Bullet, one very important thing is to get a feeling for the code itself and quickly get an intuitive feeling for where the designer knew what he was doing and where code is just a hack. The engine is not complete by any means, because the field is expanding all the time, so most of the time the user has to go into the code at some point anyway.
In Bullet, there is hardly any code analysis comments at all, and even the formatting of the code is off the map - I don't know what editor Erwin uses, but when I load it into emacs, I get horrible indentations and stuff like this: "void myfunction(int a, )" etc... anyway don't take that as criticism, just an observation - the Bullet library overall is incredibly cool to have as open-source! But it could easily be a LOT more programmer-friendly. It's not millions of lines of code - just taking 3-4 days just brain dumping all you know and come to think about while scanning through some of the most used .cpp files and adding comments could save several man-years in total programmer time afterwards!
So to summarize, the API-parts, doxygen generated documentation etc is good to fix but not the biggest issue I think. A physics engine is (currently) an incredibly complicated piece of algorithmic machinery, and I would not expect the parts to be perfect, so prioritizing actually helping programmers understand the code itself would help a lot in the long run, because it would generate more code-submissions in return, hopefully