bug#65270: 30.0.50; `describe-function' issue with some methods

bug#65270: 30.0.50; `describe-function' issue with some methods

[David Ponce]

Hello,

It seems there is an issue with `describe-function' of a method that
calls `cl-call-next-method'.  For a such method `describe-function' says
that the method is "Undocumented" even if a doc string is present.

Also the mentioned signature is weird.  See an illustration below using
a simple recipe, running 'emacs -Q'.

Thanks!

<1> In scratch buffer eval:
===========================
*scratch*
------------------------------------------------------------------
(cl-defgeneric foo (arg)
   "Generic foo receiving any ARG."
   (format "%S" arg))
foo

(cl-defmethod foo ((arg atom))
   "Specialized foo receiving any atoms."
   (format "atom %s" (cl-call-next-method)))
foo

(cl-defmethod foo ((arg string))
   "Specialized foo receiving strings."
   (format "string %S" arg))
foo

;; Check results are correct
(foo 1)
"atom 1"
(foo '(1))
"(1)"
(foo "1")
"string \"1\""
------------------------------------------------------------------

<2> M-x describe-function RET foo RET
=====================================
*Help* (is not correct for the method using `cl-call-next-method')
------------------------------------------------------------------
foo is a byte-compiled Lisp function.

(foo ARG)

Generic foo receiving any ARG.

   Probably introduced at or before Emacs version 1.2.


This is a generic function.

Implementations:

(foo (ARG string))
Specialized foo receiving strings.

(foo (ARG0 atom) &rest CL--ARGS) <<<<<<<<<<<<< Incorrect
Undocumented

(foo ARG)
Undocumented
------------------------------------------------------------------


<3> In scratch buffer eval:
===========================
*scratch*
------------------------------------------------------------------
;; Redefine method without calling `cl-call-next-method'
(cl-defmethod foo ((arg atom))
   "Specialized foo receiving any atoms."
   (format "atom %S" arg))
foo

;; Check results are correct
(foo 1)
"atom 1"
(foo '(1))
"(1)"
(foo "1")
"string \"1\""
------------------------------------------------------------------

<4> M-x describe-function RET foo RET
=====================================
*Help* (is correct)
------------------------------------------------------------------
foo is a byte-compiled Lisp function.

(foo ARG)

Generic foo receiving any ARG.

   Probably introduced at or before Emacs version 1.2.


This is a generic function.

Implementations:

(foo (ARG string))
Specialized foo receiving strings.

(foo (ARG atom)) <<<<<<<<<<<<< Correct
Specialized foo receiving any atoms.

(foo ARG)
Undocumented
------------------------------------------------------------------

In GNU Emacs 30.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version
  3.24.38, cairo version 1.17.8) of 2023-08-13
Repository revision: de6c1c4d5c92b92d5b280e157c2a5bc3228749f2
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12014000
System Description: Fedora Linux 38 (KDE Plasma)

Configured using:
  'configure --with-x-toolkit=gtk3
  --with-native-compilation=no'

Configured features:
ACL CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GSETTINGS HARFBUZZ JPEG JSON
LCMS2 LIBOTF LIBSELINUX LIBSYSTEMD LIBXML2 M17N_FLT MODULES NOTIFY
INOTIFY PDUMPER PNG RSVG SECCOMP SOUND SQLITE3 THREADS TIFF
TOOLKIT_SCROLL_BARS TREE_SITTER WEBP X11 XDBE XIM XINPUT2 XPM GTK3 ZLIB

Important settings:
   value of $LC_TIME: fr_FR.utf8
   value of $LANG: fr_FR.UTF-8
   locale-coding-system: utf-8-unix

bug#65270: 30.0.50; `describe-function' issue with some methods

[David Ponce]

[-- Attachment #1: Type: text/plain, Size: 722 bytes --]

On 13/08/2023 12:36, David Ponce wrote:
> Hello,
> 
> It seems there is an issue with `describe-function' of a method that
> calls `cl-call-next-method'.  For a such method `describe-function' says
> that the method is "Undocumented" even if a doc string is present.
> 
> Also the mentioned signature is weird.  See an illustration below using
> a simple recipe, running 'emacs -Q'.
> 
[...]

Hello,

The attached patch fixed for me the doc string issue with `describe-function'
for methods calling `cl-call-next-method'.

It would be nice if someone who better knows the cl-generic library will
double check it (CC Stefan, the author).

Unfortunately, I didn't find a solution for arguments.

Hope it will help.

Thanks

[-- Attachment #2: cl-generic-docstring-1.patch --]
[-- Type: text/x-patch, Size: 2189 bytes --]

diff --git a/lisp/emacs-lisp/cl-generic.el b/lisp/emacs-lisp/cl-generic.el
index b062c280a41..722211d6ba8 100644
--- a/lisp/emacs-lisp/cl-generic.el
+++ b/lisp/emacs-lisp/cl-generic.el
@@ -429,6 +429,15 @@ cl-generic-define-context-rewriter
             (lexical-binding
              (cons 'curried
                    `#'(lambda (,nm) ;Called when constructing the effective method.
+                        ,@(let* ((prebody (car parsed-body))
+                                 (ds (if (stringp (car prebody))
+                                         prebody
+                                       (setq prebody (cons nil prebody))))
+                                 (usage (help-split-fundoc (car ds) nil)))
+                            (unless usage
+                              (setcar ds (help-add-fundoc-usage (car ds)
+                                                                args)))
+                            prebody)
                         (let ((,nmp (if (cl--generic-isnot-nnm-p ,nm)
                                         #'always #'ignore)))
                           ;; This `(λ (&rest x) .. (apply (λ (args) ..) x))'
@@ -446,15 +455,6 @@ cl-generic-define-context-rewriter
                           ;; is always called directly and there are no
                           ;; `&optional' args.
                           (lambda (&rest ,arglist)
-                            ,@(let* ((prebody (car parsed-body))
-                                     (ds (if (stringp (car prebody))
-                                             prebody
-                                           (setq prebody (cons nil prebody))))
-                                     (usage (help-split-fundoc (car ds) nil)))
-                                (unless usage
-                                  (setcar ds (help-add-fundoc-usage (car ds)
-                                                                    args)))
-                                prebody)
                             (let ((,cnm (lambda (&rest args)
                                           (apply ,nm (or args ,arglist)))))
                               ;; This `apply+lambda' basically parses

bug#65270: 30.0.50; `describe-function' issue with some methods

[David Ponce]

On 14/08/2023 12:41, David Ponce wrote:
> On 13/08/2023 12:36, David Ponce wrote:
>> Hello,
>>
>> It seems there is an issue with `describe-function' of a method that
>> calls `cl-call-next-method'.  For a such method `describe-function' says
>> that the method is "Undocumented" even if a doc string is present.
>>
>> Also the mentioned signature is weird.  See an illustration below using
>> a simple recipe, running 'emacs -Q'.
>>
> [...]
> 
> Hello,
> 
> The attached patch fixed for me the doc string issue with `describe-function'
> for methods calling `cl-call-next-method'.
> 
> It would be nice if someone who better knows the cl-generic library will
> double check it (CC Stefan, the author).
> 
> Unfortunately, I didn't find a solution for arguments.
> 
> Hope it will help.
> 
> Thanks

Please forget my previous patch, it doesn't fix the issue in all cases.
Hopefully someone will find the proper fix.

Thanks
  

bug#65270: 30.0.50; `describe-function' issue with some methods

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> It seems there is an issue with `describe-function' of a method that
> calls `cl-call-next-method'.  For a such method `describe-function' says
> that the method is "Undocumented" even if a doc string is present.

I pushed a patch to `master` which seems to fix this problem.

> Also the mentioned signature is weird.  See an illustration below using
> a simple recipe, running 'emacs -Q'.

I think we still have a problem here when the method is not
byte-compiled, but I think the problem is in `help-function-arglist`
which decides to use the "raw arglist" from the interpreted closure
without looking at the arg names stashed in the docstring.


        Stefan

bug#65270: 30.0.50; `describe-function' issue with some methods

[David Ponce]

On 15/08/2023 04:40, Stefan Monnier wrote:
>> It seems there is an issue with `describe-function' of a method that
>> calls `cl-call-next-method'.  For a such method `describe-function' says
>> that the method is "Undocumented" even if a doc string is present.
> 
> I pushed a patch to `master` which seems to fix this problem.
> 
>> Also the mentioned signature is weird.  See an illustration below using
>> a simple recipe, running 'emacs -Q'.
> 
> I think we still have a problem here when the method is not
> byte-compiled, but I think the problem is in `help-function-arglist`
> which decides to use the "raw arglist" from the interpreted closure
> without looking at the arg names stashed in the docstring.
> 
> 
>          Stefan
> 

Hello Stefan,

I confirm that your patch fixed the issue with doc string, and with
arglist of byte-compiled methods (which is probably the common case).

Thank you very much!

bug#65270: 30.0.50; `describe-function' issue with some methods

[Stefan Kangas]

Version: 30.1

David Ponce <da_vid@orange.fr> writes:

> On 15/08/2023 04:40, Stefan Monnier wrote:
>>> It seems there is an issue with `describe-function' of a method that
>>> calls `cl-call-next-method'.  For a such method `describe-function' says
>>> that the method is "Undocumented" even if a doc string is present.
>> I pushed a patch to `master` which seems to fix this problem.
>>
>>> Also the mentioned signature is weird.  See an illustration below using
>>> a simple recipe, running 'emacs -Q'.
>> I think we still have a problem here when the method is not
>> byte-compiled, but I think the problem is in `help-function-arglist`
>> which decides to use the "raw arglist" from the interpreted closure
>> without looking at the arg names stashed in the docstring.
>>          Stefan
>>
>
> Hello Stefan,
>
> I confirm that your patch fixed the issue with doc string, and with
> arglist of byte-compiled methods (which is probably the common case).
>
> Thank you very much!

It seems like this issue was fixed, but it was left open in the bug
tracker.  I'm therefore closing it now.