Add docstrings to all functions in rmdepcheck

It's not really meant to be imported so these are a bit slapdash.

Signed-off-by: Adam Williamson <awilliam@redhat.com>

README.md

@@ -48,6 +48,10 @@ always specified as URLs. Only file:// , http:// and https:// URLs are accepted.
 
 For more complex usage, see `rmdepcheck --help`.
 
+Note rmdepcheck is really only intended for use as a script, not as an importable library. If you
+want to use it as a library go ahead, but this isn't a supported use case and bugs in it may not
+be addressed.
+
 ## License
 
 rmdepcheck is released under the [GPL](https://www.gnu.org/licenses/gpl.txt), version 3 or later.

rmdepcheck.py

@@ -55,12 +55,22 @@ REPOHASHES = {}
 
 
 def hash_repo(repo: str) -> str:
+    """Generate a hash for the repo name, stash it in a dict so we can
+    map back out later, and return it. This is so we can show the repo
+    URLs in our final output, as opposed to non-useful made-up repo
+    names. Not security sensitive.
+    """
     gothash = hashlib.sha256(repo.encode(encoding="utf-8")).hexdigest()[:8]
     REPOHASHES[gothash] = repo
     return gothash
 
 
 def parse_repoclosure(rc: str) -> list[tuple[str, str, str]]:
+    """Given some `dnf repoclosure` output, parse it into a list of
+    3-tuples each containing a package name, a repo URL (or generated
+    repo name if we can't look up the hash, should only happen in
+    tests) and an unresolved dependency for that package.
+    """
     out = []
     pkg = None
     for line in rc.splitlines():
@@ -81,6 +91,10 @@ def parse_repoclosure(rc: str) -> list[tuple[str, str, str]]:
 
 
 def format_rc_errors(errors: list[tuple[str, str, str]]) -> None:
+    """Format and print parse_repoclosure-style tuples for humans to
+    read. Used for final output after we do some diffing on the lists
+    of tuples.
+    """
     pkg = ("", "")
     for error in errors:
         if error[:2] != pkg:
@@ -90,6 +104,7 @@ def format_rc_errors(errors: list[tuple[str, str, str]]) -> None:
 
 
 def get_file(src: str, dest: str) -> None:
+    """Just downloads a file from src to dest."""
     SUBPCHECK(CURLARGS + ("-o", dest, src))
 
 
@@ -146,6 +161,10 @@ def replace_primary(primfn: str, removes: Sequence[str]) -> tuple[str, int, str,
 
 
 def get_base_repoclosure(baserepos: Sequence[str], nmbaserepos: Sequence[str]) -> str:
+    """Gets the reference repoclosure text. Both to-be-modified and
+    not-modified base repos are available to the solver, but only the
+    to-be-modified repos are checked.
+    """
     cmdargs = DNFARGS + ["repoclosure"]
     for repo in list(baserepos) + list(nmbaserepos):
         cmdargs.extend(["--repofrompath", f"{hash_repo(repo)},{repo}"])
@@ -159,6 +178,11 @@ def get_base_repoclosure(baserepos: Sequence[str], nmbaserepos: Sequence[str]) -
 def get_modified_repoclosure(
     mrepos: Sequence[str], nmrepos: Sequence[str], nrepos: Sequence[str], removes: Sequence[str]
 ) -> str:
+    """Does the repository metadata modification (the clever bit!) and
+    returns the modified repoclosure text. Non-modified base repos,
+    modified base repos after modification, and the new repo are
+    available to the solver; only modified base repos are checked.
+    """
     args = DNFARGS + ["repoclosure"]
     # place to stash the modified repos
     with tempfile.TemporaryDirectory() as mreposdir:
@@ -208,6 +232,12 @@ def get_modified_repoclosure(
 
 
 def get_new_repoclosure(baserepos: Sequence[str], nrepo: str) -> str:
+    """Gets and returns repoclosure text for the new repository; this
+    is effectively an installability check. All base repos are
+    available to the solver but are not checked. Note this is run
+    *after* repo modification, so the check runs against the modified
+    versions of the modifiable base repositories.
+    """
     cmdargs = DNFARGS + ["repoclosure"]
     for repo in baserepos:
         cmdargs.extend(["--repofrompath", f"{hash_repo(repo)},{repo}"])
@@ -216,6 +246,9 @@ def get_new_repoclosure(baserepos: Sequence[str], nrepo: str) -> str:
 
 
 def get_source_packages(repos: Sequence[str]) -> set[str]:
+    """Finds and returns the source package names for all packages in
+    the repositories specified, as a set.
+    """
     args = list(DNFARGS)
     for repo in repos:
         args.extend(["--repofrompath", f"{hash_repo(repo)},{repo}"])
@@ -225,6 +258,7 @@ def get_source_packages(repos: Sequence[str]) -> set[str]:
 
 
 def url_check(arg: str) -> str:
+    """Check arg is a file, http or https URL."""
     parsed = urlparse(arg)
     if parsed.scheme in ("http", "https", "file"):
         return arg
@@ -232,6 +266,9 @@ def url_check(arg: str) -> str:
 
 
 def comma_url(arg: str) -> list[str]:
+    """Check arg is a comma-separated list of URLs and return them
+    all as a list. If arg is the empty string, return empty list.
+    """
     if arg == "":
         return []
     split = arg.split(",")