From: Eli Zaretskii <eliz@gnu.org>
To: "Charles A. Roelli" <charles@aurox.ch>
Cc: dgutov@yandex.ru, 27230@debbugs.gnu.org
Subject: bug#27230: eldoc doc
Date: Sun, 25 Jun 2017 17:26:56 +0300 [thread overview]
Message-ID: <83efu8ta6n.fsf@gnu.org> (raw)
In-Reply-To: <d8aa01e1-57a4-ebbb-3147-304da4703377@aurox.ch> (charles@aurox.ch)
> 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.
next prev parent reply other threads:[~2017-06-25 14:26 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-06-04 10:38 bug#27230: eldoc doc Charles A. Roelli
2017-06-05 22:08 ` Dmitry Gutov
2017-06-06 18:33 ` Charles A. Roelli
2017-06-06 20:19 ` Dmitry Gutov
2017-06-25 9:14 ` Charles A. Roelli
2017-06-25 14:26 ` Eli Zaretskii [this message]
2017-06-25 19:47 ` Charles A. Roelli
2017-06-26 1:04 ` Dmitry Gutov
2017-06-27 19:51 ` Charles A. Roelli
2017-06-27 23:50 ` Dmitry Gutov
2017-06-28 19:16 ` Charles A. Roelli
2017-07-22 8:11 ` Eli Zaretskii
2017-09-14 11:47 ` Peder O. Klingenberg
2017-09-14 12:02 ` Dmitry Gutov
2017-09-14 19:39 ` Charles A. Roelli
2017-09-14 22:03 ` Dmitry Gutov
2017-09-19 20:02 ` Charles A. Roelli
2017-09-20 18:12 ` Charles A. Roelli
2017-09-21 14:23 ` Dmitry Gutov
2017-09-21 18:33 ` Charles A. Roelli
2017-09-21 23:05 ` Dmitry Gutov
2017-09-25 23:26 ` Dmitry Gutov
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=83efu8ta6n.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=27230@debbugs.gnu.org \
--cc=charles@aurox.ch \
--cc=dgutov@yandex.ru \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.