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')