[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#27230: eldoc doc
From: |
Eli Zaretskii |
Subject: |
bug#27230: eldoc doc |
Date: |
Sun, 25 Jun 2017 17:26:56 +0300 |
> From: "Charles A. Roelli" <charles@aurox.ch>
> Date: Sun, 25 Jun 2017 11:14:23 +0200
>
> Here's a doc patch for ElDoc, with some minor readability fixes.
Thanks. Please allow me a few comments below.
> -(defun eldoc-message (&rest args)
> +(defun eldoc-message (&optional format-string &rest args)
> + "Store and display the given message.
The first line of a doc string should ideally mention the arguments.
> +FORMAT-STRING and ARGS, if given, are passed to `format-message',
> +the output of which is stored in `eldoc-last-message'.
This leaves me wondering what happens if no arguments are supplied.
> (defun eldoc--message-command-p (command)
> + "Non-nil if COMMAND is a command in `eldoc-message-commands'."
"Return non-nil if ...". The way you wrote it is appropriate for a
variable, not for a function.
> (defun eldoc-pre-command-refresh-echo-area ()
> + "Reprint `eldoc-last-message' to the echo area."
Are you sure about the "to" part? I'd say "in" sounds more correct.
> (defun eldoc-display-message-p ()
> + "Non-nil when appropriate to display an ElDoc message."
"Return non-nil"
> (defun eldoc-display-message-no-interference-p ()
> + "Nil when displaying an ElDoc message would cause interference
> +with other features."
Likewise. Also, the first line of a doc string should be a complete
sentence.
> (defun eldoc-print-current-symbol-info ()
> + "Print the output of `eldoc-documentation-function'."
"Print the output" sounds confusing. How about this instead:
Print the text produced by `eldoc-documentation-function'.
> (defun eldoc-docstring-format-sym-doc (prefix doc &optional face)
> + "Concatenate PREFIX and DOC, returning the largest part of the
> +resultant string that can fit in the minibuffer window.
First line not a complete sentence again.
> +When PREFIX is a symbol, apply FACE to it before concatenating.
But FACE is optional, so what if it isn't given?
Thanks for working on this.
- bug#27230: eldoc doc, Charles A. Roelli, 2017/06/04
- bug#27230: eldoc doc, Dmitry Gutov, 2017/06/05
- bug#27230: eldoc doc, Charles A. Roelli, 2017/06/06
- bug#27230: eldoc doc, Dmitry Gutov, 2017/06/06
- bug#27230: eldoc doc, Charles A. Roelli, 2017/06/25
- bug#27230: eldoc doc,
Eli Zaretskii <=
- bug#27230: eldoc doc, Charles A. Roelli, 2017/06/25
- bug#27230: eldoc doc, Dmitry Gutov, 2017/06/25
- bug#27230: eldoc doc, Charles A. Roelli, 2017/06/27
- bug#27230: eldoc doc, Dmitry Gutov, 2017/06/27
- bug#27230: eldoc doc, Charles A. Roelli, 2017/06/28