Bug 18294 – std.path.dirName needs better documentation

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 "/".

(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.

(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.