bug#66032: [PATCH] Inline advice documentation into advised function's docstring, after all

[Jens Schmidt]

[Sorry if this is resent - thought I sent it yesterday already.]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> [...]

Thanks for your comments again, I'll consider them.

>> Do you think this docstring generation should be covered by ERT tests?
>
> ERT tests are always welcome,

I have been trying to understand these quirks and previous bugs of
functions `advice--make-single-doc' and `advice--make-docstring' better,
also to probably provide some ERT tests, and would like to focus on one
issue I came across.  Namely, it seems that your work-around:

  ;; Hack attack!  For advices installed before calling
  ;; Snarf-documentation, the integer offset into the DOC file will not
  ;; be installed in the "core unadvised function" but in the advice
  ;; object instead!  So here we try to undo the damage.
  (when (integerp (aref flist 4))
    (setq docfun flist))

is no longer efficient.  When I modify uniquifiy.el as follows in emacs
master:

diff --git a/lisp/uniquify.el b/lisp/uniquify.el
index 2ad2fb0eeac..e43d61a3be6 100644
--- a/lisp/uniquify.el
+++ b/lisp/uniquify.el
@@ -489,7 +489,7 @@ uniquify-kill-buffer-function
 ;; rename-buffer and create-file-buffer.  (Setting find-file-hook isn't
 ;; sufficient.)

-;; (advice-add 'rename-buffer :around #'uniquify--rename-buffer-advice)
+(advice-add 'rename-buffer :before #'ignore)
 (defun uniquify--rename-buffer-advice (newname &optional unique)
   ;; BEWARE: This is called directly from `buffer.c'!
   "Uniquify buffer names with parts of directory name."

and remake emacs, I do not get the doc string for `rename-buffer' in
that Emacs.  Furthermore, if I execute

  (Snarf-documentation "DOC")

I get a message

  Docstring slot busy for rename-buffer

which makes me think that function store_function_docstring now knows
better than simply overwriting the COMPILED_DOC_STRING slot.  Most
likely because of this test:

  /* Don't overwrite a non-docstring value placed there,
   * such as the symbols used for Oclosures.  */
  && VALID_DOCSTRING_P (AREF (fun, COMPILED_DOC_STRING))

What do you think?  Strictly speaking, this is not even a bug since
Emacs does not seem to use pre-dump advices.