moved function definition comments to doc strings

learned from
http://www.diveintopython.net/getting_to_know_python/documenting_functio
ns.html and http://learnpythonthehardway.org/book/ex25.html