[commit: directory] master: Document exception throwing behaviour of canonicalizedPath. (2334e09)

[David Terei]

Repository : ssh://darcs.haskell.org//srv/darcs/packages/directory

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/2334e09412f51bf847f3e23710daa566e561817f

>---------------------------------------------------------------

commit 2334e09412f51bf847f3e23710daa566e561817f
Author: David Terei <davidterei at gmail.com>
Date:   Mon Mar 4 15:36:48 2013 -0800

    Document exception throwing behaviour of canonicalizedPath.

>---------------------------------------------------------------

 System/Directory.hs |   14 +++++++++++---
 1 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/System/Directory.hs b/System/Directory.hs
index dbce2ff..0533563 100644
--- a/System/Directory.hs
+++ b/System/Directory.hs
@@ -685,13 +685,21 @@ copyFile fromFPath toFPath =
 
           ignoreIOExceptions io = io `catchIOError` (\_ -> return ())
 
--- | Given path referring to a file or directory, returns a
--- canonicalized path, with the intent that two paths referring
+-- | Given a path referring to a file or directory, returns a
+-- canonicalized path. The intent is that two paths referring
 -- to the same file\/directory will map to the same canonicalized
--- path. Note that it is impossible to guarantee that the
+-- path.
+--
+-- Note that it is impossible to guarantee that the
 -- implication (same file\/dir \<=\> same canonicalizedPath) holds
 -- in either direction: this function can make only a best-effort
 -- attempt.
+--
+-- The precise behaviour is that of the C realpath function
+-- GetFullPathNameW on Windows). In particular, the behaviour
+-- on paths that do not exist is known to vary from platform
+-- to platform. Some platforms do not alter the input, some
+-- do, and on some an exception will be thrown.
 canonicalizePath :: FilePath -> IO FilePath
 canonicalizePath fpath =
 #if defined(mingw32_HOST_OS)