Fix docstrings and comments (WIP)

Updates docstrings and comments interface and gpg.functions.
lukpueh · Oct 14, 2020 · 09d9d4b · 09d9d4b
1 parent 2e48c9f
commit 09d9d4b
Show file tree

Hide file tree

Showing 2 changed files with 230 additions and 458 deletions.
diff --git a/securesystemslib/gpg/functions.py b/securesystemslib/gpg/functions.py
@@ -232,41 +232,23 @@ def verify_signature(signature_object, pubkey_info, content):
 
 
 def export_pubkey(keyid, homedir=None):
-  """
-  <Purpose>
-    Calls gpg command line utility to export the gpg public key bundle
-    identified by the passed keyid from the gpg keyring at the passed homedir
-    in a securesystemslib-style format.
-
-    NOTE: The identified key is exported including the corresponding master
-    key and all subkeys.
-
-    The executed base export command is defined in
-    securesystemslib.gpg.constants.GPG_EXPORT_PUBKEY_COMMAND.
+  """Exports a public key from a GnuPG keyring.
 
-  <Arguments>
-    keyid:
-            The GPG keyid in format: securesystemslib.formats.KEYID_SCHEMA
-
-    homedir: (optional)
-            Path to the gpg keyring. If not passed the default keyring is used.
-
-  <Exceptions>
-    ValueError:
-            if the keyid does not match the required format.
-
-    securesystemslib.exceptions.UnsupportedLibraryError:
-            If the gpg command is not available, or
-            the cryptography library is not installed.
-
-    securesystemslib.gpg.execeptions.KeyNotFoundError:
-            if no key or subkey was found for that keyid.
+  Arguments:
+    keyid: An OpenPGP keyid in KEYID_SCHEMA format.
+    homedir (optional): A path to the GnuPG home directory. If not set the
+        default GnuPG home directory is used.
 
+  Raises:
+    ValueError: Keyid is not a string.
+    UnsupportedLibraryError: The gpg command or pyca/cryptography are not
+        available.
+    KeyNotFoundError: No key or subkey was found for that keyid.
 
-  <Side Effects>
-    None.
+  Side Effects:
+    Calls system gpg command in a subprocess.
 
-  <Returns>
+  Returns:
     The exported public key object in the format:
     securesystemslib.formats.GPG_PUBKEY_SCHEMA.
 
@@ -302,7 +284,7 @@ def export_pubkey(keyid, homedir=None):
 
 
 def export_pubkeys(keyids, homedir=None):
-  """Export multiple public keys from a GnuPG keyring.
+  """Exports multiple public keys from a GnuPG keyring.
 
   Arguments:
     keyids: A list of OpenPGP keyids in KEYID_SCHEMA format.
@@ -311,7 +293,13 @@ def export_pubkeys(keyids, homedir=None):
 
   Raises:
     TypeError: Keyids is not iterable.
-    See 'export_pubkey' for other exceptions.
+    ValueError: A Keyid is not a string.
+    UnsupportedLibraryError: The gpg command or pyca/cryptography are not
+        available.
+    KeyNotFoundError: No key or subkey was found for that keyid.
+
+  Side Effects:
+    Calls system gpg command in a subprocess.
 
   Returns:
     A dict with the OpenPGP keyids passed as the keyids argument for dict keys