bug#27230: eldoc doc

["Charles A. Roelli" <charles@aurox.ch>]

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.