Per Guido's comment about DirEntry documentation on Issue 26032, especially http://bugs.python.org/issue26032#msg257665, it'd be good to improve the docs of the scandir DirEntry methods with regard to symlinks and caching.

Attaching my stab at a documentation fix. Changes here are:

1) Clarify that the return values of is_dir()/is_file()/etc are cached separately for follow_symlinks True and False.
2) Be more specific about when the functions require a system call, and how it relates to caching and follow_symlinks.
3) DRY up common stuff between is_dir and is_file by saying "Caching, system calls made, and exceptions raised are as per is_dir" in is_file.
4) Tweak to the first paragraph of docs for is_dir/is_file to simplify: assume the follow_symlinks=True default, then note the follow_symlinks=False non-default case after.

I think they're all improvements, though I'm not sure about #3. Is it better to just repeat those couple of paragraphs verbatim?

I'm also not 100% sure about mentioning the DT_UNKNOWN thing. But you really can't get more specific about when system calls are required on Unix without mentioning it.

New changeset f2c68cb17e31 by Victor Stinner in branch '3.5':
Enhance os.scandir() doc
https://hg.python.org/cpython/rev/f2c68cb17e31

The change looks good to me. I pushed it to 3.5 & 3.6. It will be online in a few hours at:
https://docs.python.org/dev/library/os.html#os.DirEntry

I keep the issue open a few days to see if some others have other suggestions.

Thanks, Victor!

Seeing this has been merged (thanks Victor), can this issue be closed? Guido, are you happy with the changes given your comments at http://bugs.python.org/issue26032#msg257665?

Ben Hoyt added the comment:
> Seeing this has been merged (thanks Victor), can this issue be closed?

As I wrote, I left the issue open for wait for feedback. I know that
some people to read the doc online:
https://docs.python.org/dev/library/os.html#os.DirEntry

Thanks very much for all that added information!