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

From: Chong Yidong <[email-masked]>
Date: Mon, 20 Jul 2009 16:25:38 -0400

> > I guess this is because term/pc-win.elc is now in SOME_MACHINE_LISP in
> > src/Makefile.in. (It was not there in Emacs 22.)
>
> None of the *-win.elc files was in SOME_MACHINE_LISP in Emacs 22,
> which is why documentation of several important functions and
> variables were not in etc/DOC.  But there were other platform-specific
> files in SOME_MACHINE_LISP: dos-fns.elc, w32-fns.elc, vmsproc.elc,
> etc.  So the problem is not new.
>
> I think this calls for some infrastructure that is currently missing:
> how to define a platform-specific implementation of an API without
> clobbering the doc string for other platforms.  Maybe some markup in
> the doc string that would allow to have platform-specific parts there?

I think, as a temporary solution, we should make the docstrings of all
the affected functions and variables the same.  If necessary, they can
say somehthing like, "On Windows, this does X.  On Nexstep, this does
Y", and so on.