[commit: packages/directory] master: Update documentation of `canonicalizePath` (e87edde)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/directory

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/e87eddebece7d67dc0276fa71eeb3b49aea46a92/directory

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

commit e87eddebece7d67dc0276fa71eeb3b49aea46a92
Author: Phil Ruffwind <rf at rufflewind.com>
Date:   Wed Mar 11 02:24:33 2015 -0400

    Update documentation of `canonicalizePath`


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

e87eddebece7d67dc0276fa71eeb3b49aea46a92
 System/Directory.hs | 33 ++++++++++++++++++---------------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/System/Directory.hs b/System/Directory.hs
index 32dc453..be8379d 100644
--- a/System/Directory.hs
+++ b/System/Directory.hs
@@ -737,24 +737,27 @@ copyFile fromFPath toFPath =
 
           ignoreIOExceptions io = io `catchIOError` (\_ -> return ())
 
--- | 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.
+-- | Canonicalize the path of an existing file or directory.  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
--- implication (same file\/dir \<=\> same canonicalizedPath) holds
--- in either direction: this function can make only a best-effort
--- attempt.
+-- __Note__: if you only require an absolute path, consider using
+-- @'makeAbsolute'@ instead, which is more reliable and does not have
+-- unspecified behavior on nonexistent paths.
 --
--- 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.
+-- It is impossible to guarantee that the implication (same file\/dir \<=\>
+-- same canonicalized path) holds in either direction: this function can make
+-- only a best-effort attempt.
+--
+-- The precise behaviour is that of the POSIX @realpath@ function (or
+-- @GetFullPathNameW@ on Windows).  In particular, the behaviour on paths that
+-- don't exist can vary from platform to platform.  Some platforms do not
+-- alter the input, some do, and some throw an exception.
+--
+-- An empty path is considered to be equivalent to the current directory.
+--
+-- /Known bug(s)/: on Windows, this function does not resolve symbolic links.
 --
--- If passed an empty string, behaviour is equivalent to
--- calling canonicalizePath on the current directory.
 canonicalizePath :: FilePath -> IO FilePath
 canonicalizePath ""    = canonicalizePath "."
 canonicalizePath fpath =