Patch: make eldoc indicate current argument

Patch: make eldoc indicate current argument

[Tom Tromey]

This patch changes eldoc so that the current argument is highlighted
in bold.  This is something Eclipse does and I've found it nice to use
there.  Note that "current" generally means "argument after point" --
this yields the nicest results when typing in new forms, since if you
pause you will see what comes next.

This patch isn't perfect.  There are a few improvements that could be
made.  However, IMO it is good enough without these.

* Emacs formats documentation inconsistently.  Some functions use
  &optional and &rest in their description.  Some use "..." appended
  to an argument name, e.g. "CLAUSES...".  And, some use "..." as a
  standalone argument name (see 'when').  This patch doesn't attempt
  to deal with all these cases properly.

* If the documentation comments had a bit more structure, this could
  also show the description of the current argument, say as a tooltip.
  I don't think there is a reliable way to extract this information at
  present.

* It might be nice to show the eldoc just after typing space, without
  a pause.  Currently you must pause briefly to see where you are in
  the argument list.

Tom

2007-06-27  Tom Tromey  <tromey@redhat.com>

	* emacs-lisp/eldoc.el (eldoc-beginning-of-sexp): Return number of
	sexps skipped.
	(eldoc-fnsym-in-current-sexp): Return cons including number of
	sexps skipped.
	(eldoc-get-fnsym-args-string): Added 'index' argument.  Fontify
	current argument.
	(eldoc-print-current-symbol-info): Update.

Index: lisp/emacs-lisp/eldoc.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/emacs-lisp/eldoc.el,v
retrieving revision 1.42
diff -u -r1.42 eldoc.el
--- lisp/emacs-lisp/eldoc.el	7 May 2007 01:09:35 -0000	1.42
+++ lisp/emacs-lisp/eldoc.el	27 Jun 2007 17:02:32 -0000
@@ -247,14 +247,18 @@
 	   (if eldoc-documentation-function
 	       (eldoc-message (funcall eldoc-documentation-function))
 	     (let* ((current-symbol (eldoc-current-symbol))
-		    (current-fnsym  (eldoc-fnsym-in-current-sexp))
+		    (sexp-pair      (eldoc-fnsym-in-current-sexp))
+		    (current-fnsym  (cdr sexp-pair))
+		    (current-arg    (car sexp-pair))
 		    (doc (cond
 			  ((eq current-symbol current-fnsym)
-			   (or (eldoc-get-fnsym-args-string current-fnsym)
+			   (or (eldoc-get-fnsym-args-string current-fnsym
+							    current-arg)
 			       (eldoc-get-var-docstring current-symbol)))
 			  (t
 			   (or (eldoc-get-var-docstring current-symbol)
-			       (eldoc-get-fnsym-args-string current-fnsym))))))
+			       (eldoc-get-fnsym-args-string current-fnsym
+							    current-arg))))))
 	       (eldoc-message doc))))
     ;; This is run from post-command-hook or some idle timer thing,
     ;; so we need to be careful that errors aren't ignored.
@@ -263,7 +267,7 @@
 ;; Return a string containing the function parameter list, or 1-line
 ;; docstring if function is a subr and no arglist is obtainable from the
 ;; docstring or elsewhere.
