compile comments

bin/compile

 #!/usr/bin/env bash
 
+# The Heroku Python Buildpack. This script accepts paramaters for a build
+# directory, a cache directory, and a directory for app environment variables.
+
+# Warning: there are a few hacks in this script to accomidate excellent builds
+# on Heroku. No gaurentee for external compatibility is made. However,
+# everything should work fine outside of the Heroku environment, if the
+# environment is setup correctly.
+
 # Usage:
 #
 #     $ bin/compile <build-dir> <cache-dir> <env-path>
@@ -51,6 +59,7 @@ unset GIT_DIR PYTHONHOME PYTHONPATH LD_LIBRARY_PATH LIBRARY_PATH
 unset RECEIVE_DATA SOURCE_VERSION RUN_KEY BUILD_INFO DEPLOY
 unset LOG_TOKEN DYNO CYTOKINE_LOG_FILE GEM_PATH
 
+# Setup buildpack instrumentation.
 bpwatch init $LOGPLEX_KEY
 bpwatch build python $BUILDPACK_VERSION $REQUEST_ID
 TMP_APP_DIR=$CACHE_DIR/tmp_app_dir
@@ -98,7 +107,7 @@ WEBCONCURRENCY_PROFILE_PATH="$BUILD_DIR/.profile.d/python.webconcurrency.sh"
 # We'll need to send these statics to other scripts we `source`.
 export BUILD_DIR CACHE_DIR BIN_DIR PROFILE_PATH
 
-# Prepend proper path buildpack use.
+# Prepend proper environment variables for Python use.
 export PATH=$BUILD_DIR/.heroku/python/bin:$BUILD_DIR/.heroku/vendor/bin:$PATH
 export PYTHONUNBUFFERED=1
 export LANG=en_US.UTF-8
@@ -122,7 +131,7 @@ bpwatch start pre_compile
   source $BIN_DIR/steps/hooks/pre_compile
 bpwatch stop pre_compile
 
-# If no requirements given, assume `setup.py develop`.
+# If no requirements.txt file given, assume `setup.py develop` is intended.
 if [ ! -f requirements.txt ]; then
   echo "-e ." > requirements.txt
 fi
@@ -145,7 +154,7 @@ if [ ! -f runtime.txt ]; then
   echo $DEFAULT_PYTHON_VERSION > runtime.txt
 fi
 
-# ### The Cache
+# Prepare the cache.
 mkdir -p $CACHE_DIR
 
 # Purge "old-style" virtualenvs.
@@ -201,10 +210,7 @@ source $BIN_DIR/steps/pip-install
 sub-env $BIN_DIR/steps/collectstatic
 
 
-# ### Finalize
-#
-
-# Set context environment variables.
+# Create .profile script for application runtime environment variables.
 set-env PATH '$HOME/.heroku/python/bin:$PATH'
 set-env PYTHONUNBUFFERED true
 set-env PYTHONHOME /app/.heroku/python
@@ -241,7 +247,7 @@ bpwatch start dump_cache
 
 bpwatch stop dump_cache
 
-# ### Fin.
+# Fin.
 if [[ ! "$DOCKER_BUILD" ]]; then
 
   bpwatch start appdir_commit