clarify docs for std:io::fs::Path::{is_dir,is_file,exists}; add lstat

[aturon]

Clarifies the interaction of is_dir, is_file and exists with
symbolic links. Adds a convenience lstat function alongside of
stat. Removes references to conditions.

Closes issue #12583.

[lilyball]

I'm pretty sure you meant to call lstat(self) here.

[lilyball]

Are there any tests for std::io::fs::stat() and lstat()? If so, could we get some basic coverage for Path::stat() and Path::lstat() as well? The bug I pointed out here (where you called stat() in the implementation of Path::lstat()) is something that I'd rather see caught by tests.

[lilyball]

r=me with my comments addressed and some minimal tests added.

[aturon]

@kballard I've now expanded existing unit tests for stat and lstat to also check the convenience methods.

As a sidenote, the rationale for when functionality should be exposed as a function versus a method (or both) wasn't entirely clear to me. I brought it up on IRC, but discussion was inconclusive -- the main benefit of methods seem to be that you don't need imports to get access to them. In any case, it seems a shame to have (notably, error-prone) boilerplate like these wrapper methods, which then requires redundant testing. But for this patch, I'm sticking with the existing pattern.

[alexcrichton]

fs::lstat

[alexcrichton]

(and below)

[aturon]

@alexcrichton fixed, thanks.

[alexcrichton]

lstat is currently unimplemented on windows, so the tests which are exercising lstat may need some calls to if !cfg!(windows) { ... }

[aturon]

@alexcrichton yep -- I only added method-based lstat tests where there were existing function-based lstat tests, which are all already checking against cfg!(windows).