-# prompt is user@host:/dir$ where host is highlighted in green if the last
-# command exited 0 or in red (followed by the error code) otherwise
+# Prompt is user@host:/dir$ where host is highlighted in green if the last
+# command exited 0 or in red (followed by the error code) otherwise.
+#
+# Colouring is performed by the __ps1_col() and __ps1_ret() functions.
+# We redirect stderr to /dev/null when calling these functions to prevent
+# bash complaining about not knowing them when you su to another user,
+# retaining PS1 but not the function definitions.
+#
+# Override the PROMPT_OK_COLOUR and PROMPT_FAILED_COLOUR environment variables
+# to set different colours.
+#
+# To use, add a call to __ps1 in your .bash_profile file.