GNU bug report logs - #3888
Some variables get the wrong, platform-specific, documentation

Previous Next

Full log

Message #13 received at 3888 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Glenn Morris <rgm <at> gnu.org>, 3888 <at> debbugs.gnu.org
Subject: Re: bug#3888: Some variables get the wrong, platform-specific,	documentation
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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.