DOC - explanatory docstring for cythonize

tools/nicythize

@@ -1,18 +1,32 @@
 #!/usr/bin/env python
 """ nicythize
 
+Cythonize pyx files into C files as needed.
+
+Usage: nicythize [root_dir]
+
+Default [root_dir] is 'nipy'.
+
+Checks pyx files to see if they have been changed relative to their
+corresponding C files.  If they have, then runs cython on these files to
+recreate the C files.
+
+The script thinks that the pyx files have changed relative to the C files if:
+
+* The pyx file is modified compared to the version checked into git, and the C
+  file is not
+* The pyx file was committed to the repository more recently than the C file.
+
 Simple script to invoke Cython (and Tempita) on all .pyx (.pyx.in)
 files; while waiting for a proper build system. Uses file hashes to
 figure out if rebuild is needed (using dates seem to fail with
 frequent change of git branch).
 
-For now, this scripts should be run by developers when changing Cython
-files only, and the resulting files checked in, so that end-users (and
-Python-only developers) do not get the Cython/Tempita dependencies.
-
-Originally written by Dag Sverre Seljebotn.
+For now, this script should be run by developers when changing Cython files
+only, and the resulting C files checked in, so that end-users (and Python-only
+developers) do not get the Cython/Tempita dependencies.
 
-This version copied from:
+Originally written by Dag Sverre Seljebotn, and copied here from:
 
 https://raw.github.com/dagss/private-scipy-refactor/cythonize/cythonize.py