Make file operations return the path they created

[oxinabox]

This makes:

• mv
• touch
• cp
• mkdir
• mkpath
• chown
• chmod

return the path they created/modified, rather than nothing.

It isn't a big change,
but it means you can do things like:

logfile = joinpath(mkpath(string(now())), "logfile.txt")

rather than

logdir =string(now())
mkpath(logdir)
logfile = joinpath(logdirs, "logfile.txt")

[oxinabox]

CI errors are because I changed chown and chmod.
Which I thought better of, then forgot to revert.
And for some reason chown has a test that asserts it outputs nothing

[oxinabox]

AppVeyor failure is just it being a bit flacky AFAICT

[JeffBezanson]

+1. Always good to return a value if there's any possible useful value to return.

[JeffBezanson]

Maybe chmod and chown should return the path too?

[oxinabox]

done

[KristofferC]

Returns -> Return I think.

[oxinabox]

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

[fredrikekre]

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.

[oxinabox]

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

[KristofferC]

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

[waldyrious]

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

[nalimilan]

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.

[waldyrious]

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?

[martinholters]

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.

[oxinabox]

Should rm also return the path that was deleted?
I feel like returning a path to something that no longer exists isn't vary useful.

More useful behavours for rm's return, eg it could return true if something was actually removed,
and false if it was called with force=true and nothing was deleted.
But that would be a different PR

[oxinabox]

AppVeyor is, afaict failing to get correct status.
It got jammed and @fredrikekre restarted it.

The restarted results are: https://ci.appveyor.com/project/JuliaLang/julia/build/1.0.26765
Which also reads as a failure,
but looking at the results it is fine: https://ci.appveyor.com/project/JuliaLang/julia/build/1.0.26765/job/3x8dn282hs4f2pn2#L3038

It finished all tests and they passed, but then it timed out before it could finish the job