If you think that the API references for hildon-widgets are unclear or miss something important, please do file a bug report against "Desktop platform > hildon-widgets" with the "docs" keyword set, Version set to "5.0-beta", and the exact URL of the existing API reference set in the URL field in http://bugs.maemo.org .
If there are issues, let's make it easier for every developer by providing better documentation. And the libhildon/hildon-desktop/hildon-widgets hackers have been quite responsive so far IMO.