From e7cb9fd8e6be44dbe95ee80c6cc055d1f48066c5 Mon Sep 17 00:00:00 2001
From: Julian Ospald <hasufell@posteo.de>
Date: Sun, 12 May 2024 23:25:45 +0800
Subject: [PATCH] Document caveats for encodeWith

See https://github.com/haskell/os-string/issues/15
---
 System/OsPath/Internal.hs | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/System/OsPath/Internal.hs b/System/OsPath/Internal.hs
index 3b81d686..bc1d5a9b 100644
--- a/System/OsPath/Internal.hs
+++ b/System/OsPath/Internal.hs
@@ -56,8 +56,12 @@ unsafeEncodeUtf :: HasCallStack => String -> OsString
 unsafeEncodeUtf = OS.unsafeEncodeUtf
 
 -- | Encode a 'FilePath' with the specified encoding.
+--
+-- Note: on windows, we expect a "wide char" encoding (e.g. UCS-2 or UTF-16). Anything
+-- that works with @Word16@ boundaries. Picking an incompatible encoding may crash
+-- filepath operations.
 encodeWith :: TextEncoding  -- ^ unix text encoding
-           -> TextEncoding  -- ^ windows text encoding
+           -> TextEncoding  -- ^ windows text encoding (wide char)
            -> FilePath
            -> Either EncodingException OsPath
 encodeWith = OS.encodeWith