added requsted features, along with docs and unit tests