-/* -----------------------------------------------------------------------------
- Shutting down the RTS
- -------------------------------------------------------------------------- */
+/* ----------------------------------------------------------------------------
+ * Shutting down the RTS
+ *
+ * The wait_foreign parameter means:
+ * True ==> wait for any threads doing foreign calls now.
+ * False ==> threads doing foreign calls may return in the
+ * future, but will immediately block on a mutex.
+ * (capability->lock).
+ *
+ * If this RTS is a DLL that we're about to unload, then you want
+ * safe=True, otherwise the thread might return to code that has been
+ * unloaded. If this is a standalone program that is about to exit,
+ * then you can get away with safe=False, which is better because we
+ * won't hang on exit if there is a blocked foreign call outstanding.
+ *
+ ------------------------------------------------------------------------- */