tweak roles_match_with?() and improve documentation