docs for pairs and minor suggestions