BUG/TST/DOC: bug fix, added docs and tests