bug#21225: 25.0.50; doc strings of `define-obsolete-*'

bug#21225: 25.0.50; doc strings of `define-obsolete-*'

[Drew Adams]

Argument WHEN is not described at all for some of these macros.  For
others it is described incorrectly or only via an example.  It needs to
be described clearly.

The correct description is, in all cases, what is said in the Elisp
manual for `make-obsolete':

   If provided, WHEN should be a string indicating when the function
   was first made obsolete=81\for example, a date or a release number.

(with "function" replaced by "face" or "variable", as appropriate),
except that "version number" is preferable to "release number".

These macros are used by users and 3rd-party libraries too, not just by
core Emacs development, and in such contexts "release" is not
necessarily appropriate.  The most important remark, however, is that "a
date" should be offered as an example of a WHEN value, in addition to "a
version number".

The same change should be made for the Elisp manual, node `Variable
Aliases'.  It is better to say "for example, a date or a version number"
than just "(usually a version number string)".

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-07-03 on LEG570
Repository revision: 2b848fadd51e805b2f46da64c5958ea7f009048a
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=3Di686-pc-mingw32 --enable-checking=3Dyes,glyphs'

bug#21225: 25.0.50; doc strings of `define-obsolete-*'

[Drew Adams]

I forgot to add:

The doc (doc strings and manual) should make clear that the args
are evaluated.  This is not obvious, as these are macros.

For example, this is needed:

(define-obsolete-variable-alias 'last-input-char 'last-input-event
  "at least 19.34")

This is no good:

(define-obsolete-variable-alias last-input-char last-input-event
  "at least 19.34")

The current doc is quite unclear about this, especially by just
referring to the args as "*-NAME".  (Nothing wrong with those
parameter names, as long as you make clear that the args are
evaluated.)

bug#21225: 25.0.50; doc strings of `define-obsolete-*'

[Artur Malabarba]

> The doc (doc strings and manual) should make clear that the args
> are evaluated.  This is not obvious, as these are macros.

Yes please. Everytime I use these I have to manually check their
behavior because I'm never sure just by reading the docstring.

bug#21225: 25.0.50; doc strings of `define-obsolete-*'

[Stefan Monnier]

>> The doc (doc strings and manual) should make clear that the args
>> are evaluated.  This is not obvious, as these are macros.
> Yes please. Everytime I use these I have to manually check their
> behavior because I'm never sure just by reading the docstring.

Maybe a better fix is to turn them into functions (which basically
means, to add special support for them in the byte-compiler, since
that's the only reason they're defined as macros, AFAIK).


        Stefan

bug#21225: 25.0.50; doc strings of `define-obsolete-*'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> Argument WHEN is not described at all for some of these macros.  For
> others it is described incorrectly or only via an example.  It needs to
> be described clearly.
>
> The correct description is, in all cases, what is said in the Elisp
> manual for `make-obsolete':
>
>    If provided, WHEN should be a string indicating when the function
>    was first made obsolete=81\for example, a date or a release number.
>
> (with "function" replaced by "face" or "variable", as appropriate),
> except that "version number" is preferable to "release number".

I've now done so.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no