Update docstrings to include descriptions of snapshot merkle parameters.

Signed-off-by: marinamoore <[email protected]>

Author: mnm678

tuf/client/updater.py

@@ -1522,6 +1522,11 @@ def _get_metadata_file(self, metadata_role, remote_filename,
         The expected and required version number of the 'metadata_role' file
         downloaded.  'expected_version' is an integer.
 
+      snapshot_merkle:
+        Is the metadata file a snapshot merkle file? Snapshot merkle files
+        are not signed and so should skip some of the verification steps here.
+        Instead, they must be verified using _verify_merkle_path.
+
     <Exceptions>
       tuf.exceptions.NoWorkingMirrorError:
         The metadata could not be fetched. This is raised only when all known
@@ -1768,6 +1773,11 @@ def _update_metadata(self, metadata_role, upperbound_filelength, version=None,
         The expected and required version number of the 'metadata_role' file
         downloaded.  'expected_version' is an integer.
 
+      snapshot_merkle:
+        Is the metadata to be updated for a snapshot merkle file?
+        Snapshot merkle metadata does not contain a signature, but must
+        instead be verified using _verify_merkle_path.
+
     <Exceptions>
       tuf.exceptions.NoWorkingMirrorError:
         The metadata cannot be updated. This is not specific to a single

tuf/repository_lib.py

@@ -1834,6 +1834,11 @@ def generate_snapshot_metadata(metadata_directory, version, expiration_date,
       Read more at section 5.6 from the Mercury paper:
       https://www.usenix.org/conference/atc17/technical-sessions/presentation/kuppusamy
 
+    snapshot_merkle:
+      Whether to generate snapshot merkle files in addition to snapshot.json
+      metadata. If this is true, this function will return the root and leaves
+      of the merkle tree in addition to the snapshot metadata.
+
   <Exceptions>
     securesystemslib.exceptions.FormatError, if the arguments are improperly
     formatted.
@@ -1979,6 +1984,10 @@ def generate_timestamp_metadata(snapshot_file_path, version, expiration_date,
       metadata file in the timestamp metadata.
       Default is True.
 
+    roleinfo:
+      The roleinfo for the timestamp role. This is used when a snapshot
+      merkle tree is used to access the merkle tree's root hash.
+
   <Exceptions>
     securesystemslib.exceptions.FormatError, if the generated timestamp metadata
     object cannot be formatted correctly, or one of the arguments is improperly

tuf/repository_tool.py

@@ -291,6 +291,10 @@ def writeall(self, consistent_snapshot=False, use_existing_fileinfo=False, snaps
         written as-is (True) or whether hashes should be generated (False,
         requires access to the targets files on-disk).
 
+      snapshot_merkle:
+        Whether to generate snapshot merkle metadata in addition to snapshot
+        metadata.
+
     <Exceptions>
       tuf.exceptions.UnsignedMetadataError, if any of the top-level
       and delegated roles do not have the minimum threshold of signatures.