all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
To: 69387@debbugs.gnu.org
Cc: monnier@iro.umontreal.ca
Subject: bug#69387: 30.0.50; A string shouldn't be both a docstring and a return value
Date: Sun, 25 Feb 2024 11:29:45 -0500	[thread overview]
Message-ID: <jwvil2ctsli.fsf@iro.umontreal.ca> (raw)

Package: Emacs
Version: 30.0.50


Currently, ELisp defines

    (lambda (blabla) "Help!")

as a function that returns "Help!" *and* whose docstring is "Help!".
As seen in commit eeb89a5cb292bffe40ba7d0b0cf81f82f8452bf8, it can be
a source of annoyance as well.

I cannot remember finding source code which makes use of this "feature".
My impression is that our docs document this behavior simply because
that's how it happened to work rather than how it should work.
This is documented in the texinfo under "Function Documentation" where
it says:

    [...
    effects, it has no effect if it is not the last form in the body.  Thus,
    in practice, there is no confusion between the first form of the body
    and the documentation string; if the only body form is a string then it
    serves both as the return value and as the documentation.

I think we should change that to say that

    if the only body form is a string then it serves as the return value
    and not as the documentation.

This will/would require a few changes to `macroexp.el` and
`bytecomp.el`, but it should be minor.  It shouldn't introduce any
significant breakage either because the only effect will be to make it
so some functions won't have a docstring any more, but most (all?) of
those function never expected to have a docstring in the first place.


        Stefan






             reply	other threads:[~2024-02-25 16:29 UTC|newest]

Thread overview: 16+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2024-02-25 16:29 Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors [this message]
2024-02-25 17:13 ` bug#69387: 30.0.50; A string shouldn't be both a docstring and a return value Eli Zaretskii
2024-02-25 18:23   ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-25 17:33 ` Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-26 14:47   ` Philip Kaludercic
2024-02-26 17:15 ` Mattias Engdegård
2024-02-26 17:44   ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-26 18:04     ` Mattias Engdegård
2024-02-26 18:17       ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-26 19:06         ` Mattias Engdegård
2024-03-04 14:28           ` Mattias Engdegård
2024-03-04 14:46             ` Eli Zaretskii
2024-03-05 13:16               ` Mattias Engdegård
2024-03-05 15:38                 ` Eli Zaretskii
2024-03-06 11:44                   ` Mattias Engdegård
2024-03-07 14:06                     ` Mattias Engdegård

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=jwvil2ctsli.fsf@iro.umontreal.ca \
    --to=bug-gnu-emacs@gnu.org \
    --cc=69387@debbugs.gnu.org \
    --cc=monnier@iro.umontreal.ca \
    /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.