From: Drew Adams <drew.adams@oracle.com>
To: Stephen Berman <stephen.berman@gmx.net>
Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
Subject: RE: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps'
Date: Fri, 4 Nov 2016 10:21:36 -0700 (PDT) [thread overview]
Message-ID: <3687e9ab-658b-49b9-b766-8658d5c48374@default> (raw)
In-Reply-To: <87twbncgve.fsf@gmx.net>
> > If that's what is meant then that's what the doc should say:
> > "the innermost sexp containing point".
>
> I think that's unnecessary if this is a "reasonable interpretation",
> i.e. it's common sense, so making it explicit tends to be pedantic.
> Do you really think this is not the common sense way of understanding
> it? If so, I guess you have a function in mind that behaves differently;
> which one?
When you know what the code does it is very easy to think
that vague doc is "reasonable" enough and "common sense".
Readers of the doc should not need to depend on what you
might understand of the code.
It is not unreasonable to be clear and brief. I repeat:
if the doc means "the innermost sexp containing point" then
it should just say that. That's not being pedantic; it's
being clear.
I stand by the bug #24860 report. Saying that something
described vaguely "does not work" is not helpful enough.
"Does not work on a sexp that point is in the middle of
if it is a list or string."
There is no way for users to know what that really means
(except by checking the code).
next prev parent reply other threads:[~2016-11-04 17:21 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <20161104095223.23249.72530@vcs.savannah.gnu.org>
[not found] ` <20161104095223.631AB22012D@vcs.savannah.gnu.org>
2016-11-04 14:09 ` emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' Stephen Berman
2016-11-04 14:31 ` Drew Adams
2016-11-04 15:47 ` Stephen Berman
2016-11-04 16:44 ` Drew Adams
2016-11-04 17:08 ` Stephen Berman
2016-11-04 17:21 ` Drew Adams [this message]
2016-11-04 17:50 ` Stephen Berman
2016-11-04 18:00 ` Drew Adams
2016-11-04 18:33 ` Eli Zaretskii
2016-11-04 18:30 ` Eli Zaretskii
2016-11-04 18:26 ` Eli Zaretskii
2016-11-04 18:14 ` Eli Zaretskii
[not found] <<20161104095223.23249.72530@vcs.savannah.gnu.org>
[not found] ` <<20161104095223.631AB22012D@vcs.savannah.gnu.org>
[not found] ` <<8737j7e3r5.fsf@gmx.net>
[not found] ` <<ba4a000f-c63d-4fde-94b9-d493e895b7c7@default>
[not found] ` <<87y40zckn9.fsf@gmx.net>
[not found] ` <<977b7eaa-1c5f-4d8b-be5d-33ec73f5a962@default>
[not found] ` <<87twbncgve.fsf@gmx.net>
[not found] ` <<3687e9ab-658b-49b9-b766-8658d5c48374@default>
[not found] ` <<87pombceyc.fsf@gmx.net>
[not found] ` <<83cd67b5-cb42-4fea-b6be-21e9ec8075a7@default>
[not found] ` <<83oa1vjdrx.fsf@gnu.org>
2016-11-04 19:36 ` Drew Adams
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
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=3687e9ab-658b-49b9-b766-8658d5c48374@default \
--to=drew.adams@oracle.com \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=stephen.berman@gmx.net \
/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 public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).