Update usage documentation1.22.0

We recently merged a patch that enhanced the RuleDefault object by
allowing it to have more attributes:

  Ie9b335420394166bb39c43e3d26fcc9237ffd1a0

This commit describes its usage in the usage documentation.

Change-Id: I8f6e6bc289a046b09529f707874314c69757ee11

1 files changed, 26 insertions, 0 deletions

diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 2ba217f..93d8ad1 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -52,6 +52,11 @@ benefits.
   policies used are registered. The signature of Enforcer.authorize matches
   Enforcer.enforce.
 
+* Projects can register policies as `DocumentedRuleDefault` objects, which
+  require a method and path of the corresponding policy. This helps policy
+  readers understand which path maps to a particular policy ultimately
+  providing better documentation.
+
 * A sample policy file can be generated based on the registered policies
   rather than needing to manually maintain one.
 
@@ -83,6 +88,27 @@ How to register
                                                  'rule:admin_required',
                                                  description='helpful text'))
 
+To provide more information about the policy, use the `DocumentedRuleDefault`
+class::
+
+    enforcer.register_default(
+        policy.DocumentedRuleDefault(
+            'identity:create_region',
+            'rule:admin_required',
+            'helpful text',
+            [{'path': '/regions/{region_id}', 'method': 'POST'}]
+        )
+    )
+
+The `DocumentedRuleDefault` class inherits from the `RuleDefault`
+implementation, but it must be supplied with the `description` attribute in
+order to be used. In addition, the `DocumentedRuleDefault` class requires a new
+`operations` attributes that is a list of dictionaries. Each dictionary must
+have a `path` and a `method` key. The `path` should map to the path used to
+interact with the resource the policy protects. The `method` should be the HTTP
+verb corresponding to the `path`. The list of `operations` can be supplied with
+multiple dictionaries if the policy is used to protect multiple paths.
+
 Sample file generation
 ----------------------