Re: convert-standard-filename's doc

[Stefan Monnier]

>> Four years ago, the docstring for convert-standard-filename (in files.el)
>> was changed, but the ones in w32-fns.el and dos-fns.el were not.
>> 
>> Now, it's trivial to fix them to be identical again.

> They don't need to be identical: once a port overloads the standard
> definition with another one, the doc string is replaced as well.

> So we could have a doc string that describes what that function does
> on the specific platform where it runs.  The default doc string
> should be left as it is now, IMHO.

I think the docstring should document what "the function
convert-standard-filename" does, not what the "the function currently
associated with the convert-standard-filename symbol" does.

So I think the "generic" text needs to be in, together with an explanation
of what this specific instance of convert-standard-filename does.

Basically I think that multiple definitions of the same function is
a bad thing.  Maybe using defadvice in dos-fns and w32-fns would be even
worse for various reasons, but I think that the docstrings should do
something similar to what we'd get if we used defadvice.


        Stefan