Fixed #4377 -- document certificate policies with an example (#5058)

1 files changed, 12 insertions, 0 deletions

diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst
index 6eca950b..7f75f69d 100644
--- a/docs/x509/reference.rst
+++ b/docs/x509/reference.rst
@@ -2483,6 +2483,18 @@ X.509 Extensions
 
     :param list policies: A list of :class:`PolicyInformation` instances.
 
+    As an example of how ``CertificatePolicies`` might be used, if you wanted
+    to check if a certificated contained the CAB Forum's "domain-validated"
+    policy, you might write code like:
+
+    .. code-block:: python
+
+        def contains_domain_validated(policies):
+            return any(
+                policy.oid.dotted_string == "2.23.140.1.2.1"
+                for policy in policies
+            )
+
     .. attribute:: oid
 
         .. versionadded:: 1.0