added documentation to the public headers