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

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'
 

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

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

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

I've removed " non-nil" so that the documentation says what it does.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

[Drew Adams]

> I've removed " non-nil" so that the documentation says what it does.

No, that's not it.  Please reread the bug report.  It is important to
say what the behavior is for a value of nil.  Thx.

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

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

>> I've removed " non-nil" so that the documentation says what it does.
>
> No, that's not it.  Please reread the bug report.  It is important to
> say what the behavior is for a value of nil.  Thx.

Yeah, it's still vaguely unclear.  Fixed on trunk.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/