bug#27230: eldoc doc

[Charles A. Roelli]

On 26/06/2017 03:04, Dmitry Gutov wrote:
> On 6/25/17 10:47 PM, Charles A. Roelli wrote:
>
> > FORMAT-STRING (or nil, if not given) is stored in
> > `eldoc-last-message'.  If ARGS are given, FORMAT-STRING is first
> > formatted through `format-message'.
>
> I wonder if we ever call this function with more than one argument. If 
> not, the code and the doc call for simplification. We can avoid 
> advertising this possibility, at least.

I think it follows the tradition of other *-message functions, which
normally use the calling convention of `message'/`format-message'.

> > If `eldoc-last-message' is non-nil, display it using
> > `eldoc-message-function'.  If it is nil, clear the echo area if
> > there was recently a message from ElDoc there.
>
> I think this needlessly prioritizes the implementation over the 
> intention. And the latter is to display whatever the documentation 
> function returns (if non-nil). Saving to eldoc-last-message is 
> secondary, and can be mentioned later.

Agreed. Can you suggest how to word it?  Here's what I come up with:

  "Display FORMAT-STRING formatted with ARGS as an ElDoc message.

Store the message (if any) in `eldoc-last-message', and return it."

> > Return `eldoc-last-message'."
>
> This is probably non-essential, and we can avoid mentioning it.

I think it once again follows the convention of other *-message
functions, probably for consistency.