adding comments / public API description
fixing tests