add documentation to match-pairs functionality