[commit: packages/directory] master: Emphasize the more useful variant of getDirectoryContents (02b1f45)

[git at git.haskell.org]

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

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

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

commit 02b1f4524cc52df780ca62ef0ef26ac4ab3d81c8
Author: Phil Ruffwind <rf at rufflewind.com>
Date:   Sat Oct 10 20:36:20 2015 -0400

    Emphasize the more useful variant of getDirectoryContents


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

02b1f4524cc52df780ca62ef0ef26ac4ab3d81c8
 System/Directory.hs | 70 ++++++++++++++++++++++++++---------------------------
 1 file changed, 34 insertions(+), 36 deletions(-)

diff --git a/System/Directory.hs b/System/Directory.hs
index 0cd3d10..8f4dc36 100644
--- a/System/Directory.hs
+++ b/System/Directory.hs
@@ -29,8 +29,8 @@ module System.Directory
     , removeDirectory
     , removeDirectoryRecursive
     , renameDirectory
-    , getDirectoryContents
     , getDirectoryContentsA
+    , getDirectoryContents
     -- ** Current working directory
     , getCurrentDirectory
     , setCurrentDirectory
@@ -964,37 +964,8 @@ findFilesWith f (d:ds) fileName = do
         else findFilesWith f ds fileName
 
 #ifdef __GLASGOW_HASKELL__
-{- |@'getDirectoryContents' dir@ returns a list of /all/ entries
-in /dir/, including @.@ and @..@ (even on Windows).
-
-The operation may fail with:
-
-* 'HardwareFault'
-A physical I\/O error has occurred.
-@[EIO]@
-
-* 'InvalidArgument'
-The operand is not a valid directory name.
-@[ENAMETOOLONG, ELOOP]@
-
-* 'isDoesNotExistError' \/ 'NoSuchThing'
-The directory does not exist.
-@[ENOENT, ENOTDIR]@
-
-* 'isPermissionError' \/ 'PermissionDenied'
-The process has insufficient privileges to perform the operation.
-@[EACCES]@
-
-* 'ResourceExhausted'
-Insufficient resources are available to perform the operation.
-@[EMFILE, ENFILE]@
-
-* 'InappropriateType'
-The path refers to an existing non-directory object.
-@[ENOTDIR]@
-
--}
-
+-- | Similar to 'getDirectoryContentsA', but always includes the special entries (@.@
+-- and @..@).  (This applies to Windows as well.)
 getDirectoryContents :: FilePath -> IO [FilePath]
 getDirectoryContents path =
   modifyIOError ((`ioeSetFileName` path) .
@@ -1031,10 +1002,37 @@ getDirectoryContents path =
                  -- no need to reverse, ordering is undefined
 #endif /* mingw32 */
 
-{- | A version of 'getDirectoryContents' which returns /almost all/
-entries, ignoring the current and parent directories, @.@ and @.. at .
-
--}
+-- | @'getDirectoryContentsA' dir@ returns a list of /all/ entries in /dir/ without
+-- the special entries (@.@ and @..@).
+--
+-- The operation may fail with:
+--
+-- * 'HardwareFault'
+--   A physical I\/O error has occurred.
+--   @[EIO]@
+--
+-- * 'InvalidArgument'
+--   The operand is not a valid directory name.
+--   @[ENAMETOOLONG, ELOOP]@
+--
+-- * 'isDoesNotExistError' \/ 'NoSuchThing'
+--   The directory does not exist.
+--   @[ENOENT, ENOTDIR]@
+--
+-- * 'isPermissionError' \/ 'PermissionDenied'
+--   The process has insufficient privileges to perform the operation.
+--   @[EACCES]@
+--
+-- * 'ResourceExhausted'
+--   Insufficient resources are available to perform the operation.
+--   @[EMFILE, ENFILE]@
+--
+-- * 'InappropriateType'
+--   The path refers to an existing non-directory object.
+--   @[ENOTDIR]@
+--
+-- @since 1.2.5.0
+--
 getDirectoryContentsA :: FilePath -> IO [FilePath]
 getDirectoryContentsA path =
   (filter f) <$> (getDirectoryContents path)