improve docs #266

Author: Anton-4

platform/File.roc

@@ -153,7 +153,9 @@ readUtf8 = \path ->
 #    Path.read (Path.fromStr path) fmt
 
 ## Returns true if the path exists on disk and is pointing at a directory.
-## Any error will return false.
+## Returns `Task.ok false` if the path exists and it is not a directory. If the path does not exist,
+## this function will return `Task.err PathErr PathDoesNotExist`.
+##
 ## This uses [rust's std::path::is_dir](https://doc.rust-lang.org/std/path/struct.Path.html#method.is_dir).
 ##
 ## > [Path.isDir] does the same thing, except it takes a [Path] instead of a [Str].
@@ -162,7 +164,9 @@ isDir = \path ->
     Path.isDir (Path.fromStr path)
 
 ## Returns true if the path exists on disk and is pointing at a regular file.
-## Any error will return false.
+## Returns `Task.ok false` if the path exists and it is not a file. If the path does not exist,
+## this function will return `Task.err PathErr PathDoesNotExist`.
+##
 ## This uses [rust's std::path::is_file](https://doc.rust-lang.org/std/path/struct.Path.html#method.is_file).
 ##
 ## > [Path.isFile] does the same thing, except it takes a [Path] instead of a [Str].
@@ -171,7 +175,9 @@ isFile = \path ->
     Path.isFile (Path.fromStr path)
 
 ## Returns true if the path exists on disk and is pointing at a symbolic link.
-## Any error will return false.
+## Returns `Task.ok false` if the path exists and it is not a symbolic link. If the path does not exist,
+## this function will return `Task.err PathErr PathDoesNotExist`.
+##
 ## This uses [rust's std::path::is_symlink](https://doc.rust-lang.org/std/path/struct.Path.html#method.is_symlink).
 ##
 ## > [Path.isSymLink] does the same thing, except it takes a [Path] instead of a [Str].

platform/Path.roc

@@ -418,7 +418,10 @@ display = \path ->
 # Path.isDir, etc.
 
 ## Returns true if the path exists on disk and is pointing at a directory.
-## Any error will return false.
+## Returns `Task.ok false` if the path exists and it is not a directory. If the path does not exist,
+## this function will return `Task.err PathErr PathDoesNotExist`.
+##
+## This uses [rust's std::path::is_dir](https://doc.rust-lang.org/std/path/struct.Path.html#method.is_dir).
 ##
 ## > [`File.isDir`](File#isDir) does the same thing, except it takes a [Str] instead of a [Path].
 isDir : Path -> Task Bool [PathErr MetadataErr]
@@ -427,7 +430,9 @@ isDir = \path ->
     Task.ok (res == IsDir)
 
 ## Returns true if the path exists on disk and is pointing at a regular file.
-## Any error will return false.
+## Returns `Task.ok false` if the path exists and it is not a file. If the path does not exist,
+## this function will return `Task.err PathErr PathDoesNotExist`.
+##
 ## This uses [rust's std::path::is_file](https://doc.rust-lang.org/std/path/struct.Path.html#method.is_file).
 ##
 ## > [`File.isFile`](File#isFile) does the same thing, except it takes a [Str] instead of a [Path].
@@ -437,7 +442,10 @@ isFile = \path ->
     Task.ok (res == IsFile)
 
 ## Returns true if the path exists on disk and is pointing at a symbolic link.
-## Any error will return false.
+## Returns `Task.ok false` if the path exists and it is not a symbolic link. If the path does not exist,
+## this function will return `Task.err PathErr PathDoesNotExist`.
+##
+## This uses [rust's std::path::is_symlink](https://doc.rust-lang.org/std/path/struct.Path.html#method.is_symlink).
 ##
 ## > [`File.isSymLink`](File#isSymLink) does the same thing, except it takes a [Str] instead of a [Path].
 isSymLink : Path -> Task Bool [PathErr MetadataErr]