-(defun eldoc-get-fnsym-args-string (sym)
+(defun eldoc-get-fnsym-args-string (sym index)
   (let ((args nil)
         (doc nil))
     (cond ((not (and sym (symbolp sym) (fboundp sym))))
@@ -279,6 +283,20 @@
     (cond (args
            (setq doc (eldoc-docstring-format-sym-doc sym args))
            (eldoc-last-data-store sym doc 'function)))
+    (when (and doc (> index 0))
+      (save-match-data
+	;; Perhaps this should recognize argument names that have
+	;; trailing "..."s (see 'cond') or standalone "..."s (see
+	;; 'when').  Or, maybe Emacs should more strictly follow a
+	;; convention.  And, perhaps this should use a different
+	;; highlight if there are now many actual arguments.
+	(let ((rx (concat "[(]\\(?:&optional \\|&rest \\)?\\(?:[^ ]* \\(?:&optional \\|&rest \\)?\\)\\{"
+			  (int-to-string (1- index))
+			  "\\}\\([^ ]*\\)[ )]")))
+	  (when (string-match rx doc)
+	    (setq doc (substring doc 0))
+	    (put-text-property (match-beginning 1) (match-end 1) 'face 'bold
+			       doc)))))
     doc))
 
 ;; Return a string containing a brief (one-line) documentation string for
@@ -342,23 +360,27 @@
 
 \f
 (defun eldoc-fnsym-in-current-sexp ()
-  (let ((p (point)))
-    (eldoc-beginning-of-sexp)
+  (let* ((p (point))
+	 (n-sexps (eldoc-beginning-of-sexp)))
     (prog1
         ;; Don't do anything if current word is inside a string.
         (if (= (or (char-after (1- (point))) 0) ?\")
             nil
-          (eldoc-current-symbol))
+          (cons n-sexps (eldoc-current-symbol)))
       (goto-char p))))
 
 (defun eldoc-beginning-of-sexp ()
-  (let ((parse-sexp-ignore-comments t))
+  (let ((parse-sexp-ignore-comments t)
+	(count 0))
     (condition-case err
-        (while (progn
-                 (forward-sexp -1)
-                 (or (= (char-before) ?\")
-                     (> (point) (point-min)))))
-      (error nil))))
+        (progn
+	  (while (progn
+		   (forward-sexp -1)
+		   (setq count (1+ count))
+		   (or (= (char-before) ?\")
+		       (> (point) (point-min)))))
+	  count)
+      (error count))))
 
 ;; returns nil unless current word is an interned symbol.
 (defun eldoc-current-symbol ()

Re: Patch: make eldoc indicate current argument

[Richard Stallman]

    * Emacs formats documentation inconsistently.  Some functions use
      &optional and &rest in their description.  

I think you are talking about calling patterns in doc strings, not
about documentation in general.  Is that right?

&optional and &rest appear in calling patterns of functions.
We use ellipses and square brackets in calling patterns of macros
and special forms.

						 Some use "..." appended
      to an argument name, e.g. "CLAUSES...".  And, some use "..." as a
      standalone argument name (see 'when').

Do you mean this?

    (when COND BODY ...)

If so, I think that is a misunderstanding.  The ellipsis here is not
an argument name, it is just an ellipsis.  The space after `BODY' has
no significance.

Perhaps we should delete that space, for consistency.
Would someone like to do that?

Would you like to make a list of the places where such spurious spaces
appear?

    * If the documentation comments had a bit more structure, this could
      also show the description of the current argument, say as a tooltip.
      I don't think there is a reliable way to extract this information at
      present.

Alas, this would be a tremendous rewrite, and could make the doc
strings less readable for their current use if we're not careful.
Maybe some sort of cookie to indicate where the discussion of an
argument begins, within the doc string, would let you do this,
but it won't be easy.

The difficulty can be seen in the doc string of `when':

    If COND yields non-nil, do BODY, else return nil.
    When COND yields non-nil, eval BODY forms sequentially and return
    value of last one, or nil if there are none.

It is not natural to separate this into a discussion of COND and a
discussion of BODY.

But if you don't insist that each segment discuss only one argument,
we could subdivide each doc string into segments, and they you could
find all the segments in which the argument name is mentioned, and
display them.

Suppose that we use `][' as the segment separator.
Here as an example is the doc string of call-process, showing what
this would look like.

    (call-process PROGRAM &optional INFILE BUFFER DISPLAY &rest ARGS)

    Call PROGRAM synchronously in separate process.
    The remaining arguments are optional.
    ][The program's input comes from file INFILE (nil means `/dev/null').
    ][Insert output in BUFFER before point; t means current buffer;
     nil for BUFFER means discard it; 0 means discard and don't wait.
    BUFFER can also have the form (REAL-BUFFER STDERR-FILE); in that case,
    REAL-BUFFER says what to do with standard output, as above,
    while STDERR-FILE says what to do with standard error in the child.
    STDERR-FILE may be nil (discard standard error output),
    t (mix it with ordinary output), or a file name string.

    ][Fourth arg DISPLAY non-nil means redisplay buffer as output is inserted.
    ][Remaining arguments are strings passed as command arguments to PROGRAM.

    ][If executable PROGRAM can't be found as an executable, `call-process'
    signals a Lisp error.  `call-process' reports errors in execution of
    the program only through its return and output.

    ][If BUFFER is 0, `call-process' returns immediately with value nil.
    Otherwise it waits for PROGRAM to terminate
    and returns a numeric exit status or a signal description string.
    ][If you quit, the process is killed with SIGINT, or SIGKILL if you quit again.

If you like, you could try experimenting with this idea and see what
you can make it do.

Re: Patch: make eldoc indicate current argument

[Tom Tromey]

>>>>> "rms" == Richard Stallman <rms@gnu.org> writes:

>     * Emacs formats documentation inconsistently.  Some functions use
>       &optional and &rest in their description.  

rms> I think you are talking about calling patterns in doc strings, not
rms> about documentation in general.  Is that right?

Yes.  Sorry about that.  This patch & my comments are solely about
eldoc and thus doc strings.

rms> Do you mean this?
rms>     (when COND BODY ...)
rms> If so, I think that is a misunderstanding.  The ellipsis here is not
rms> an argument name, it is just an ellipsis.  The space after `BODY' has
rms> no significance.

Yeah, my terminology was a bit lax.  Anyway, sometimes there is a
space, and sometimes not.  And this means that with this patch
occasionally something like "FOO..." is bold, and sometimes just the
"...".  Also the modified code doesn't understand that "..." refers to
all remaining arguments; so for instance in:

    (when (cond)
       (f1)
       (f2)
       (f3))

... if point is on (f3), nothing will be made bold in the description.

Personally I find these buglets to be minor.  But others may disagree.

rms> Perhaps we should delete that space, for consistency.
rms> Would someone like to do that?

Not me :-).

>     * If the documentation comments had a bit more structure, this could
>       also show the description of the current argument, say as a tooltip.
>       I don't think there is a reliable way to extract this information at
>       present.

rms> Alas, this would be a tremendous rewrite, and could make the doc
rms> strings less readable for their current use if we're not careful.

Good example here, thanks.  Well, another idea is to display the full
documentation comment in a tooltip, perhaps in response to some key.

This is really a side idea: it is something I've seen in Eclipse and
which is occasionally useful, and I thought maybe it would also be
useful in Emacs.  But the patch at hand doesn't really need this.

Tom

Re: Patch: make eldoc indicate current argument

[Tom Tromey]

>>>>> "Tom" == Tom Tromey <tromey@redhat.com> writes:

Tom> This patch changes eldoc so that the current argument is
Tom> highlighted in bold.

On irc someone (sorry, don't know your real name...) pointed out that
there is a previous patch:

    http://article.gmane.org/gmane.emacs.devel/24426

This was sent in 2004 and from what I can tell, not checked in due to
a feature freeze.


And there is also the color-eldoc package:

    http://www.dd.chalmers.se/~bojohan/emacs/lisp/color-eldoc.el

This one looks nicest (the screenshot -- I didn't read the code),
maybe someone (an actual maintainer, not a dilettante like me :-)
could approach the author for paperwork and inclusion in Emacs.

Tom

Re: Patch: make eldoc indicate current argument

[Kevin Rodgers]

Richard Stallman wrote:
> &optional and &rest appear in calling patterns of functions.
> We use ellipses and square brackets in calling patterns of macros
> and special forms.
> 
> 						 Some use "..." appended
>       to an argument name, e.g. "CLAUSES...".  And, some use "..." as a
>       standalone argument name (see 'when').
> 
> Do you mean this?
> 
>     (when COND BODY ...)
> 
> If so, I think that is a misunderstanding.  The ellipsis here is not
> an argument name, it is just an ellipsis.  The space after `BODY' has
> no significance.
 >
 > Perhaps we should delete that space, for consistency.

The problem is not the space, it is the ellipsis, which is usually
interpreted in this context to mean "et cetera".  But there is only 1
BODY, which is the list of individual body forms.

I would prefer

	(when COND &rest BODY)

or

	(when COND FORM ...)

-- 
Kevin Rodgers
Denver, Colorado, USA

Re: Patch: make eldoc indicate current argument

[David Kastrup]

Kevin Rodgers <kevin.d.rodgers@gmail.com> writes:

> Richard Stallman wrote:
>> &optional and &rest appear in calling patterns of functions.
>> We use ellipses and square brackets in calling patterns of macros
>> and special forms.
>>
>> 						 Some use "..." appended
>>       to an argument name, e.g. "CLAUSES...".  And, some use "..." as a
>>       standalone argument name (see 'when').
>>
>> Do you mean this?
>>
>>     (when COND BODY ...)
>>
>> If so, I think that is a misunderstanding.  The ellipsis here is not
>> an argument name, it is just an ellipsis.  The space after `BODY' has
>> no significance.
>>
>> Perhaps we should delete that space, for consistency.
>
> The problem is not the space, it is the ellipsis, which is usually
> interpreted in this context to mean "et cetera".  But there is only 1
> BODY, which is the list of individual body forms.
>
> I would prefer
>
> 	(when COND &rest BODY)
>
> or
>
> 	(when COND FORM ...)

BODY... is a single symbol which brings across the idea of a
multi-form entity quite intuitively.

A agree with Richard that there should not be a space, however.

-- 
David Kastrup

Re: Patch: make eldoc indicate current argument

[Richard Stallman]

    BODY... is a single symbol which brings across the idea of a
    multi-form entity quite intuitively.

Yes, that is our convention.

    A agree with Richard that there should not be a space, however.

Would you like to delete the spaces from such doc strings
in the trunk?

Re: Patch: make eldoc indicate current argument

[Juanma Barranquero]

On 7/14/07, Richard Stallman <rms@gnu.org> wrote:

> Would you like to delete the spaces from such doc strings
> in the trunk?

Why just in the trunk?

             Juanma

Re: Patch: make eldoc indicate current argument

[David Kastrup]

"Juanma Barranquero" <lekktu@gmail.com> writes:

> On 7/14/07, Richard Stallman <rms@gnu.org> wrote:
>
>> Would you like to delete the spaces from such doc strings
>> in the trunk?
>
> Why just in the trunk?

Because it will percolate from there, anyway, if people find it
important.

Anyway, you beat me to it.  It appears that "such doc strings" were
only there for `when' and `unless'.  To do anything at all, I changed
a single occurence of "BODY... )" in advice.el to "BODY...)" which
seems to be the default.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Patch: make eldoc indicate current argument

[Richard Stallman]

    >> Would you like to delete the spaces from such doc strings
    >> in the trunk?
    >
    > Why just in the trunk?

Because the eldoc changes that would need this will only go in the trunk.

Re: Patch: make eldoc indicate current argument

[Juanma Barranquero]

On 7/15/07, Richard Stallman <rms@gnu.org> wrote:

> Because the eldoc changes that would need this will only go in the trunk.

Having "BODY ..." in a docstring is ugly and confusing, irrespectively
of any eldoc change.

             Juanma

Re: Patch: make eldoc indicate current argument

[Johan Bockgård]

David Kastrup <dak@gnu.org> writes:

> It appears that "such doc strings" were only there for `when' and
> `unless'.

Others are

  src/eval.c:   (or CONDITIONS ...)
  src/eval.c:   (and CONDITIONS ...)
  src/coding.c: (find-operation-coding-system OPERATION ARGUMENTS ...)

Maybe the last should even use `&rest' as it is a function rather than
a special form.


Then there are a bunch of operators using e.g. square brackets which
are troublesome for eldoc. E.g

  (setq-default [VAR VALUE...])

  (vs  (setq SYM VAL SYM VAL ...))

-- 
Johan Bockgård

Re: Patch: make eldoc indicate current argument

[Richard Stallman]

    Having "BODY ..." in a docstring is ugly and confusing, irrespectively
    of any eldoc change.

I don't mind if you change it in Emacs 22 as well.
I just didn't ask for that, because it wasn't specifically needed.

Re: Patch: make eldoc indicate current argument

[Richard Stallman]

    Then there are a bunch of operators using e.g. square brackets which
    are troublesome for eldoc. E.g

      (setq-default [VAR VALUE...])

      (vs  (setq SYM VAL SYM VAL ...))

I fixed both of those (in Emacs 22) to be more rational:
[VAR VALUE]...

I hope those changes will migrate into the trunk.

Re: Patch: make eldoc indicate current argument

[Paul Pogonyshev]

Johan Bockgård wrote:
> Then there are a bunch of operators using e.g. square brackets which
> are troublesome for eldoc. E.g
> 
>   (setq-default [VAR VALUE...])
> 
>   (vs  (setq SYM VAL SYM VAL ...))

I was aware of such things (optional parameters in brackets), but
didn't figure out what to do with them:

    ;; FIXME: What to do with optional arguments, like in
    ;;        (defun NAME ARGLIST [DOCSTRING] BODY...) case?
    ;;        The problem is there is no robust way to determine if
    ;;        the current argument is indeed a docstring.

Paul

Re: Patch: make eldoc indicate current argument

[Richard Stallman]

    I was aware of such things (optional parameters in brackets), but
    didn't figure out what to do with them:

	;; FIXME: What to do with optional arguments, like in
	;;        (defun NAME ARGLIST [DOCSTRING] BODY...) case?
	;;        The problem is there is no robust way to determine if
	;;        the current argument is indeed a docstring.

Doc strings are so important that eldoc may as well have special-case
code for them.

Re: Patch: make eldoc indicate current argument

[Stefan Monnier]

>     I was aware of such things (optional parameters in brackets), but
>     didn't figure out what to do with them:

> 	;; FIXME: What to do with optional arguments, like in
> 	;;        (defun NAME ARGLIST [DOCSTRING] BODY...) case?
> 	;;        The problem is there is no robust way to determine if
> 	;;        the current argument is indeed a docstring.

> Doc strings are so important that eldoc may as well have special-case
> code for them.

Hmm.... I'm trying to figure out in which circumstance it would be useful or
even possible to distinguish the two args in the help info:

- if point is on the second sexp (or further) in the body, it obviously
  won't make any difference.
- so it only makes a potential difference if point is on the first sexp in
  the body.
- if we don't do anything special, this will always be listed as being on
  [DOCSTRING].
- so if we're looking at a string, this is right unless there's
  no sexp afterwards.
- if we're looking at nothing, then selecting [DOCSTRING] is as good
  as any.
- if we're looking at an open paren an open [, then this is wrong,
  although only marginally so: we're just *before* the BODY and the user may
  decide to insert a docstring at point, so showing [DOCSTRING] isn't such
  a bad idea after all.
- we're inside a number or a symbol: this case is indeed just wrong and the
  help data should indicate we're in the BODY part.


-- Stefan

Re: Patch: make eldoc indicate current argument

[Richard Stallman]

The doc string is always just before the body.
Perhaps the best thing for eldoc to do is not distinguish them:
to treat the doc string just like the body.