Explain design decisions in get_project_files().
Add docstrings to functions without.

Some pavement.py functions were missing them.
Improve read() function to close the file.