Pythonify source code

Remove a bunch of "C-style" dividers, unify spacing between functions,
add function docstrings (although most are just 'TODO:' entries).

As with the previous commits, this might be subject to taste but this
suits my taste and I think it's more pythonesque.
Add a few function docstrings

..also change interpreter from python2.5 to just 'python' so latest and
greated version installed is used.
A few comments
Corrected number of values

The number of values expected from and returned by two function calls
now match.