Improve docs for unsafeCoerce

Make it clear that compilers differ.  Point to GHC docs in GHC.Base, and
add a short description of nhc98's representation-safe conversions.

diff --git a/Unsafe/Coerce.hs b/Unsafe/Coerce.hs
index 00444bd..e911c6f 100644 (file)
--- a/Unsafe/Coerce.hs
+++ b/Unsafe/Coerce.hs
@@ -14,8 +14,16 @@
 -- it is your responsibility to ensure that the old and new types have
 -- identical internal representations, in order to prevent runtime corruption.
 --
--- 'unsafeCoerce' is just a trivial wrapper for 'unsafeCoerce#';
--- see the latter for important documentation about correct usage.
+-- The types for which 'unsafeCoerce' is representation-safe may differ
+-- from compiler to compiler (and version to version).
+--
+--   * Documentation for correct usage in GHC will be found under
+--     'unsafeCoerce#' in GHC.Base (around which 'unsafeCoerce' is just a
+--     trivial wrapper).
+--
+--   * In nhc98, the only representation-safe coercions are between Enum
+--     types with the same range (e.g. Int, Int32, Char, Word32),
+--     or between a newtype and the type that it wraps.
 
 module Unsafe.Coerce (unsafeCoerce) where