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

Jump to bottom

Make file operations return the path they created #27071

Merged
merged 6 commits into from
May 18, 2018
Merged

Make file operations return the path they created #27071

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5bc2392
=make creation functions return the path the thing they created
oxinabox May 11, 2018
2005702
=update news.md
oxinabox May 11, 2018
a6c7853
=punctuation
oxinabox May 11, 2018
9464873
Don't change chown or chmod
oxinabox May 11, 2018
c5a5510
=also chown and chmod
oxinabox May 14, 2018
4709cf5
=imperative
oxinabox May 14, 2018
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
4 changes: 4 additions & 0 deletions base/file.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -658,6 +658,7 @@ end
Change the permissions mode of `path` to `mode`. Only integer `mode`s (e.g. `0o777`) are
currently supported. If `recursive=true` and the path is a directory all permissions in
that directory will be recursively changed.
Returns `path`.
Copy link
Sponsor Member

Choose a reason for hiding this comment

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

Returns -> Return I think.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I think Returns, as in "This function returns path"

Overly complicated explanation for why:
It is a sentence incorporating ellipsis. which is short for "This function returns path"
Returns is the verb in 3rd person present tense (I had to look that up).

Copy link
Member

Choose a reason for hiding this comment

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

We usually use imperative form though, from point 2 in the manual (https://docs.julialang.org/en/latest/manual/documentation/):

The one-line sentence should use the imperative form ("Do this", "Return that") instead of the third person (do not write "Returns the length...") when documenting functions.

Copy link
Contributor Author

@oxinabox oxinabox May 14, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

Fair enough, amazing and excellent that the manual is that specific

Copy link
Sponsor Member

Choose a reason for hiding this comment

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

However, from searching a bit in the doc strings, we are very inconsistent regarding this.

Copy link
Contributor

Choose a reason for hiding this comment

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

The imperative mode guideline was introduced in #15136, among several other guidelines, by @nalimilan. However, I can't seem to find discussion of that particular aspect in the PR. Was it discussed elsewhere, e.g. on discourse or slack?

(FWIW, I do agree with @KristofferC that indicative mode sounds more natural, as neither the author nor the reader of the documentation will be the actor performing the returning action... but I may be missing something.)

Copy link
Member

Choose a reason for hiding this comment

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

I don't remember where that rule comes from, but I don't think I invented it. It's a know problem that our docs are inconsistent, and I don't really care about which convention is chosen as long as one exists.

Copy link
Contributor

@waldyrious waldyrious May 14, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

I do know of that convention/recommendation for git commits, but not for function documentation. I do think it makes more sense in the former context than the latter, but don't meant to discuss this here. Should I open an issue for that, or is everyone else ok with the current convention?

Copy link
Member

Choose a reason for hiding this comment

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

Note that the cited rule applies to the one-line sentence in the following sense:

Include a single one-line sentence describing what the function does or what the object represents after the simplified signature block. If needed, provide more details in a second paragraph, after a blank line

So no need to discuss the rule here, because it doesn't apply.

"""
function chmod(path::AbstractString, mode::Integer; recursive::Bool=false)
err = ccall(:jl_fs_chmod, Int32, (Cstring, Cint), path, mode)
Expand All @@ -669,15 +670,18 @@ function chmod(path::AbstractString, mode::Integer; recursive::Bool=false)
end
end
end
path
end

"""
chown(path::AbstractString, owner::Integer, group::Integer=-1)

Change the owner and/or group of `path` to `owner` and/or `group`. If the value entered for `owner` or `group`
is `-1` the corresponding ID will not change. Only integer `owner`s and `group`s are currently supported.
Returns `path`
"""
function chown(path::AbstractString, owner::Integer, group::Integer=-1)
err = ccall(:jl_fs_chown, Int32, (Cstring, Cint, Cint), path, owner, group)
uv_error("chown",err)
path
end
6 changes: 3 additions & 3 deletions test/file.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ end

@test filemode(file) & 0o444 > 0 # readable
@test filemode(file) & 0o222 > 0 # writable
chmod(file, filemode(file) & 0o7555)
@test chmod(file, filemode(file) & 0o7555) == file
@test filemode(file) & 0o222 == 0
chmod(file, filemode(file) | 0o222)
@test filemode(file) & 0o111 == 0
Expand Down Expand Up @@ -171,7 +171,7 @@ if !Sys.iswindows()
chown(file, 0, -2) # Change the file group to nogroup (and owner back to root)
@test stat(file).gid !=0
@test stat(file).uid ==0
chown(file, -1, 0)
@test chown(file, -1, 0) == file
@test stat(file).gid ==0
@test stat(file).uid ==0
else
Expand All @@ -180,7 +180,7 @@ if !Sys.iswindows()
end
else
# test that chown doesn't cause any errors for Windows
@test chown(file, -2, -2) === nothing
@test chown(file, -2, -2) == file
end

##############
Expand Down