[commit: packages/directory] master: Clarify docs for XDG directory and add link to migration guide (bac362f)

[git at git.haskell.org]

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

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

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

commit bac362fffeb4c79e4b432d3fdfba80d8dfae02b7
Author: Phil Ruffwind <rf at rufflewind.com>
Date:   Sat May 2 04:00:31 2015 -0400

    Clarify docs for XDG directory and add link to migration guide


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

bac362fffeb4c79e4b432d3fdfba80d8dfae02b7
 System/Directory.hs | 36 ++++++++++++++++++++----------------
 1 file changed, 20 insertions(+), 16 deletions(-)

diff --git a/System/Directory.hs b/System/Directory.hs
index c49d67f..151533d 100644
--- a/System/Directory.hs
+++ b/System/Directory.hs
@@ -1180,23 +1180,26 @@ getHomeDirectory =
 --   /Since: 1.2.3.0/
 data XdgDirectory
   = XdgData
-    -- ^ Data files:
-    --   may be overridden by the @XDG_DATA_HOME@ environment variable;
-    --   defaults to @~\/.local\/share@;
-    --   Windows equivalent: @%APPDATA%@
-    --   (e.g. @C:\/Users\//\<user\>/\/AppData\/Roaming@)
+    -- ^ For data files (e.g. images).
+    --   Defaults to @~\/.local\/share@ and can be
+    --   overridden by the @XDG_DATA_HOME@ environment variable.
+    --   On Windows, it is @%APPDATA%@
+    --   (e.g. @C:\/Users\//\<user\>/\/AppData\/Roaming@).
+    --   Can be considered as the user-specific equivalent of @\/usr\/share at .
   | XdgConfig
-    -- ^ For configuration files;
-    --   may be overridden by the @XDG_CONFIG_HOME@ environment variable;
-    --   defaults to @~\/.config@;
-    --   Windows equivalent: @%APPDATA%@
-    --   (e.g. @C:\/Users\//\<user\>/\/AppData\/Roaming@)
+    -- ^ For configuration files.
+    --   Defaults to @~\/.config@ and can be
+    --   overridden by the @XDG_CONFIG_HOME@ environment variable.
+    --   On Windows, it is @%APPDATA%@
+    --   (e.g. @C:\/Users\//\<user\>/\/AppData\/Roaming@).
+    --   Can be considered as the user-specific equivalent of @\/etc at .
   | XdgCache
-    -- ^ For non-essential (cached) data;
-    --   may be overridden by the @XDG_CACHE_HOME@ environment variable;
-    --   defaults to @~\/.cache@;
-    --   Windows equivalent: @%LOCALAPPDATA%@
-    --   (e.g. @C:\/Users\//\<user\>/\/AppData\/Local@)
+    -- ^ For non-essential files (e.g. cache).
+    --   Defaults to @~\/.cache@ and can be
+    --   overridden by the @XDG_CACHE_HOME@ environment variable.
+    --   On Windows, it is @%LOCALAPPDATA%@
+    --   (e.g. @C:\/Users\//\<user\>/\/AppData\/Local@).
+    --   Can be considered as the user-specific equivalent of @\/var\/cache at .
   deriving (Eq, Ord, Read, Show)
 
 -- | Obtain the paths to special directories for storing user-specific
@@ -1265,7 +1268,8 @@ tryIOErrorType check action = do
 --   application data (traditional Unix location).  Except for backward
 --   compatibility reasons, newer applications may prefer the the
 --   XDG-conformant location provided by 'getXdgDirectory', which offers a
---   more fine-grained hierarchy as well as greater flexibility for the user.
+--   more fine-grained hierarchy as well as greater flexibility for the user
+--   (<https://github.com/haskell/directory/issues/6#issuecomment-96521020 migration guide>).
 --
 --   The argument is usually the name of the application.  Since it will be
 --   integrated into the path, it must consist of valid path characters.