Improve docstrings

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

whipper/common/common.py

@@ -39,14 +39,14 @@ BYTES_PER_FRAME = SAMPLES_PER_FRAME * 4
 
 
 class EjectError(SystemError):
-    """
-    Possibly ejects the drive in command.main.
-    """
+    """Possibly eject the drive in command.main."""
 
     def __init__(self, device, *args):
         """
-        args is a tuple used by BaseException.__str__
-        device is the device path to eject
+        Init EjectError.
+
+        :param args: a tuple used by ``BaseException.__str__``
+        :param device: device path to eject
         """
         self.args = args
         self.device = device
@@ -54,13 +54,12 @@ class EjectError(SystemError):
 
 def msfToFrames(msf):
     """
-    Converts a string value in MM:SS:FF to frames.
+    Convert a string value in MM:SS:FF to frames.
 
     :param msf: the MM:SS:FF value to convert
-    :type  msf: str
-
-    :rtype:   int
+    :type msf: str
     :returns: number of frames
+    :rtype: int
     """
     if ':' not in msf:
         return int(msf)
@@ -97,21 +96,19 @@ def framesToHMSF(frames):
 
 def formatTime(seconds, fractional=3):
     """
-    Nicely format time in a human-readable format, like
-    HH:MM:SS.mmm
+    Nicely format time in a human-readable format, like HH:MM:SS.mmm.
 
     If fractional is zero, no seconds will be shown.
     If it is greater than 0, we will show seconds and fractions of seconds.
     As a side consequence, there is no way to show seconds without fractions.
 
-    :param seconds:    the time in seconds to format.
-    :type  seconds:    int or float
+    :param seconds: the time in seconds to format
+    :type seconds: int or float
     :param fractional: how many digits to show for the fractional part of
-                       seconds.
-    :type  fractional: int
-
+                       seconds
+    :type fractional: int
+    :returns: a nicely formatted time string
     :rtype: string
-    :returns: a nicely formatted time string.
     """
     chunks = []
 
@@ -149,16 +146,13 @@ class EmptyError(Exception):
 
 
 class MissingFrames(Exception):
-    """
-    Less frames decoded than expected.
-    """
+    """Less frames decoded than expected."""
+
     pass
 
 
 def truncate_filename(path):
-    """
-    Truncate filename to the max. len. allowed by the path's filesystem
-    """
+    """Truncate filename to the max. len. allowed by the path's filesystem."""
     p, f = os.path.split(os.path.normpath(path))
     f, e = os.path.splitext(f)
     # Get the filename length limit in bytes
@@ -172,7 +166,8 @@ def truncate_filename(path):
 def shrinkPath(path):
     """
     Shrink a full path to a shorter version.
-    Used to handle ENAMETOOLONG
+
+    Used to handle ``ENAMETOOLONG``.
     """
     parts = list(os.path.split(path))
     length = len(parts[-1])
@@ -204,14 +199,15 @@ def shrinkPath(path):
 def getRealPath(refPath, filePath):
     """
     Translate a .cue or .toc's FILE argument to an existing path.
+
     Does Windows path translation.
+
     Will look for the given file name, but with .flac and .wav as extensions.
 
-    :param refPath:  path to the file from which the track is referenced;
-                     for example, path to the .cue file in the same directory
-    :type  refPath:  str
-
-    :type  filePath: str
+    :param refPath: path to the file from which the track is referenced;
+                    for example, path to the .cue file in the same directory
+    :type refPath: str
+    :type filePath: str
     """
     assert isinstance(filePath, str), "%r is not str" % filePath
 
@@ -258,10 +254,9 @@ def getRealPath(refPath, filePath):
 
 def getRelativePath(targetPath, collectionPath):
     """
-    Get a relative path from the directory of collectionPath to
-    targetPath.
+    Get a relative path from the directory of collectionPath to targetPath.
 
-    Used to determine the path to use in .cue/.m3u files
+    Used to determine the path to use in .cue/.m3u files.
     """
     logger.debug('getRelativePath: target %r, collection %r',
                  targetPath, collectionPath)
@@ -280,9 +275,7 @@ def getRelativePath(targetPath, collectionPath):
 
 
 def validate_template(template, kind):
-    """
-    Raise exception if disc/track template includes invalid variables
-    """
+    """Raise exception if disc/track template includes invalid variables."""
     if kind == 'disc':
         matches = re.findall(r'%[^ARSXdrxy]', template)
     elif kind == 'track':
@@ -294,20 +287,22 @@ def validate_template(template, kind):
 
 class VersionGetter:
     """
-    I get the version of a program by looking for it in command output
-    according to a regexp.
+    Get the version of a program.
+
+    It is extracted by looking for it in command output according to a RegEX.
     """
 
     def __init__(self, dependency, args, regexp, expander):
         """
-        :param dependency: name of the dependency providing the program
-        :param args:       the arguments to invoke to show the version
-        :type  args:       list of str
-        :param regexp:     the regular expression to get the version
-        :param expander:   the expansion string for the version using the
-                           regexp group dict
-        """
+        Init VersionGetter.
 
+        :param dependency: name of the dependency providing the program
+        :param args: the arguments to invoke to show the version
+        :type args: list(str)
+        :param regexp: the regular expression to get the version
+        :param expander: the expansion string for the version using the
+                         regexp group dict
+        """
         self._dep = dependency
         self._args = args
         self._regexp = regexp