improved documentation of public methods