add .remove() docs, api and tests