Fixed incorrect Python API docs format.

The Python API docs in some classes/methods have been fixed to
remove the errors and warnings generated by python-sphinx.

https://fedorahosted.org/pki/ticket/1157

2 files changed, 55 insertions, 51 deletions

diff --git a/base/common/python/pki/encoder.py b/base/common/python/pki/encoder.py
index 09e8f5a9f..88a92f243 100644
--- a/base/common/python/pki/encoder.py
+++ b/base/common/python/pki/encoder.py
@@ -5,7 +5,8 @@ NOTYPES = {}
 
 
 class CustomTypeEncoder(json.JSONEncoder):
-    """A custom JSONEncoder class that knows how to encode core custom
+    """
+    A custom JSONEncoder class that knows how to encode core custom
     objects.
 
     Custom objects are encoded as JSON object literals (ie, dicts) with
@@ -13,21 +14,22 @@ class CustomTypeEncoder(json.JSONEncoder):
     type to which the object belongs.  That single key maps to another
     object literal which is just the __dict__ of the object encoded.
 
-    Reason for ignoring the error
-         E0202 - An attribute affected in json.encoder line 157 hide this method
-       reported by pylint:
-
-       The error is in json.encoder.JSONEncoder class.
-       There is a default method (which is overridden here) and also a class
-       attribute self.default initialized in the init method of the class.
-       The intention of such usage being that a custom default method object can
-       be passed to init when creating an instance of JSONEncoder, which is then
-       assigned to class's default method. (which is valid)
-       But pylint raises an issue due to the usage of same name for a method and
-       an attribute in which case the attribute definition hides the method.
-       The reason and example for the issue: (top rated comment)
-           http://stackoverflow.com/questions/12949064/python-what-happens-
-           when-instance-variable-name-is-same-as-method-name
+    Reason for ignoring the error:
+    E0202 - An attribute affected in json.encoder line 157 hide this method
+    reported by pylint:
+
+    The error is in json.encoder.JSONEncoder class.
+    There is a default method (which is overridden here) and also a class
+    attribute self.default initialized in the init method of the class.
+    The intention of such usage being that a custom default method object can
+    be passed to init when creating an instance of JSONEncoder, which is then
+    assigned to class's default method. (which is valid)
+    But pylint raises an issue due to the usage of same name for a method and
+    an attribute in which case the attribute definition hides the method.
+    The reason and example for the issue: (top rated comment)
+
+        http://stackoverflow.com/questions/12949064/python-what-happens-
+        when-instance-variable-name-is-same-as-method-name
     """
     # pylint: disable-msg=E0202
     def default(self, obj):
diff --git a/base/common/python/pki/key.py b/base/common/python/pki/key.py
index 0be438a28..1f449955b 100644
--- a/base/common/python/pki/key.py
+++ b/base/common/python/pki/key.py
@@ -708,26 +708,27 @@ class KeyClient(object):
                                encrypted_data, trans_wrapped_session_key,
                                algorithm_oid, symkey_params,
                                key_algorithm=None, key_size=None):
-        """ Archive a secret (symmetric key or passphrase) on the DRM.
-
-            Refer to archive_key() comments for a description of client_key_id,
-            data_type, key_algorithm and key_size.
-
-            The following parameters are also required:
-                - wrapped_private_data - which is the secret wrapped by a
-                session key (168 bit 3DES symmetric key)
-                - trans_wrapped_session_key - the above session key wrapped by
-                the DRM transport certificate public key.
-                - the algorithm_oid string for the symmetric key wrap
-                - the symkey_params for the symmetric key wrap
-
-            This function is useful if the caller wants to do their own wrapping
-            of the secret, or if the secret was generated on a separate client
-            machine and the wrapping was done there.
-
-            The function returns a KeyRequestResponse object containing a
-            KeyRequestInfo object with details about the archival request and
-            key archived.
+        """
+        Archive a secret (symmetric key or passphrase) on the DRM.
+
+        Refer to archive_key() comments for a description of client_key_id,
+        data_type, key_algorithm and key_size.
+
+        The following parameters are also required:
+            - wrapped_private_data - which is the secret wrapped by a
+              session key (168 bit 3DES symmetric key)
+            - trans_wrapped_session_key - the above session key wrapped by
+              the DRM transport certificate public key.
+            - the algorithm_oid string for the symmetric key wrap
+            - the symkey_params for the symmetric key wrap
+
+        This function is useful if the caller wants to do their own wrapping
+        of the secret, or if the secret was generated on a separate client
+        machine and the wrapping was done there.
+
+        The function returns a KeyRequestResponse object containing a
+        KeyRequestInfo object with details about the archival request and
+        key archived.
         """
         if (client_key_id is None) or (data_type is None):
             raise TypeError("Client Key ID and data type must be specified")
@@ -908,7 +909,8 @@ class KeyClient(object):
                                    trans_wrapped_session_key=None,
                                    session_wrapped_passphrase=None,
                                    nonce_data=None):
-        """ Retrieve a secret (passphrase or symmetric key) from the DRM using
+        """
+        Retrieve a secret (passphrase or symmetric key) from the DRM using
         a passphrase.
 
         This function generates a key recovery request, approves it, and
@@ -922,28 +924,28 @@ class KeyClient(object):
 
         1) A passphrase is provided by the caller.
 
-        In this case, CryptoProvider methods will be called to create the data
-        to securely send the passphrase to the DRM.  Basically, three pieces of
-        data will be sent:
+           In this case, CryptoProvider methods will be called to create the data
+           to securely send the passphrase to the DRM.  Basically, three pieces of
+           data will be sent:
 
-        - the passphrase wrapped by a 168 bit 3DES symmetric key (the session
-        key).  This is referred to as the parameter session_wrapped_passphrase.
+           - the passphrase wrapped by a 168 bit 3DES symmetric key (the session
+             key).  This is referred to as the parameter session_wrapped_passphrase.
 
-        - the session key wrapped with the public key in the DRM transport
-        certificate.  This is referred to as the trans_wrapped_session_key.
+           - the session key wrapped with the public key in the DRM transport
+             certificate.  This is referred to as the trans_wrapped_session_key.
 
-        - ivps nonce data, referred to as nonce_data
+           - ivps nonce data, referred to as nonce_data
 
-        The function will return the tuple (KeyData, unwrapped_secret)
+           The function will return the tuple (KeyData, unwrapped_secret)
 
         2) The caller provides the trans_wrapped_session_key,
-        session_wrapped_passphrase and nonce_data.
+           session_wrapped_passphrase and nonce_data.
 
-        In this case, the data will simply be passed to the DRM.  The function
-        will return the secret encrypted by the passphrase using PBE Encryption.
-        The secret will still need to be decrypted by the caller.
+           In this case, the data will simply be passed to the DRM.  The function
+           will return the secret encrypted by the passphrase using PBE Encryption.
+           The secret will still need to be decrypted by the caller.
 
-        The function will return the tuple (KeyData, None)
+           The function will return the tuple (KeyData, None)
         """
         pass