Convert docstrings to reStructuredText

This commit also includes:

  - whitespace / code formatting fixes
  - slight syntax related changes: except <exception_name>, e -> except <exception_name> as e
  - 3 pointless instructions instances have been rewritten [sorted] (spotted by semi-automatic check)

The unrelated changes shouldn't have any real impact on whipper's behaviour.

whipper/test/common.py

@@ -49,9 +49,9 @@ class TestCase(unittest.TestCase):
     def failUnlessRaises(self, exception, f, *args, **kwargs):
         try:
             result = f(*args, **kwargs)
-        except exception, inst:
+        except exception as inst:
             return inst
-        except exception, e:
+        except exception as e:
             raise Exception('%s raised instead of %s:\n %s' %
                             (sys.exec_info()[0], exception.__name__, str(e))
                             )
@@ -63,9 +63,14 @@ class TestCase(unittest.TestCase):
     assertRaises = failUnlessRaises
 
     def readCue(self, name):
-        """
-        Read a .cue file, and replace the version comment with the current
-        version so we can use it in comparisons.
+        """Read a cue file and replace its version number with the current one.
+
+        The version number is replaced to use the cue file in comparisons.
+
+        :param name: cuesheet filename (without path).
+        :type name: str
+        :returns: the cuesheet with version number replaced.
+        :rtype: str
         """
         cuefile = os.path.join(os.path.dirname(__file__), name)
         ret = open(cuefile).read().decode('utf-8')

whipper/test/test_common_accurip.py

@@ -110,7 +110,7 @@ class TestVerifyResult(TestCase):
 
     def setUp(self):
         self.result = RipResult()
-        for n in range(1, 2+1):
+        for n in range(1, 2 + 1):
             track = TrackResult()
             track.number = n
             self.result.tracks.append(track)

whipper/test/test_common_mbngs.py

@@ -116,11 +116,9 @@ class MetadataTestCase(unittest.TestCase):
                           )
 
     def testNorthernGateway(self):
-        """
-        check the received metadata for artists tagged with [unknown]
-        and artists tagged with an alias in MusicBrainz
+        """Check MBz metadata for artists tagged with: [unknown] / an alias.
 
-        see https://github.com/JoeLametta/whipper/issues/155
+        .. seealso:: https://github.com/JoeLametta/whipper/issues/156
         """
         filename = 'whipper.release.38b05c7d-65fe-4dc0-9c10-33a391b86703.json'
         path = os.path.join(os.path.dirname(__file__), filename)
@@ -157,9 +155,12 @@ class MetadataTestCase(unittest.TestCase):
                           )
 
     def testNenaAndKimWildSingle(self):
-        """
-        check the received metadata for artists that differ between
-        named on release and named in recording
+        """Check MBz metadata for artists with different names.
+
+        An artist can have different names on MusicBrainz like:
+        *artist in MusicBrainz*, *artist as credited*.
+
+        .. seealso:: https://github.com/JoeLametta/whipper/issues/156
         """
         filename = 'whipper.release.f484a9fc-db21-4106-9408-bcd105c90047.json'
         path = os.path.join(os.path.dirname(__file__), filename)