Improving docstrings for policy API
Improving docstrings for policy API

The docstring for the policy API has some wrong examples and is
lacking examples of other types of checkings already available to
be used on policy languages. This patch corrects it.

Change-Id: I8d8ed04b10a28ca2ade5aaf95bc080c39472ae32

rodrigods/oslo.policy,openstack/oslo.policy,citrix-openstack-build/oslo.policy