Improve comments

Remove outdated comments.
Add explanations to non-obvious cases.

Signed-off-by: Teodora Sechkova <[email protected]>

Author: sechkova

tuf/ngclient/_internal/metadata_bundle.py

@@ -257,7 +257,6 @@ def update_timestamp(self, data: bytes):
                 error type and content will contain more details.
         """
         if not self._root_update_finished:
-            # root_update_finished() not called
             raise RuntimeError("Cannot update timestamp before root")
         if self.snapshot is not None:
             raise RuntimeError("Cannot update timestamp after snapshot")
@@ -277,6 +276,8 @@ def update_timestamp(self, data: bytes):
                 "New timestamp is not signed by root", new_timestamp.signed
             )
 
+        # If an existing trusted timestamp is updated,
+        # check for a rollback attack
         if self.timestamp is not None:
             # Prevent rolling back timestamp version
             if new_timestamp.signed.version < self.timestamp.signed.version:
@@ -290,7 +291,6 @@ def update_timestamp(self, data: bytes):
                 new_timestamp.signed.meta["snapshot.json"].version
                 < self.timestamp.signed.meta["snapshot.json"].version
             ):
-                # TODO not sure about the correct exception here
                 raise exceptions.ReplayedMetadataError(
                     "snapshot",
                     new_timestamp.signed.meta["snapshot.json"].version,
@@ -330,7 +330,6 @@ def update_snapshot(self, data: bytes):  # pylint: disable=too-many-branches
             digest_object.update(data)
             observed_hash = digest_object.hexdigest()
             if observed_hash != stored_hash:
-                # TODO: Error should derive from RepositoryError
                 raise exceptions.BadHashError(stored_hash, observed_hash)
 
         try:
@@ -358,6 +357,8 @@ def update_snapshot(self, data: bytes):  # pylint: disable=too-many-branches
                 f"got {new_snapshot.signed.version}"
             )
 
+        # If an existing trusted snapshot is updated,
+        # check for a rollback attack
         if self.snapshot:
             for filename, fileinfo in self.snapshot.signed.meta.items():
                 new_fileinfo = new_snapshot.signed.meta.get(filename)

tuf/ngclient/updater.py

@@ -122,7 +122,7 @@ def updated_targets(targets: Dict, destination_directory: str) -> Dict:
         After the client has retrieved the target information for those targets
         they are interested in updating, they would call this method to
         determine which targets have changed from those saved locally on disk.
-        All the targets that have changed are returns in a list.  From this
+        All the targets that have changed are returned in a list.  From this
         list, they can request a download by calling 'download_target()'.
         """
         # Keep track of the target objects and filepaths of updated targets.