docs: repository api module's docstrings

taf/api/metadata.py

@@ -1,7 +1,7 @@
 import datetime
 from logging import DEBUG, ERROR, INFO
 from pathlib import Path
-from logdecorator import log_on_end, log_on_error, log_on_start
+from logdecorator import log_on_end, log_on_error
 from taf.exceptions import TargetsMetadataUpdateError
 from taf.git import GitRepository
 from taf.keys import load_signing_keys

taf/api/repository.py

@@ -1,5 +1,7 @@
 from functools import partial
+from logging import INFO
 import click
+from logdecorator import log_on_start, log_on_end
 
 from collections import defaultdict
 from pathlib import Path
@@ -12,28 +14,31 @@
 from taf.keys import get_key_name, load_sorted_keys_of_new_roles
 from taf.repository_tool import Repository, yubikey_signature_provider
 from tuf.repository_tool import create_new_repository
+from taf.log import taf_logger
 
 
+@log_on_end(INFO, "Created new authentication repository", logger=taf_logger)
 def create_repository(
     repo_path, keystore=None, roles_key_infos=None, commit=False, test=False
 ):
     """
-    <Purpose>
+    Purpose:
         Create a new authentication repository. Generate initial metadata files.
-        The initial targets metadata file is empty (does not specify any targets).
-    <Arguments>
-        repo_path:
-        Authentication repository's location
-        targets_directory:
-        Directory which contains target repositories
-        keystore:
-        Location of the keystore files
-        roles_key_infos:
-        A dictionary whose keys are role names, while values contain information about the keys.
-        commit:
-        Indicates if the changes should be automatically committed
-        test:
-        Indicates if the created repository is a test authentication repository
+        If target files already exist, add corresponding targets information to
+        targets metadata files.
+
+    Arguments:
+        repo_path: Authentication repository's location.
+        keystore: Location of the keystore files.
+        roles_key_infos: A dictionary whose keys are role names, while values contain information about the keys.
+        commit: Indicates if the changes should be automatically committed.
+        test: Indicates if the created repository is a test authentication repository.
+
+    Side Effects:
+        Creates a new authentication repository (initializes a new git repository and generates tuf metadata)
+
+    Returns:
+        None
     """
     yubikeys = defaultdict(dict)
     auth_repo = AuthenticationRepository(path=repo_path)
@@ -85,15 +90,29 @@ def create_repository(
         # if there are no target files
         repository.writeall()
 
-    print("Created new authentication repository")
-
     if commit:
         auth_repo.init_repo()
         commit_message = input("\nEnter commit message and press ENTER\n\n")
         auth_repo.commit(commit_message)
 
 
 def _check_if_can_create_repository(auth_repo):
+    """
+    Purpose:
+       Check if a new authentication repository can be created at the specified location.
+       A repository can be created if there is not directory at the repository's location
+       or if it does exists, is not the root of a git repository.
+
+    Arguments:
+        auth_repo: Authentication repository.
+
+
+    Side Effects:
+        None
+
+    Returns:
+        True if a new authentication repository can be created, False otherwise.
+    """
     repo_path = Path(auth_repo.path)
     if repo_path.is_dir():
         # check if there is non-empty metadata directory
@@ -119,6 +138,26 @@ def _setup_role(
     signing_keys=None,
     parent=None,
 ):
+    """
+    Purpose:
+        Set up a role, which can wither be one of the main TUF roles, or a delegated role.
+        Define threshold and signing and verification keys of the role and link it with the repository.
+
+    Arguments:
+        role_name: Role's name, either one of the main TUF roles or a delegated role.
+        threshold: Signatures threshold.
+        is_yubikey: Indicates if the role's metadata file should be signed using Yubikeys or not.
+        repository: TUF repository
+        verification_keys: Public keys used to verify the signatures
+        signing_keys (optional): Signing (private) keys, which only need to be specified if Yubikeys are not used
+        parent: The role's parent role
+
+    Side Effects:
+        Adds a new role to the TUF repository and sets up its threshold and signing and verification keys
+
+    Returns:
+        None
+    """
     role_obj = _role_obj(role_name, repository, parent)
     role_obj.threshold = threshold
     if not is_yubikey: