[slededit]

Doxygen should never be your sole source of documentation although a lot of projects use it that way. It does not communicate the design philosophy behind the code, so while it will answer whether you can use an API a certain way it doesn't answer if it was the intended use. This becomes important because once you step outside the programmers intent things are less likely to work and will be more brittle.

If you are a public library it also results in the infuriating situation of knowing an API will do what you want but not knowing how to get a parameter or class it requires.