From 0747714f6ed0ab4c9252b3b2a0cfb89855b3b683 Mon Sep 17 00:00:00 2001
From: Ken Dreyer <kdreyer@redhat.com>
Date: Oct 12 2021 18:27:39 +0000
Subject: document convertFault method


Update the convertFault docstring to describe how the method converts
faults, the "fault" parameter type, and possible return values.

---

diff --git a/koji/__init__.py b/koji/__init__.py
index 4fe2209..83ab9bf 100644
--- a/koji/__init__.py
+++ b/koji/__init__.py
@@ -437,9 +437,18 @@ class MultiCallInProgress(object):
     pass
 
 
-# A function to get create an exception from a fault
 def convertFault(fault):
-    """Convert a fault to the corresponding Exception type, if possible"""
+    """Convert a fault to the corresponding Exception type, if possible.
+
+    This method compares this fault's faultCode to all the known faultCodes
+    in the GenericError and sub-classes defined above. If there is a matching
+    faultCode, return that new Exception class. If there is no match, just
+    return the fault object as-is.
+
+    :param xmlrpc.client.Fault fault: The XML-RPC fault from the hub.
+    :returns: one of the GenericError sub-classes, if possible.
+    :returns: fault instance, if no GenericError sub-classes matched.
+    """
     code = getattr(fault, 'faultCode', None)
     if code is None:
         return fault