Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: path functions ignore trailing slashes #12181

Closed
wants to merge 4 commits into from
Closed

doc: path functions ignore trailing slashes #12181

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
96f2a34
doc: path functions ignore trailing slashes
tniessen Apr 3, 2017
abb4b82
Remove POSIX reference and add note about Windows
tniessen Apr 3, 2017
879ef35
Clarify differences between Windows and POSIX
tniessen Apr 5, 2017
3118594
Simplify sentence
tniessen Apr 5, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions doc/api/path.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,8 @@ changes:
* Returns: {string}

The `path.basename()` methods returns the last portion of a `path`, similar to
the Unix `basename` command.
the Unix `basename` command. Trailing `/` (and `\\` on Windows) characters are
ignored.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the wording is too subtle, its not clear enough that windows supports two dir seps, and will strip both. I would say "Trailing / characters are ignore, and on Windows trailing / and \ characters are both ignored". Or perhaps "trailing directory seperators are ignored, see REF", and explain that unix has only one directory seperator, /, but that win32 supports both / and \ (or a mixture of the two) as directory seps.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about moving the paragraph

Note: On Windows, both the forward slash (/) and backward slash (\\) characters are accepted as path delimiters; however, only the backward slash (\\) will be used in return values.

from the very bottom to the section about path.sep and referencing that section: "Trailing directory separators are ignored, see [path.sep][]"?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok. but "used in return values" means what?

> path.win32.dirname('\foo/that/bar\\//\\//')
'\foo/that'

^--- clearly / and \ are both used in return values

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is preexisting (I copied that paragraph from path.md about path.win32). Is it to be considered a bug in dirname or is it a documentation inaccuracy?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like a doc inaccuracy to me.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just noticed that "path delimiters" is not the best wording as well, considering how path.delimiter is defined. How about

Note: On Windows, both the forward slash (/) and backward slash (\) are accepted as path segment separators; however, if separators are to be added by the Windows-specific implementations of the path methods, only the backward slash (\) will be used.


For example:

Expand Down Expand Up @@ -128,7 +129,8 @@ changes:
* Returns: {string}

The `path.dirname()` method returns the directory name of a `path`, similar to
the Unix `dirname` command.
the Unix `dirname` command. Trailing `/` (and `\\` on Windows) characters are
ignored.

For example:

Expand Down Expand Up @@ -347,7 +349,8 @@ added: v0.11.15
* Returns: {Object}

The `path.parse()` method returns an object whose properties represent
significant elements of the `path`.
significant elements of the `path`. Trailing `/` (and `\\` on Windows)
characters are ignored.

The returned object will have the following properties:

Expand Down