hasufell/hsfm
1
1
Fork 0
Code Issues 33 Pull Requests Releases Wiki Activity

LIB: improve documentation formatting

Browse Source
This commit is contained in:
Julian Ospald 2016-05-02 20:49:08 +02:00
parent 71cee4019b
commit 37516306d3
No known key found for this signature in database
GPG Key ID: 511B62C09D50CD28
1 changed files with 74 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
src/HSFM/FileSystem/FileOperations.hs
View File

@ -227,14 +227,17 @@ runFileOp fo' =
-- `DirCopyMode`. Excludes symlinks. -- `DirCopyMode`. Excludes symlinks.
-- --
-- Safety/reliability concerns: -- Safety/reliability concerns:
--
-- * not atomic -- * not atomic
-- * examines filetypes explicitly -- * examines filetypes explicitly
-- * an explicit check `throwDestinationInSource` is carried out for the top -- * an explicit check `throwDestinationInSource` is carried out for the
-- directory for basic sanity, because otherwise we might end up with an -- top directory for basic sanity, because otherwise we might end up
-- infinite copy loop... however, this operation is not carried out -- with an infinite copy loop... however, this operation is not
-- recursively (because it's slow) -- carried out recursively (because it's slow)
-- --
-- Throws: - `NoSuchThing` if source directory does not exist -- Throws:
--
-- - `NoSuchThing` if source directory does not exist
-- - `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 directory is wrong type (symlink) -- - `InvalidArgument` if source directory is wrong type (symlink)
@ -273,7 +276,9 @@ copyDirRecursive fromp destdirp
-- |Recreate a symlink. -- |Recreate a symlink.
-- --
-- Throws: - `InvalidArgument` if symlink file is wrong type (file) -- Throws:
--
-- - `InvalidArgument` if symlink file is wrong type (file)
-- - `InvalidArgument` if symlink file is wrong type (directory) -- - `InvalidArgument` if symlink file is wrong type (directory)
-- - `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
@ -293,7 +298,9 @@ recreateSymlink symsource newsym
-- |Copies the given regular file to the given dir with the given filename. -- |Copies the given regular file to the given dir with the given filename.
-- Excludes symlinks. -- Excludes symlinks.
-- --
-- Throws: - `NoSuchThing` if source file does not exist -- Throws:
--
-- - `NoSuchThing` if source file does not exist
-- - `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) -- - `InvalidArgument` if source file is wrong type (symlink)
@ -358,6 +365,7 @@ copyFile from to
-- it is just recreated, even if it points to a directory. -- it is just recreated, even if it points to a directory.
-- --
-- Safety/reliability concerns: -- Safety/reliability concerns:
--
-- * examines filetypes explicitly -- * examines filetypes explicitly
-- * calls `copyDirRecursive` for directories -- * calls `copyDirRecursive` for directories
easyCopy :: Path Abs easyCopy :: Path Abs
@ -396,6 +404,7 @@ deleteDir p = P.withAbsPath p removeDirectory
-- |Deletes the given directory recursively. -- |Deletes the given directory recursively.
-- --
-- Safety/reliability concerns: -- Safety/reliability concerns:
--
-- * not atomic -- * not atomic
-- * examines filetypes explicitly -- * examines filetypes explicitly
deleteDirRecursive :: Path Abs -> IO () deleteDirRecursive :: Path Abs -> IO ()
@ -417,6 +426,7 @@ deleteDirRecursive p = do
-- a symlink, the symlink file is deleted. -- a symlink, the symlink file is deleted.
-- --
-- Safety/reliability concerns: -- Safety/reliability concerns:
--
-- * examines filetypes explicitly -- * examines filetypes explicitly
-- * calls `deleteDirRecursive` for directories -- * calls `deleteDirRecursive` for directories
easyDelete :: Path Abs -> IO () easyDelete :: Path Abs -> IO ()
@ -465,7 +475,9 @@ 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: - `PermissionDenied` if output directory cannot be written to -- Throws:
--
-- - `PermissionDenied` if output directory cannot be written to
-- - `AlreadyExists` if destination file already exists -- - `AlreadyExists` if destination file already exists
createRegularFile :: Path Abs -> IO () createRegularFile :: Path Abs -> IO ()
createRegularFile dest = createRegularFile dest =
@ -477,7 +489,9 @@ createRegularFile dest =
-- |Create an empty directory at the given directory with the given filename. -- |Create an empty directory at the given directory with the given filename.
-- --
-- Throws: - `PermissionDenied` if output directory cannot be written to -- Throws:
--
-- - `PermissionDenied` if output directory cannot be written to
-- - `AlreadyExists` if destination directory already exists -- - `AlreadyExists` if destination directory already exists
createDir :: Path Abs -> IO () createDir :: Path Abs -> IO ()
createDir dest = createDirectory (P.fromAbs dest) newDirPerms createDir dest = createDirectory (P.fromAbs dest) newDirPerms
@ -493,12 +507,13 @@ createDir dest = createDirectory (P.fromAbs dest) newDirPerms
-- |Rename a given file with the provided filename. Destination and source -- |Rename a given file with the provided filename. Destination and source
-- must be on the same device, otherwise `eXDEV` will be raised. -- must be on the same device, otherwise `eXDEV` will be raised.
-- --
-- Calls `rename`, but does not allow to rename over existing files.
--
-- Safety/reliability concerns: -- Safety/reliability concerns:
--
-- * has a separate set of exception handling, apart from the syscall -- * has a separate set of exception handling, apart from the syscall
-- --
-- Throws: - `NoSuchThing` if source file does not exist -- Throws:
--
-- - `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 driectory cannot be opened -- - `PermissionDenied` if source driectory cannot be opened
-- - `UnsupportedOperation` if source and destination are on different devices -- - `UnsupportedOperation` if source and destination are on different devices
@ -506,7 +521,7 @@ createDir dest = createDirectory (P.fromAbs dest) newDirPerms
-- - `DirDoesExist` if destination directory already exists -- - `DirDoesExist` if destination directory already exists
-- - `SameFile` if destination and source are the same file -- - `SameFile` if destination and source are the same file
-- --
-- Note: calls `rename` -- Note: calls `rename` (but does not allow to rename over existing files)
renameFile :: Path Abs -> Path Abs -> IO () renameFile :: Path Abs -> Path Abs -> IO ()
renameFile fromf tof = do renameFile fromf tof = do
throwSameFile fromf tof throwSameFile fromf tof
@ -519,16 +534,19 @@ renameFile fromf tof = do
-- And also works on directories. -- And also works on directories.
-- --
-- Safety/reliability concerns: -- Safety/reliability concerns:
--
-- * copy-delete fallback is inherently non-atomic -- * copy-delete fallback is inherently non-atomic
-- --
-- Throws: - `NoSuchThing` if source file does not exist -- Throws:
--
-- - `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 driectory cannot be opened -- - `PermissionDenied` if source driectory cannot be opened
-- - `FileDoesExist` if destination file already exists -- - `FileDoesExist` if destination file already exists
-- - `DirDoesExist` if destination directory already exists -- - `DirDoesExist` if destination directory already exists
-- - `SameFile` if destination and source are the same file -- - `SameFile` if destination and source are the same file
-- --
-- Note: calls `rename` -- Note: calls `rename` (but does not allow to rename over existing files)
moveFile :: Path Abs -- ^ file to move moveFile :: Path Abs -- ^ file to move
-> Path Abs -- ^ destination -> Path Abs -- ^ destination
-> IO () -> IO ()