Re: Patch: make eldoc indicate current argument

[Richard Stallman <rms@gnu.org>]

    * 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.