Subject: bug#12884: closed (Re: bug#12884: 24.2.50; defun*: argument lists in documentation look terrible)

From: [email-masked] (GNU bug Tracking System)
Date: Thu, 15 Nov 2012 01:29:03 +0000

Your bug report

#12884: 24.2.50; defun*: argument lists in documentation look terrible

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
12884: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=12884
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#12884: 24.2.50; defun*: argument lists in documentation look terrible
From: Stefan Monnier <[email-masked]>
To: Michael Heerdegen <[email-masked]>
Cc: [email-masked]
Date: Wed, 14 Nov 2012 20:28:07 -0500
List-Id: <debbugs-submit.debbugs.gnu.org>

>> > This looks terrible with all this #: and quote \, stuff.
>> Binding print-quoted makes sense to improve the quote/backquote syntax.
>> But I don't understand why we have those #: in there.  I understand it's
>> there to say the symbols are not interned, but I don't understand why
>> they're not interned.
> See `cl--make-usage-args'.  It upcases the names of the arguments and
> makes them a symbol again.  The one who wrote that wanted that no new
> symbols are interned, and so used `make-symbol'.  Dunno if there's a
> reason to do so.

Ah, yes of course.
I installed a patch similar to yours, except I didn't touch print-length
and print-level, since I can't think of a good reason to favor nil
for them.

        Stefan

Subject: 24.2.50; defun*: argument lists in documentation look terrible
From: Michael Heerdegen <[email-masked]>
To: [email-masked]
Date: Wed, 14 Nov 2012 17:47:20 +0100
List-Id: <debbugs-submit.debbugs.gnu.org>

If I e.g. define something like that:

(defun* my-toggle-item (mode-or-var
                               &key
                               ((:selected enabled-spec) `(am-bound-and-true-p ',mode-or-var))
                               ((:help     help-string)   (am-make-symbol-docstring mode-or-var)))
  "Toggle item creater for modes and flags."
  ...)

the docstring then looks like that for me:

| my-toggle-item is a Lisp function.
| 
| (my-toggle-item #:MODE-OR-VAR &key ((:selected #:ENABLED-SPEC) (\`
| (am-bound-and-true-p (quote (\, mode-or-var))))) ((:help
| #:HELP-STRING) (am-make-symbol-docstring mode-or-var)))
| 
| Toggle item creater for modes and flags.

This looks terrible with all this #: and quote \, stuff.

The culprit is `cl--transform-lambda', which just uses this:

(format "%S"
        (cons 'fn
              (cl--make-usage-args orig-args)))

I think we can easily improve this, e.g. by using something like

(let (print-gensym print-level print-length (print-quoted t))
  (format "%S"
     (cons 'fn (cl--make-usage-args orig-args))))

instead.  Looks much better in *Help* and with eldoc.

Thanks,

Michael.

In GNU Emacs 24.2.50.1 (x86_64-unknown-linux-gnu, GTK+ Version 2.24.10)
 of 2012-11-13 on drachen
Bzr revision: [email-masked]
Windowing system distributor `The X.Org Foundation', version 11.0.10707000
System Description:	Debian GNU/Linux testing (wheezy)

Configured using:
 `configure '--prefix=/usr/local/built/''