bug#18318: 24.4.50; doc of `file-readable-p'

[Drew Adams <drew.adams@oracle.com>]

> > The doc - both Elisp manual and doc string, should explicitly point out
> > that this returns non-nil for a directory, IOW, a non-nil value does not
> > mean that the file can be, say, inserted into a buffer.
> >
> > In addition, it would be better to change the parameter name to
> > FILE-OR-DIR (or even FILE-OR-DIR-NAME).  It is all to easy to not
> > realize, when reading this, that this does not test for a non-directory
> > file that is readable.
> 
> Well, the function isn't about files or directories, but filenames.  It
> can be a fifo, a device node, etc.

All the more reason to make the doc clearer.  The argument
passed to the function is not necessarily the name of a file
whose contents can, say, be inserted into a buffer.  It is
not a FILENAME, unless you understand "filename" in the wider
sense you elaborated - elaboration that is missing from this doc.

It is (I think) far more common for a file or directory name
(string) to be passed as an argument than it is for a FIFO,
device node, etc. to be passed.  The directory case is common,
and the doc misleads.  If you want to mention other
possibilities, besides file and dir names, so much the better.
But ideal should not be the enemy of better.

> So I think the doc is fine as it is.

Disagree.