This actually bothered me to no end at google. At the API level, it's great, I can learn a lot about what your function is going to do just by looking at the signature, but when reading code that uses an API I don't know, it's hell. For me, the extra help you get by looking at a function signature really isn't that great, when I should have the same information available in the documentation that had damn well better accompany the function signature in your header.