bug#11534: 24.0.97; `dired-get-marked-files' does not behave as documented

[Drew Adams]

emacs -Q
 
Put point on any file line.
 
M-: (dired-get-marked-files)
 
It returns the name of that line's file.
 
But the doc string says this about argument ARG, which is nil in this
case:
 
Optional second argument ARG, if non-nil, specifies files near
 point instead of marked files.  It usually comes from the prefix
 argument.
  If ARG is an integer, use the next ARG files.
  Any other non-nil value means to use the current file instead.
 
It does not explicitly say anything about what happens when ARG is nil
(and no files are marked).  But a reader could reasonably assume that
none of what happens when ARG is non-nil would happen.
 
In particular, this line:
 
  Any other non-nil value means to use the current file instead.
 
gives the impression that the current file will not be used if ARG is
nil.  Otherwise, it makes little sense to say "any non-nil value" and to
put this sentence under the guard of "Optional second argument ARG, if
non-nil...".
 
Should the behavior be as is documented, which would reasonably mean
that no file name is returned (nil is returned)?  Or should the doc
string be corrected to reflect the actual behavior, i.e., the fact that
ARG = nil means return only the current file name when none are marked?
 
In GNU Emacs 24.0.97.1 (i386-mingw-nt5.1.2600)
 of 2012-05-16 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --enable-checking --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include'