Path/File.isFile documentation on path not existing is missleading

[ScallyGames]

Path/File.isFile according to the documentation: Returns true if the path exists on disk and is pointing at a regular file. Any error will return false.

Reproduction:

Run Path/File.isFile on a path that does not exist.

Expected Behavior:

I'd expect it to trigger a file not found error but then according to the documentation on any error it should return false, not an error.

Actual Behavior:

Returns PathErr PathDoesNotExist (this is somewhat consistent with the signature PathErr MetadataErr but MetadataErr does not sound as if it would include FileNotFound.

Discussion

I don't know if the behavior or the documentation should be changed but as is I find it very missleading.
Looking at the source code I don't think there is ANY error that would actually produce a result of false.
https://github.com/roc-lang/basic-cli/blob/main/platform/Path.roc#L437 sort of makes it look like it would always return Ok but in actuality Path.type will raise an error (probably in https://github.com/roc-lang/basic-cli/blob/main/platform/Path.roc#L454) which will then have Path.isFile exit early.

[Anton-4]

Thanks for this nice issue report @ScallyGames!

MetadataErr does not sound as if it would include FileNotFound.

Yes, I agree, the name MetadataErr was chosen because this represents errors that happen when trying to get the metadata of a path. Feel free to suggest a better name :)

Looking at the source code I don't think there is ANY error that would actually produce a result of false.

Yes, that is correct.

For isFile what do you think of replacing "Any error will return false." with "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"?