Merge pull request #1843 from ivanayov/metadata_docstrings_imprv_follow_up

Improve docstrings in Metadata API to be more descriptive

Author: Lukas Pühringer

tuf/api/metadata.py

@@ -141,7 +141,7 @@ def __eq__(self, other: Any) -> bool:
 
     @classmethod
     def from_dict(cls, metadata: Dict[str, Any]) -> "Metadata[T]":
-        """Creates ``Metadata`` object from its dict representation.
+        """Creates ``Metadata`` object from its json/dict representation.
 
         Args:
             metadata: TUF metadata in dict representation.
@@ -335,7 +335,9 @@ def sign(
         """Creates signature over ``signed`` and assigns it to ``signatures``.
 
         Args:
-            signer: A securesystemslib.signer.Signer implementation.
+            signer: A ``securesystemslib.signer.Signer`` object that provides a private
+                key and signing implementation to generate the signature. A standard
+                implementation is available in ``securesystemslib.signer.SSlibSigner``.
             append: ``True`` if the signature should be appended to
                 the list of signatures or replace any existing signatures. The
                 default behavior is to replace signatures.
@@ -522,7 +524,7 @@ def to_dict(self) -> Dict[str, Any]:
     @classmethod
     @abc.abstractmethod
     def from_dict(cls, signed_dict: Dict[str, Any]) -> "Signed":
-        """Deserialization helper, creates object from dict representation"""
+        """Deserialization helper, creates object from json/dict representation"""
         raise NotImplementedError
 
     @classmethod
@@ -636,7 +638,7 @@ def __eq__(self, other: Any) -> bool:
 
     @classmethod
     def from_dict(cls, keyid: str, key_dict: Dict[str, Any]) -> "Key":
-        """Creates ``Key`` object from its dict representation.
+        """Creates ``Key`` object from its json/dict representation.
 
         Raises:
             KeyError, TypeError: Invalid arguments.
@@ -667,7 +669,7 @@ def to_securesystemslib_key(self) -> Dict[str, Any]:
 
     @classmethod
     def from_securesystemslib_key(cls, key_dict: Dict[str, Any]) -> "Key":
-        """Creates a ``Key`` object from a securesystemlib key dict representation
+        """Creates a ``Key`` object from a securesystemlib key json/dict representation
         removing the private key from keyval.
 
         Args:
@@ -790,7 +792,7 @@ def __eq__(self, other: Any) -> bool:
 
     @classmethod
     def from_dict(cls, role_dict: Dict[str, Any]) -> "Role":
-        """Creates ``Role`` object from its dict representation.
+        """Creates ``Role`` object from its json/dict representation.
 
         Raises:
             ValueError, KeyError: Invalid arguments.
@@ -863,7 +865,7 @@ def __eq__(self, other: Any) -> bool:
 
     @classmethod
     def from_dict(cls, signed_dict: Dict[str, Any]) -> "Root":
-        """Creates ``Root`` object from its dict representation.
+        """Creates ``Root`` object from its json/dict representation.
 
         Raises:
             ValueError, KeyError, TypeError: Invalid arguments.
@@ -1056,7 +1058,7 @@ def __eq__(self, other: Any) -> bool:
 
     @classmethod
     def from_dict(cls, meta_dict: Dict[str, Any]) -> "MetaFile":
-        """Creates ``MetaFile`` object from its dict representation.
+        """Creates ``MetaFile`` object from its json/dict representation.
 
         Raises:
             ValueError, KeyError: Invalid arguments.
@@ -1144,7 +1146,7 @@ def __eq__(self, other: Any) -> bool:
 
     @classmethod
     def from_dict(cls, signed_dict: Dict[str, Any]) -> "Timestamp":
-        """Creates ``Timestamp`` object from its dict representation.
+        """Creates ``Timestamp`` object from its json/dict representation.
 
         Raises:
             ValueError, KeyError: Invalid arguments.
@@ -1203,7 +1205,7 @@ def __eq__(self, other: Any) -> bool:
 
     @classmethod
     def from_dict(cls, signed_dict: Dict[str, Any]) -> "Snapshot":
-        """Creates ``Snapshot`` object from its dict representation.
+        """Creates ``Snapshot`` object from its json/dict representation.
 
         Raises:
             ValueError, KeyError: Invalid arguments.
@@ -1299,7 +1301,7 @@ def __eq__(self, other: Any) -> bool:
 
     @classmethod
     def from_dict(cls, role_dict: Dict[str, Any]) -> "DelegatedRole":
-        """Creates ``DelegatedRole`` object from its dict representation.
+        """Creates ``DelegatedRole`` object from its json/dict representation.
 
         Raises:
             ValueError, KeyError: Invalid arguments.
@@ -1439,7 +1441,7 @@ def __eq__(self, other: Any) -> bool:
 
     @classmethod
     def from_dict(cls, delegations_dict: Dict[str, Any]) -> "Delegations":
-        """Creates ``Delegations`` object from its dict representation.
+        """Creates ``Delegations`` object from its json/dict representation.
 
         Raises:
             ValueError, KeyError, TypeError: Invalid arguments.
@@ -1522,7 +1524,7 @@ def __eq__(self, other: Any) -> bool:
 
     @classmethod
     def from_dict(cls, target_dict: Dict[str, Any], path: str) -> "TargetFile":
-        """Creates ``TargetFile`` object from its dict representation.
+        """Creates ``TargetFile`` object from its json/dict representation.
 
         Raises:
             ValueError, KeyError, TypeError: Invalid arguments.
@@ -1679,7 +1681,7 @@ def __eq__(self, other: Any) -> bool:
 
     @classmethod
     def from_dict(cls, signed_dict: Dict[str, Any]) -> "Targets":
-        """Creates ``Targets`` object from its dict representation.
+        """Creates ``Targets`` object from its json/dict representation.
 
         Raises:
             ValueError, KeyError, TypeError: Invalid arguments.