summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJose Antonio Ortega Ruiz <jao@gnu.org>2010-11-19 21:13:56 +0100
committerJose Antonio Ortega Ruiz <jao@gnu.org>2010-11-19 21:13:56 +0100
commit481f0ea2e5577ad5bb1a718b8023af92202e7423 (patch)
tree4c62ceb15765a66cf4c0eef70917d01b8d9d280d
parentf6b03b27810e70304b89fd6185437dcf35d27b94 (diff)
downloadgeiser-guile-481f0ea2e5577ad5bb1a718b8023af92202e7423.tar.gz
geiser-guile-481f0ea2e5577ad5bb1a718b8023af92202e7423.tar.bz2
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).
-rw-r--r--doc/img/autodoc-scm.pngbin0 -> 18208 bytes
-rw-r--r--doc/img/repl-autodoc.pngbin44150 -> 13953 bytes
-rw-r--r--doc/parens.texi31
-rw-r--r--doc/repl.texi6
-rw-r--r--elisp/geiser-autodoc.el36
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
Binary files differ
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
Binary files differ
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