bug#11571: 24.0.97; doc string of `dired-get-subdir-min'

[Drew Adams]

> > Actually, the real bug is that `dired-get-subdir-min' has no doc
> > string, so the doc string of `cdr' is used in its stead.  The
> > whole point of defining and using a separate function for this,
> > instead of just coding with `cdr', is to enable readers of the
> > code - and a fortiori the doc - to think in terms of the data
> > structure of directories and not just abstract cons cells.  There
> > should be doc at the proper level of abstraction here.
> 
> Help says:
> 
> ---
> dired-get-subdir-min is an alias for `cdr' in `dired.el'.
> (dired-get-subdir-min LIST)
> Return the cdr of LIST.  If arg is nil, return nil.
> Error if arg is not nil and not a cons cell.  See also `cdr-safe'.
> ---
> 
> I think that's fine.

No, it is not fine.  That doc is 100% unrelated to "dired",
"getting" something, "subdir", and "minimum".

If it were fine, then it would be even finer to get rid of this
function, with its supposedly descriptive name, and use just cdr.

If that is the fix you make, fine with me.  If you keep the
function then users deserve its doc to explain what it is about.
Clearly, it is not just "about" returning the cdr.  The function
is named, presumably, to suggest what it is for: its purpose or
behavior WRT DIRED AND SUBDIRS.

Hard to believe that when someone goes to the trouble of
spelling out in the bug report why better doc is needed here
you cannot read and understand that.

> However:
> 
> ;; can't use macro,  must be redefinable for other alist format in
> dired-nstd.
> (defalias 'dired-get-subdir-min 'cdr)
> 
> Which is kinda er.
> 
> I don't know what nstd is, and the function doesn't seem to be
> redefined anywhere, so is this just legacy gunk?  Should
> `dired-get-subdir-min' just be replaced by `cdr' in all the
> calling sites?

Yes, that can be the first question, if you want to get into it.
If you do not want to file a separate (code) bug for that, fine.
But if this function is kept then please document it properly.