Thread overview
[Issue 18294] std.path.dirName needs better documentation
Jan 25, 2018
Jonathan M Davis
Jan 26, 2018
bachmeil@yahoo.com
Dec 21
berni44
January 25, 2018
https://issues.dlang.org/show_bug.cgi?id=18294

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

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

--- Comment #1 from Jonathan M Davis <issues.dlang@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.

--
January 26, 2018
https://issues.dlang.org/show_bug.cgi?id=18294

--- Comment #2 from bachmeil@yahoo.com ---
(In reply to Jonathan M Davis from comment #1)
> (In reply to bachmeil from comment #0)
> 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.

Because this is such an easy fix, I submitted a PR to fix it.

https://github.com/dlang/phobos/pull/6075

I only changed "Returns the directory part of a path" to "Returns the parent directory of path." I did not add an example because I that might lead to discussion.

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

berni44 <bugzilla@d-ecke.de> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
                 CC|                            |bugzilla@d-ecke.de
         Resolution|---                         |FIXED

--