From 2726860192b6c836e1376f9745c41816680a18bd Mon Sep 17 00:00:00 2001
From: Ivana Atanasova <iyovcheva@vmware.com>
Date: Tue, 8 Feb 2022 18:35:16 +0200
Subject: [PATCH] Improve docstrings in Metadata API to be more descritpive

This change updates some parts of the Metadata API docstrings
that did not give enough details and context

Fixes #1600

Signed-off-by: Ivana Atanasova <iyovcheva@vmware.com>
---
 tuf/api/metadata.py | 29 +++++++++++++++--------------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/tuf/api/metadata.py b/tuf/api/metadata.py
index 471ebdb209..591c11f28c 100644
--- a/tuf/api/metadata.py
+++ b/tuf/api/metadata.py
@@ -119,7 +119,7 @@ def __init__(self, signed: T, signatures: Dict[str, Signature]):
 
     @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.
@@ -307,7 +307,8 @@ def sign(
         """Creates signature over ``signed`` and assigns it to ``signatures``.
 
         Args:
-            signer: A securesystemslib.signer.Signer implementation.
+            signer: Custom or securesystemslib implementation of the
+                ``securesystemslib.signer.Signer`` interface.
             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.
@@ -482,7 +483,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
@@ -584,7 +585,7 @@ def __init__(
 
     @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.
@@ -615,7 +616,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:
@@ -727,7 +728,7 @@ def __init__(
 
     @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.
@@ -789,7 +790,7 @@ def __init__(
 
     @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.
@@ -971,7 +972,7 @@ def __init__(
 
     @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.
@@ -1051,7 +1052,7 @@ def __init__(
 
     @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.
@@ -1104,7 +1105,7 @@ def __init__(
 
     @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.
@@ -1188,7 +1189,7 @@ def __init__(
 
     @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.
@@ -1316,7 +1317,7 @@ def __init__(
 
     @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.
@@ -1388,7 +1389,7 @@ def custom(self) -> Any:
 
     @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.
@@ -1535,7 +1536,7 @@ def __init__(
 
     @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.