fixes bug 858244 - documentation for public api, r=rhelmer