From b2b79169a4a7fab4de2f0337f5c850421a3ad3a0 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Fri, 19 Nov 2010 21:13:56 +0100 Subject: 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). --- doc/img/autodoc-scm.png | Bin 0 -> 18208 bytes doc/img/repl-autodoc.png | Bin 44150 -> 13953 bytes doc/parens.texi | 31 ++++++++++++++++--------------- doc/repl.texi | 6 +++--- 4 files changed, 19 insertions(+), 18 deletions(-) create mode 100644 doc/img/autodoc-scm.png (limited to 'doc') diff --git a/doc/img/autodoc-scm.png b/doc/img/autodoc-scm.png new file mode 100644 index 0000000..d7cc50f Binary files /dev/null and b/doc/img/autodoc-scm.png differ diff --git a/doc/img/repl-autodoc.png b/doc/img/repl-autodoc.png index 85df156..49ce58a 100644 Binary files a/doc/img/repl-autodoc.png and b/doc/img/repl-autodoc.png 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 -- cgit v1.2.3