Better argument display in autodoc

Simpler (we don't need no square brackets) and more correct (keywords
display as keywords and we only include default values when available
(Guile, i'm looking at you).

5 files changed, 38 insertions, 35 deletions

diff --git a/doc/img/autodoc-scm.png b/doc/img/autodoc-scm.png
new file mode 100644
index 0000000..d7cc50f
--- /dev/null
+++ b/doc/img/autodoc-scm.png
diff --git a/doc/img/repl-autodoc.png b/doc/img/repl-autodoc.png
index 85df156..49ce58a 100644
--- a/doc/img/repl-autodoc.png
+++ b/doc/img/repl-autodoc.png
diff --git a/doc/parens.texi b/doc/parens.texi
index 8068d51..439e56c 100644
--- a/doc/parens.texi
+++ b/doc/parens.texi
@@ -227,31 +227,32 @@ obscure reason, that it be inactive by default, just set
 @code{geiser-mode-autodoc-p} to @code{nil} in your customization files.
 
 @cindex autodoc explained
-@img{autodoc-req, right} The way autodoc displays information deserves
+@img{autodoc-scm, right} The way autodoc displays information deserves
 some explanation. It will first show the name of the module where the
 identifier at hand is defined, followed by a colon and the identifier
 itself. If the latter corresponds to a procedure or macro, it will be
 followed by a list of argument names, starting with the ones that are
-required. Then there comes a square-bracketed list of optional argument
-names, if any. When an optional argument has a default value (or a form
-defining its default value), instead of a plain name, autodoc will
-display a list with the name followed by its initialisation form. When
-the optional arguments are keywords, their names are prefixed with a
-colon. An ellipsis (@dots{}) servers as a marker of an indeterminated
-number of parameters, as is the case with @i{rest} arguments or when
-autodoc cannot fathom the exact number of arguments (this is often the
-case with macros defined using @code{syntax-case}). Another way in which
-autodoc displays its ignorance is by using and underscore to display
-parameters whose name is beyond its powers.
+required. Then there comes a list of optional arguments, if any,
+enclosed in parenthesis. When an optional argument has a default value
+(or a form defining its default value), autodoc will display it after
+the argument name. When the optional arguments are keywords, their names
+are prefixed with ``#:'' (i.e., their names @i{are} keywords). An
+ellipsis (@dots{}) serves as a marker of an indeterminated number of
+parameters, as is the case with @i{rest} arguments or when autodoc
+cannot fathom the exact number of arguments (this is often the case with
+macros defined using @code{syntax-case}). Another way in which autodoc
+displays its ignorance is by using and underscore to display parameters
+whose name is beyond its powers.
 
 @img{autodoc-multi, right} It can also be the case that a function or
 macro has more than one signature (e.g., functions defined using
 @code{case-lambda}, or some @code{syntax-rules} macros, for which Geiser
 has often the black magic necessary to retrieve their actual arities).
 In those cases, autodoc shows all known signatures (using the above
-rules for each one) separated by a vertical bar (|). As you have already
-noticed, the whole thing is enclosed in parenthesis. After all, we're
-talking about Scheme here.
+rules for each one) separated by a vertical bar (|).
+
+As you have already noticed, the whole autodoc message is enclosed in
+parenthesis. After all, we're talking about Scheme here.
 
 @cindex autodoc for variables
 @img{autodoc-var, right} Finally, life is much easier when your cursor
diff --git a/doc/repl.texi b/doc/repl.texi
index aefa432..ffb733b 100644
--- a/doc/repl.texi
+++ b/doc/repl.texi
@@ -210,10 +210,10 @@ If that identifier corresponds to a variable visible in the current
 namespace, you'll see the module it belongs to and its value. For
 procedures and macros, autodoc will display, instead of their value, the
 argument names (or an underscore if Geiser cannot determine the name
-used in the definition). Optional arguments are surrounded by square
-brackets, and, when the optional argument has a default value, it's
+used in the definition). Optional arguments are surrounded by
+parenthesis. When the optional argument has a default value, it's
 represented by a list made up of its name and that value. When the
-argument is a keyword argument, its name is preceded by a colon.
+argument is a keyword argument, its name has ``#:'' as a prefix.
 
 @cindex help on identifier
 If that's not enough documentation for you, @kbd{C-c C-d d} will open a
diff --git a/elisp/geiser-autodoc.el b/elisp/geiser-autodoc.el
index 35a9834..5bdfb1a 100644
--- a/elisp/geiser-autodoc.el
+++ b/elisp/geiser-autodoc.el
@@ -84,12 +84,20 @@ when `geiser-autodoc-display-module-p' is on."
   (cond ((null args) nil)
         ((listp args)
          (cons (car args) (geiser-autodoc--sanitize-args (cdr args))))
-        (t '(...))))
+        (t '...)))
+
+(defun geiser-autodoc--format-arg (a)
+  (if (and (listp a) (keywordp (car a)))
+      (if (and (cdr a) (listp (cdr a)))
+          (format "(#%s %s)" (car a) (cadr a))
+        (format "(#%s)" (car a)))
+    (format "%s" a)))
 
 (defun geiser-autodoc--insert-arg-group (args current &optional pos)
+  (when args (insert " "))
   (dolist (a (geiser-autodoc--sanitize-args args))
     (let ((p (point)))
-      (insert (format "%s" a))
+      (insert (geiser-autodoc--format-arg a))
       (when (or (and (numberp pos)
                      (numberp current)
                      (setq current (1+ current))
@@ -107,22 +115,16 @@ when `geiser-autodoc-display-module-p' is on."
 (defun geiser-autodoc--insert-args (args pos prev)
   (let ((cpos 1)
         (reqs (cdr (assoc 'required args)))
-        (opts (cdr (assoc 'optional args)))
+        (opts (mapcar (lambda (a)
+                        (if (and (symbolp a) (not (eq a '...))) (list a) a))
+                      (cdr (assoc 'optional args))))
         (keys (cdr (assoc 'key args))))
-    (when reqs
-      (insert " ")
-      (setq cpos
-            (geiser-autodoc--insert-arg-group reqs
-                                              cpos
-                                              (and (not (zerop pos)) pos))))
-    (when opts
-      (insert " [")
-      (setq cpos (geiser-autodoc--insert-arg-group opts cpos pos)))
-    (when keys
-      (insert " [")
-      (geiser-autodoc--insert-arg-group keys prev nil)
-      (insert "]"))
-    (when opts (insert "]"))))
+    (setq cpos
+          (geiser-autodoc--insert-arg-group reqs
+                                            cpos
+                                            (and (not (zerop pos)) pos)))
+    (setq cpos (geiser-autodoc--insert-arg-group opts cpos pos))
+    (geiser-autodoc--insert-arg-group keys prev nil)))
 
 (defsubst geiser-autodoc--id-name (proc module)
   (let ((str (if module