From ff7d0661a71ff2c9a66c8c9a1a48837d041f9099 Mon Sep 17 00:00:00 2001
From: Fraser Tweedale <ftweedal@redhat.com>
Date: Jun 07 2020 07:38:27 +0000
Subject: certmonger: move 'criteria' description to module docstring


The 'criteria' parameter is used by several subroutines in the
ipalib.install.certmonger module.  It has incomplete documentation
spread across several of these subroutines.  Move the documentation
to the module docstring and reference it where appropriate.

Part of: https://pagure.io/freeipa/issue/8186

Reviewed-By: Rob Crittenden <rcritten@redhat.com>
Reviewed-By: Rob Crittenden <rcritten@redhat.com>

---

diff --git a/ipalib/install/certmonger.py b/ipalib/install/certmonger.py
index 10b23c0..bda5672 100644
--- a/ipalib/install/certmonger.py
+++ b/ipalib/install/certmonger.py
@@ -47,6 +47,29 @@ DBUS_CM_CA_IF = 'org.fedorahosted.certmonger.ca'
 DBUS_PROPERTY_IF = 'org.freedesktop.DBus.Properties'
 
 
+"""
+Certmonger helper routines.
+
+Search criteria
+---------------
+
+Functions that look up requests take a ``dict`` of search criteria.
+In general, the key is a name of a property in the request property
+interface.  But there are some special cases with different
+behaviour:
+
+``nickname``
+  a.k.a. "request ID".  If given, only the specified request is
+  retrieved (if it exists), and it is still tested against other
+  criteria.
+
+``ca-name``
+  Test equality against the nickname of the CA (a.k.a. request
+  helper) object for the request.
+
+"""
+
+
 class _cm_dbus_object:
     """
     Auxiliary class for convenient DBus object handling.
@@ -159,6 +182,9 @@ class _certmonger(_cm_dbus_object):
 def _get_requests(criteria):
     """
     Get all requests that matches the provided criteria.
+
+    :param criteria: dict of criteria; see module doc for details
+
     """
     if not isinstance(criteria, dict):
         raise TypeError('"criteria" must be dict.')
@@ -197,11 +223,11 @@ def _get_requests(criteria):
 
 def _get_request(criteria):
     """
-    Find request that matches criteria.
-    If 'nickname' is specified other criteria are ignored because 'nickname'
-    uniquely identify single request.
-    When multiple or none request matches specified criteria RuntimeError is
-    raised.
+    Find request that matches criteria.  Return ``None`` if no match.
+    Raise ``RuntimeError`` if there is more than one matching request.
+
+    :param criteria: dict of criteria; see module doc for details
+
     """
     requests = _get_requests(criteria)
     if len(requests) == 0:
@@ -239,11 +265,11 @@ def get_request_id(criteria):
     If you don't know the certmonger request_id then try to find it by looking
     through all the requests.
 
-    criteria is a tuple of key/value to search for. The more specific
-    the better. An error is raised if multiple request_ids are returned for
-    the same criteria.
+    Return ``None`` if no match.  Raise ``RuntimeError`` if there is
+    more than one matching request.
+
+    :param criteria: dict of criteria; see module doc for details
 
-    None is returned if none of the criteria match.
     """
     try:
         request = _get_request(criteria)