rejigger variable name and docs on policy.allows

This is to try to address some of the ambiguity about
what gets passed to allows. There is no functional change
to the code, just tidy ups.