[Issue 18294] std.path.dirName needs better documentation

[d-bugmail at puremagic.com]

https://issues.dlang.org/show_bug.cgi?id=18294

Jonathan M Davis <issues.dlang at jmdavisProg.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |issues.dlang at jmdavisProg.co
                   |                            |m

--- Comment #1 from Jonathan M Davis <issues.dlang at jmdavisProg.com> ---
(In reply to bachmeil from comment #0)
> std.path.dirName has no examples. The documentation is incomplete, because
> the function can yield surprising output.
> 
> std.path.dirName("foo/bar/baz") returns "foo/bar".
> std.path.dirName("foo/bar/baz/") also return "foo/bar", even though "baz/"
> is clearly a directory.
> 
> The only documentation is "Returns the directory part of a path." It should
> be clarified that the end of the path is always assumed to be a file, even
> if it ends with "/".

Actually, that particular result is because dirName gives you the parent
directory, not because it's assuming that the end of the path is a file.
Whether the end of the path is a directory or file or whatever is irrelevant
(and to an extent has to be, because it doesn't check whether the path even
exists, let alone what it points at). But really, the documentation should say
that it gives the parent directory of the argument rather than the "directory
part" of the argument.

--