bug#14734: 24.3.50; REGRESSION: defadvice broken wrt doc strings (C-h f)

[Drew Adams]

> > If you don't want to see the internal thingy, then use the new
> > advice-add rather than the old defadvice.

So you introduce a regression in user-visible behavior that
degrades the user interface, with the idea that that will
encourage use of your new advice replacement over traditional
defadvice?  Is that it?

Using traditional advice to add to a doc string has always worked
seamlessly: a user saw a single display of help text that included
both the original doc and any doc added by advice, seamlessly.

The change introduced is horrible for users.  Now they see only
the original doc string, plus a link that will be incomprehensible
to many (so skipped over by them):

  :around advice: `ad-Advice-isearch-forward'

And if they do happen to click that uninviting link then they
get an even more incomprehensible page of internal,
advice-oriented code and unintelligible text:

  ad-Advice-isearch-forward is a Lisp function.

  (ad-Advice-isearch-forward AD--ADDOIT-FUNCTION &optional REGEXP-P
  NO-RECURSIVE-EDIT)

  Advice function assembled by advice.el.

  Before-advice `isearch+-doc':
   
  Isearch Plus
  ============
  ...

What they should see for `C-h f isearch-forward', and what they have
always seen in the past, is the original `isearch-forward' doc together
with the added doc from advising - it is just appended:

  Isearch Plus
  ============
  ...

Emacs did that by design.  You have broken that.

Not only can Emacs do better, it always HAS.  This is a real step
backward for users.  Intentional or not.  I'm reopening the bug.
I hope you will seriously consider reverting the misguided changes
that introduced this regression.