Fix documentation

This commit is contained in:
Julian Ospald 2016-06-05 15:57:41 +02:00
parent d708f80a1f
commit 7ed5829d47
No known key found for this signature in database
GPG Key ID: 511B62C09D50CD28
1 changed files with 48 additions and 29 deletions

View File

@ -225,10 +225,9 @@ data FileType = Directory
-- recursive sub-operations fail, which is sort of the default -- recursive sub-operations fail, which is sort of the default
-- for IO operations. -- for IO operations.
-- --
-- On `CollectFailures` skips and collects the failed sub-operation -- On `CollectFailures` skips errors in the recursion and keeps on recursing.
-- and keeps on -- However all errors are collected in the `RecursiveFailure` error type,
-- recursing. At the end an exception describing the collected -- which is raised finally if there was any error.
-- failures will still be raised.
data RecursiveMode = FailEarly data RecursiveMode = FailEarly
| CollectFailures | CollectFailures
@ -251,14 +250,16 @@ data CopyMode = Strict -- ^ fail if any target exists
-- |Copies a directory recursively to the given destination. -- |Copies a directory recursively to the given destination.
-- Does not follow symbolic links. -- Does not follow symbolic links.
-- --
-- For directory contents, this has the same behavior as `easyCopy` -- For directory contents, this will ignore any file type that is not
-- and thus will ignore any file type that is not `RegularFile`, -- `RegularFile`, `SymbolicLink` or `Directory`.
-- `SymbolicLink` or `Directory`.
-- --
-- For `Overwrite` mode this does not prune destination directory contents, -- For `Overwrite` mode this does not prune destination directory contents,
-- so the destination might contain more files than the source after -- so the destination might contain more files than the source after
-- the operation has completed. -- the operation has completed.
-- --
-- Note that there is no guaranteed ordering of the exceptions
-- contained within `RecursiveFailure` in `CollectFailures` RecursiveMode.
--
-- Safety/reliability concerns: -- Safety/reliability concerns:
-- --
-- * not atomic -- * not atomic
@ -271,20 +272,25 @@ data CopyMode = Strict -- ^ fail if any target exists
-- Throws: -- Throws:
-- --
-- - `NoSuchThing` if source directory does not exist -- - `NoSuchThing` if source directory does not exist
-- - `PermissionDenied` if output directory is not writable
-- - `PermissionDenied` if source directory can't be opened -- - `PermissionDenied` if source directory can't be opened
-- - `SameFile` if source and destination are the same file
-- (`HPathIOException`)
-- - `DestinationInSource` if destination is contained in source
-- (`HPathIOException`)
--
-- Throws in `FailEarly` RecursiveMode only:
--
-- - `PermissionDenied` if output directory is not writable
-- - `InvalidArgument` if source directory is wrong type (symlink) -- - `InvalidArgument` if source directory is wrong type (symlink)
-- - `InvalidArgument` if source directory is wrong type (regular file) -- - `InappropriateType` if source directory is wrong type (regular file)
-- - `SameFile` if source and destination are the same file (`HPathIOException`)
-- - `DestinationInSource` if destination is contained in source (`HPathIOException`)
-- - `RecursiveFailure` if any sub-operation failed (for `CollectFailures` RecursiveMode only)
--
-- Throws in `Strict` CopyMode only:
--
-- - `AlreadyExists` if destination already exists
-- --
-- Throws in `CollectFailures` RecursiveMode only: -- Throws in `CollectFailures` RecursiveMode only:
-- --
-- - `RecursiveFailure` if any of the recursive operations that are not
-- part of the top-directory sanity-checks fails (`HPathIOException`)
--
-- Throws in `Strict` CopyMode only:
--
-- - `AlreadyExists` if destination already exists -- - `AlreadyExists` if destination already exists
copyDirRecursive :: Path Abs -- ^ source dir copyDirRecursive :: Path Abs -- ^ source dir
-> Path Abs -- ^ full destination -> Path Abs -- ^ full destination
@ -313,7 +319,8 @@ copyDirRecursive fromp destdirp cm rm
fmode' <- PF.fileMode <$> PF.getSymbolicLinkStatus (fromAbs fromp') fmode' <- PF.fileMode <$> PF.getSymbolicLinkStatus (fromAbs fromp')
case cm of case cm of
Strict -> createDirectory (fromAbs destdirp') fmode' Strict -> createDirectory (fromAbs destdirp') fmode'
Overwrite -> catchIOError (createDirectory (fromAbs destdirp') fmode') Overwrite -> catchIOError (createDirectory (fromAbs destdirp')
fmode')
$ \e -> $ \e ->
case ioeGetErrorType e of case ioeGetErrorType e of
AlreadyExists -> setFileMode (fromAbs destdirp') AlreadyExists -> setFileMode (fromAbs destdirp')
@ -352,7 +359,8 @@ copyDirRecursive fromp destdirp cm rm
-- - `InvalidArgument` if source file is wrong type (not a symlink) -- - `InvalidArgument` if source file is wrong type (not a symlink)
-- - `PermissionDenied` if output directory cannot be written to -- - `PermissionDenied` if output directory cannot be written to
-- - `PermissionDenied` if source directory cannot be opened -- - `PermissionDenied` if source directory cannot be opened
-- - `SameFile` if source and destination are the same file (`HPathIOException`) -- - `SameFile` if source and destination are the same file
-- (`HPathIOException`)
-- --
-- --
-- Throws in `Strict` mode only: -- Throws in `Strict` mode only:
@ -410,7 +418,8 @@ recreateSymlink symsource newsym cm
-- - `PermissionDenied` if output directory is not writable -- - `PermissionDenied` if output directory is not writable
-- - `PermissionDenied` if source directory can't be opened -- - `PermissionDenied` if source directory can't be opened
-- - `InvalidArgument` if source file is wrong type (symlink or directory) -- - `InvalidArgument` if source file is wrong type (symlink or directory)
-- - `SameFile` if source and destination are the same file (`HPathIOException`) -- - `SameFile` if source and destination are the same file
-- (`HPathIOException`)
-- --
-- Throws in `Strict` mode only: -- Throws in `Strict` mode only:
-- --
@ -452,8 +461,8 @@ _copyFile :: [SPDF.Flags]
_copyFile sflags dflags from to _copyFile sflags dflags from to
= =
-- from sendfile(2) manpage: -- from sendfile(2) manpage:
-- Applications may wish to fall back to read(2)/write(2) in the case -- Applications may wish to fall back to read(2)/write(2) in
-- where sendfile() fails with EINVAL or ENOSYS. -- the case where sendfile() fails with EINVAL or ENOSYS.
withAbsPath to $ \to' -> withAbsPath from $ \from' -> withAbsPath to $ \to' -> withAbsPath from $ \from' ->
catchErrno [eINVAL, eNOSYS] catchErrno [eINVAL, eNOSYS]
(sendFileCopy from' to') (sendFileCopy from' to')
@ -489,7 +498,8 @@ _copyFile sflags dflags from to
if size == 0 if size == 0
then return $ fromIntegral totalsize then return $ fromIntegral totalsize
else do rsize <- SPB.fdWriteBuf dfd buf size else do rsize <- SPB.fdWriteBuf dfd buf size
when (rsize /= size) (throwIO . CopyFailed $ "wrong size!") when (rsize /= size) (throwIO . CopyFailed
$ "wrong size!")
write' sfd dfd buf (totalsize + fromIntegral size) write' sfd dfd buf (totalsize + fromIntegral size)
@ -637,7 +647,8 @@ executeFile fp args
--------------------- ---------------------
-- |Create an empty regular file at the given directory with the given filename. -- |Create an empty regular file at the given directory with the given
-- filename.
-- --
-- Throws: -- Throws:
-- --
@ -696,10 +707,14 @@ createSymlink dest sympoint
-- - `NoSuchThing` if source file does not exist -- - `NoSuchThing` if source file does not exist
-- - `PermissionDenied` if output directory cannot be written to -- - `PermissionDenied` if output directory cannot be written to
-- - `PermissionDenied` if source directory cannot be opened -- - `PermissionDenied` if source directory cannot be opened
-- - `UnsupportedOperation` if source and destination are on different devices -- - `UnsupportedOperation` if source and destination are on different
-- - `FileDoesExist` if destination file already exists (`HPathIOException`) -- devices
-- - `DirDoesExist` if destination directory already exists (`HPathIOException`) -- - `FileDoesExist` if destination file already exists
-- - `SameFile` if destination and source are the same file (`HPathIOException`) -- (`HPathIOException`)
-- - `DirDoesExist` if destination directory already exists
-- (`HPathIOException`)
-- - `SameFile` if destination and source are the same file
-- (`HPathIOException`)
-- --
-- Note: calls `rename` (but does not allow to rename over existing files) -- Note: calls `rename` (but does not allow to rename over existing files)
renameFile :: Path Abs -> Path Abs -> IO () renameFile :: Path Abs -> Path Abs -> IO ()
@ -731,12 +746,14 @@ renameFile fromf tof = do
-- - `NoSuchThing` if source file does not exist -- - `NoSuchThing` if source file does not exist
-- - `PermissionDenied` if output directory cannot be written to -- - `PermissionDenied` if output directory cannot be written to
-- - `PermissionDenied` if source directory cannot be opened -- - `PermissionDenied` if source directory cannot be opened
-- - `SameFile` if destination and source are the same file (`HPathIOException`) -- - `SameFile` if destination and source are the same file
-- (`HPathIOException`)
-- --
-- Throws in `Strict` mode only: -- Throws in `Strict` mode only:
-- --
-- - `FileDoesExist` if destination file already exists (`HPathIOException`) -- - `FileDoesExist` if destination file already exists (`HPathIOException`)
-- - `DirDoesExist` if destination directory already exists (`HPathIOException`) -- - `DirDoesExist` if destination directory already exists
-- (`HPathIOException`)
-- --
-- Note: calls `rename` (but does not allow to rename over existing files) -- Note: calls `rename` (but does not allow to rename over existing files)
moveFile :: Path Abs -- ^ file to move moveFile :: Path Abs -- ^ file to move
@ -805,6 +822,8 @@ newDirPerms
-- |Gets all filenames of the given directory. This excludes "." and "..". -- |Gets all filenames of the given directory. This excludes "." and "..".
-- This version does not follow symbolic links. -- This version does not follow symbolic links.
-- --
-- The contents are not sorted and there is no guarantee on the ordering.
--
-- Throws: -- Throws:
-- --
-- - `NoSuchThing` if directory does not exist -- - `NoSuchThing` if directory does not exist