One simple problem that I usually encounter when writing C++ code with drake is after finding the proper function to use from the official documentation, the official documentation does not tell me which header file to include and I have to dig into the source code to find the declaration. For example, I find function AddContactMaterical from the doc but the doc does not tell which header to include. I have to dig into the source code and finally find that it is declared in drake/geometry/proximity_properties.h. Do I miss something in the doc? Thank you very much!
This is a very real problem. When looking for a class (say ProximityProperties), the "Detailed Description" section includes #include <drake/geometry/geometry_roles.h>. However, the same doesn't apply for stand-alone functions, aliases, etc. For example, the page that has the documentation for AddContactMaterial doesn't include any information for include files. That's definitely a usability issue.
I've submitted an issue for this.