update docs and corner cases