bug#18039: 24.3; Broken docstring in cl-style functions

bug#18039: 24.3; Broken docstring in cl-style functions

[Thorsten Jolitz]

Certain combinations of normal function args with &key args result in
broken docstrings for functions defined with `defun*'.

Recipe:
0. emacs -Q
1. download and load
   https://raw.githubusercontent.com/tj64/puml/master/puml.el
2. 
   
,----[ C-h f puml-key-val RET ]
| puml-key-val is a Lisp function in `puml.el'.
| 
| (puml-key-val KEY VAL &key CRLF INS)
| 
| Return or insert PlantUML key-val pair.
`----

OK

3. 

,----[ C-h f puml-arrow RET ]
| puml-arrow is a Lisp function in `puml.el'.
| 
| (puml-arrow &key (LEN 2) DIR (SHAFT "-") (LHEAD "") (RHEAD ">") LEXTRA
| REXTRA INS)
| 
| Return or insert PlantUML arrow.
`----

OK

4.  

,----[ C-h f puml-skinparam RET ]
| puml-skinparam is a Lisp function in `puml.el'.
| 
| (puml-skinparam 40 102 110 32 75 69 89 45 86 65 76 45 83 84 82 71 32
| 38 107 101 121 32 69 76 69 77 32 40 67 82 76 70 32 34 10 34 41 32 73
| 78 83 41)
| 
| Return or insert PlantUML skinparam.
`----

BUG

signature looks like this:

(defun* puml-skinparam (key-val-strg &key elem (crlf "\n") ins)

thus the bug seems to be in the combination of normal args
'key-val-strg and &key args with default values '(crlf "\n"). 



In GNU Emacs 24.3.1 (x86_64-unknown-linux-gnu, GTK+ Version 3.12.2)
 of 2014-06-11 on var-lib-archbuild-staging-x86_64-jgc
Configured using:
 `configure '--prefix=/usr' '--sysconfdir=/etc' '--libexecdir=/usr/lib'
 '--localstatedir=/var' '--with-x-toolkit=gtk3' '--with-xft'
 'CFLAGS=-march=x86-64 -mtune=generic -O2 -pipe -fstack-protector-strong
 --param=ssp-buffer-size=4'
 'LDFLAGS=-Wl,-O1,--sort-common,--as-needed,-z,relro'
 'CPPFLAGS=-D_FORTIFY_SOURCE=2''

Important settings:
  value of $LANG: de_DE.UTF-8
  locale-coding-system: utf-8-unix
  default enable-multibyte-characters: t

Major mode: Emacs-Lisp

Minor modes in effect:
  tooltip-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
C-x d g i t / p u m TAB RET n n n L y C-x 3 C-h f p 
u m l - a c t TAB i TAB RET f C-v C-v C-v C-v C-v C-v 
C-v C-v C-v C-h f p u m l - s k i TAB RET C-v C-h f 
p u m l - a r r o w RET C-g C-p C-p C-p C-p C-p C-p 
C-p C-p C-p C-p C-p C-p C-h f p u m l - k e TAB RET 
C-h f p u m l - n o t e RET ESC x e m a DEL DEL DEL 
b u TAB g TAB TAB ESC b C-k C-b C-g ESC x r e p TAB 
o TAB r TAB RET

Recent messages:
Load: 1 file.
Making completion list...
Type "q" in help window to restore its previous buffer.
Loading vc-git...done
 [2 times]
Quit
 [2 times]
Making completion list... [2 times]
Quit
Making completion list... [2 times]

Load-path shadows:
/usr/share/emacs/24.3/lisp/org/.dir-locals hides /usr/share/emacs/24.3/lisp/gnus/.dir-locals

Features:
(shadow sort gnus-util mail-extr emacsbug message format-spec rfc822 mml
mml-sec mm-decode mm-bodies mm-encode mail-parse rfc2231 mailabbrev
gmm-utils mailheader sendmail rfc2047 rfc2045 ietf-drums mm-util
mail-prsvr mail-utils vc-git help-mode easymenu puml help-fns cl-macs gv
cl cl-lib dired-aux dired time-date tooltip ediff-hook vc-hooks
lisp-float-type mwheel x-win x-dnd tool-bar dnd fontset image regexp-opt
fringe tabulated-list newcomment lisp-mode register page menu-bar
rfn-eshadow timer select scroll-bar mouse jit-lock font-lock syntax
facemenu font-core frame cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese hebrew greek romanian slovak
czech european ethiopic indian cyrillic chinese case-table epa-hook
jka-cmpr-hook help simple abbrev minibuffer loaddefs button faces
cus-face macroexp files text-properties overlay sha1 md5 base64 format
env code-pages mule custom widget hashtable-print-readable backquote
make-network-process dbusbind dynamic-setting system-font-setting
font-render-setting move-toolbar gtk x-toolkit x multi-tty emacs)

-- 
cheers,
Thorsten

bug#18039: 24.3; Broken docstring in cl-style functions

[Michael Heerdegen]

Thorsten Jolitz <tjolitz@gmail.com> writes:

> thus the bug seems to be in the combination of normal args
> 'key-val-strg and &key args with default values '(crlf "\n"). 

Indeed. Eval this in emacs -Q:

M-: (require 'cl)
M-: (cl-defun test (&key (c "\n")) "Test" nil)
M-: (symbol-function 'test)

==>

(lambda (&rest --cl-rest--) "Test

(fn 40 102 110 32 38 107 101 121 32 40 67 32 34 10 34 41 41) ...)

The newline character in the (printed) argument list makes a
difference in this expression in help-add-fundoc-usage:

    (if (and (stringp arglist)
	     (string-match "\\`([^ ]+\\(.*\\))\\'" arglist))
	(concat "(fn" (match-string 1 arglist) ")")
      (format "%S" (help-make-usage 'fn arglist)))

(help-make-usage doesn't seem to expect a stringp arglist).  Should the
regexp given to string-match be changed?


Michael.

bug#18039: 24.3; Broken docstring in cl-style functions

[Stefan Monnier]

> The newline character in the (printed) argument list makes a
> difference in this expression in help-add-fundoc-usage:

>     (if (and (stringp arglist)
> 	     (string-match "\\`([^ ]+\\(.*\\))\\'" arglist))
> 	(concat "(fn" (match-string 1 arglist) ")")
>       (format "%S" (help-make-usage 'fn arglist)))

> (help-make-usage doesn't seem to expect a stringp arglist).  Should the
> regexp given to string-match be changed?

Indeed, we have a bug there.  We should/could probably arrange for
arglist to be on a single line (quote newlines as \n), but we should
also make the code more robust such that when the regexp fails to match
we signal an error rather than fallback to the non-string case which
then burps.


        Stefan