update docs
add test for map convenience methods