bug#3888: Some variables get the wrong, platform-specific, documentation

[Stefan Monnier]

> No technical problems, but experience teaches me that these solutions
> don't hold in practice, i.e. new non-internal functions that overload
> others pop up with time.

Yes, clearly, this solution is of the form "let's try and impose this
discipline on ourselves in the future".  But it's not like we usually
shy away from coding conventions.

> Also, the `foo-internal' trick does not solve the problem of the doc
> string that needs to say something platform-specific without bothering
> too much the users of other platforms.

That is a docstring problem that needs to be addressed with good use of
language and judgement.  There's no silver bullet for this one.

> Finally, there's (an admittedly very specific and quite rare) problem
> of ls-lisp and its ilk that overload the default implementation with
> something utterly different, and whose doc string _must_ be very
> different if we want it to be useful.

Yes, but again it's not difficult to find a way to do it right, e.g. by
having a shared function whose docstring hyperlinks to the two possible
implementation alternatives and their respective docstrings.  We've done
it already and can do it again.

> I tried to think of an infrastructure that would solve all these
> use-cases in a relatively elegant way that would not become a
> maintenance burden.

That would be swell, but my proposal is a lot more modest.


        Stefan