bug#16491: 24.3.50; ?REGRESSION: `defadvice' doc removed from Elisp manual

[Alan Mackenzie]

Drew Adams <drew.adams@oracle.com> wrote:
> Elisp manual node `Advising Emacs Lisp Functions' has been rewritten to
> include the new `add-function' stuff.  It is fine to document that new
> feature.

> What's not fine is to simply remove all of the doc about the traditional
> `defadvice' advice system.  Even if that feature is to be deprecated,
> its doc should remain until it is desupported.  If this removal is not
> a temporary oversight (mistake) then it is quite misguided.  It hurts
> Emacs users.

+1.  defadvice will remain absolutely necessary for Emacs hackers
maintaining packages with the exception of those who are only targetting
recent GNU Emacsen.

> The Elisp manual should continue to be usable to help users code
> `defadvice' advice, in addition to `add-function' advice.  As one use
> case, some users will use Emacs 24.4 to write or maintain code for
> older or multiple Emacs versions.

Not a few users, either.  Without documentation, defadvice is unusable and
packages using it are unmaintainable.  The doc string of defadvice, by
itself, is inadequate; for example, it doesn't say anything about ad-do-it.

Besides, there are 34 files in .../lisp containing the string "defadvice".
This feature is clearly widely used, even in the Emacs sources.

> Normally there is a reasonably long transition period before a feature,
> especially a major feature such as `defadvice', is desupported.  And
> until desupport, the deprecated feature remains SUPPORTED - in
> particular, by continuing to provide users with its reference doc.

-- 
Alan Mackenzie (Nuremberg, Germany).