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