Improve docstrings

Signed-off-by: JoeLametta <JoeLametta@users.noreply.github.com>

whipper/common/accurip.py

@@ -43,8 +43,7 @@ class EntryNotFound(Exception):
 
 class _AccurateRipResponse:
     """
-    An AccurateRip response contains a collection of metadata identifying a
-    particular digital audio compact disc.
+    An AR resp. contains a collection of metadata identifying a specific disc.
 
     For disc level metadata it contains the track count, two internal disc
     IDs, and the CDDB disc ID.
@@ -55,9 +54,12 @@ class _AccurateRipResponse:
 
     The response is stored as a packed binary structure.
     """
+
     def __init__(self, data):
         """
-        The checksums and confidences arrays are indexed by relative track
+        Init _AccurateRipResponse.
+
+        Checksums and confidences arrays are indexed by relative track
         position, so track 1 will have array index 0, track 2 will have array
         index 1, and so forth. HTOA and other hidden tracks are not included.
         """
@@ -98,12 +100,14 @@ def _split_responses(raw_entry):
 
 def calculate_checksums(track_paths):
     """
-    Return ARv1 and ARv2 checksums as two arrays of character strings in a
-    dictionary: {'v1': ['deadbeef', ...], 'v2': [...]}
-
-    Return None instead of checksum string for unchecksummable tracks.
+    Calculate AccurateRip checksums for the given tracks.
 
     HTOA checksums are not included in the database and are not calculated.
+
+    :returns: ARv1 and ARv2 checksums as two arrays of character strings in a
+              dictionary: ``{'v1': ['deadbeef', ...], 'v2': [...]}``
+              or None instead of checksum string for unchecksummable tracks.
+    :rtype: dict(string, list()) or None
     """
     track_count = len(track_paths)
     v1_checksums = []
@@ -152,9 +156,10 @@ def _save_entry(raw_entry, path):
 def get_db_entry(path):
     """
     Retrieve cached AccurateRip disc entry as array of _AccurateRipResponses.
+
     Downloads entry from accuraterip.com on cache fault.
 
-    `path' is in the format of the output of table.accuraterip_path().
+    ``path`` is in the format of the output of ``table.accuraterip_path()``.
     """
     cached_path = join(_CACHE_DIR, path)
     if exists(cached_path):
@@ -183,11 +188,11 @@ def _assign_checksums_and_confidences(tracks, checksums, responses):
 
 def _match_responses(tracks, responses):
     """
-    Match and save track accuraterip response checksums against
-    all non-hidden tracks.
+    Match and save track AR response checksums against all non-hidden tracks.
 
-    Returns True if every track has a match for every entry for either
-    AccurateRip version.
+    :returns: True if every track has a match for every entry for either
+              AccurateRip version, False otherwise.
+    :rtype: bool
     """
     for r in responses:
         for i, track in enumerate(tracks):
@@ -211,7 +216,8 @@ def _match_responses(tracks, responses):
 def verify_result(result, responses, checksums):
     """
     Verify track AccurateRip checksums against database responses.
-    Stores track checksums and database values on result.
+
+    Store track checksums and database values on result.
     """
     if not (result and responses and checksums):
         return False
@@ -226,9 +232,7 @@ def verify_result(result, responses, checksums):
 
 
 def print_report(result):
-    """
-    Print AccurateRip verification results.
-    """
+    """Print AccurateRip verification results."""
     for _, track in enumerate(result.tracks):
         status = 'rip NOT accurate'
         conf = '(not found)'