From: Stefan Monnier <monnier@iro.umontreal.ca>
To: Michael Albinus <michael.albinus@gmx.de>
Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Kangas <stefan@marxist.se>,
Anonymous <c4droid@foxmail.com>,
Emacs developers <emacs-devel@gnu.org>
Subject: Adding examples in the doc (was: Some ideas with Emacs)
Date: Fri, 29 Nov 2019 14:13:25 -0500 [thread overview]
Message-ID: <jwvd0damrmy.fsf-monnier+emacs@gnu.org> (raw)
In-Reply-To: <87h82my0fm.fsf@gmx.de> (Michael Albinus's message of "Fri, 29 Nov 2019 19:58:21 +0100")
>> AFACT, currently we have some examples in the Elisp manual and very
>> few examples in docstrings.
>> It might be a good idea to encourage the addition of examples either in
>> docstrings or in the Elisp manual (or both).
> Personally, I don't like docstring to be too verbose.
I tend to agree. Of course part of it is that a verbose docstring is an
indication that the function is complex to use, but there's also simply
the impact on the visual distance between the function header and the code.
Another issue w.r.t examples is that editing Elisp code within
docstrings is a PITA (you don't get the usual
completion/indentation/... plus you have to be careful with escaping
' and friends so they don't get "shaped").
Also, docstrings have no formal structure and usually contain text, so
if we want to add examples in docstrings, I would prefer we first design
a structure to clearly distinguish text from code so we can render it
more elegantly.
Maybe examples should simply live *outside* of the function definition,
e.g. with
(defexamples ...)
This might also have the benefit of being able to associate an example
with several functions (when the example shows how to combine calls to
various functions to get a particular result).
> Usually, when a function is documented with both docstrings and
> a manual, I prefer to put the examples in the manual.
I find code in texi files to be less convenient to edit/use.
Stefan
next prev parent reply other threads:[~2019-11-29 19:13 UTC|newest]
Thread overview: 120+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-11-29 9:05 Some ideas with Emacs Anonymous
2019-11-29 11:16 ` Marcin Borkowski
2019-11-29 11:44 ` =?gb18030?B?QW5vbnltb3Vz?=
2019-11-30 5:54 ` Emanuel Berg via Emacs development discussions.
2019-11-30 5:51 ` Emanuel Berg via Emacs development discussions.
2019-12-01 5:57 ` Richard Stallman
2019-12-01 10:56 ` Marcin Borkowski
2019-12-01 11:08 ` Marcin Borkowski
2019-12-01 13:40 ` VanL
2019-12-01 14:07 ` Marcin Borkowski
2019-12-02 4:52 ` VanL
2019-12-02 6:12 ` Marcin Borkowski
2019-12-03 5:01 ` Richard Stallman
2019-12-03 15:45 ` Eli Zaretskii
2019-12-03 16:21 ` Emanuel Berg via Emacs development discussions.
2019-12-03 17:35 ` Eli Zaretskii
2019-12-03 17:59 ` Stefan Monnier
2019-12-03 19:51 ` Emanuel Berg via Emacs development discussions.
2019-12-03 19:32 ` Marcin Borkowski
2019-12-03 19:37 ` Eli Zaretskii
2019-12-03 23:08 ` Marcin Borkowski
2019-12-04 3:42 ` Eli Zaretskii
2019-12-06 18:29 ` Marcin Borkowski
2019-12-04 8:39 ` VanL
2019-12-03 23:12 ` Marcin Borkowski
2019-12-05 4:41 ` Richard Stallman
2019-12-06 6:51 ` VanL
2019-12-06 20:13 ` Marcin Borkowski
2019-12-06 23:58 ` VanL
2019-12-02 5:41 ` Richard Stallman
2019-12-02 12:53 ` Marcin Borkowski
2019-12-02 18:07 ` Stefan Monnier
2019-12-02 20:57 ` Marcin Borkowski
2019-12-02 21:19 ` Stefan Monnier
2019-12-02 22:13 ` Marcin Borkowski
2019-12-02 22:41 ` Stefan Monnier
2019-12-02 23:04 ` Marcin Borkowski
2019-12-03 0:20 ` Stefan Monnier
2019-12-03 23:26 ` Marcin Borkowski
2019-12-03 8:37 ` VanL
2019-12-03 10:14 ` Marcin Borkowski
2019-12-03 11:14 ` VanL
2019-12-05 4:44 ` Richard Stallman
2019-12-05 7:30 ` Elias Mårtenson
2019-12-06 4:11 ` Richard Stallman
2019-12-07 2:21 ` Elias Mårtenson
2019-12-08 5:06 ` Librepay Richard Stallman
2019-12-08 12:10 ` Librepay VanL
2019-12-03 5:03 ` Some ideas with Emacs Richard Stallman
2019-12-03 4:58 ` Richard Stallman
2019-12-04 0:37 ` Marcin Borkowski
2019-12-05 4:41 ` Richard Stallman
2020-05-11 19:37 ` Marcin Borkowski
2020-06-03 4:25 ` Richard Stallman
2019-11-29 11:37 ` Stefan Kangas
2019-11-29 11:59 ` Anonymous
2019-11-29 12:31 ` Emacs: the Editor for the Next Forty Years (was Re: Some ideas with Emacs) Juanma Barranquero
2019-11-29 13:22 ` Some ideas with Emacs Eli Zaretskii
2019-11-29 13:34 ` Stefan Kangas
2019-11-29 13:56 ` Eduardo Ochs
2019-11-29 14:13 ` Eli Zaretskii
2019-11-29 14:26 ` Anonymous
2019-11-30 3:51 ` Stefan Kangas
2019-12-01 3:14 ` Emanuel Berg via Emacs development discussions.
2019-11-29 15:36 ` Stefan Monnier
2019-11-29 18:58 ` Michael Albinus
2019-11-29 19:13 ` Stefan Monnier [this message]
2019-11-29 19:30 ` Adding examples in the doc (was: Some ideas with Emacs) Yuan Fu
2019-11-29 20:03 ` Adding examples in the doc Michael Albinus
2019-11-29 19:32 ` Some ideas with Emacs Eli Zaretskii
2019-11-29 20:09 ` Michael Albinus
2019-11-29 20:14 ` Eli Zaretskii
2019-11-29 20:25 ` Michael Albinus
2019-11-29 20:30 ` Eli Zaretskii
2019-12-01 6:25 ` Emanuel Berg via Emacs development discussions.
2019-12-01 7:35 ` Eduardo Ochs
2019-12-01 10:21 ` Michael Albinus
2019-12-01 6:19 ` Emanuel Berg via Emacs development discussions.
2019-11-29 21:42 ` Clément Pit-Claudel
2019-11-30 0:12 ` João Távora
2019-12-01 6:48 ` Emanuel Berg via Emacs development discussions.
2019-12-01 17:30 ` Eli Zaretskii
2019-11-30 0:44 ` Yuan Fu
2019-11-30 4:00 ` Stefan Kangas
2019-11-30 7:19 ` Eli Zaretskii
2019-11-30 7:05 ` Eli Zaretskii
2019-12-01 6:51 ` Emanuel Berg via Emacs development discussions.
2019-12-01 17:32 ` Eli Zaretskii
2019-12-01 18:25 ` Emanuel Berg via Emacs development discussions.
2019-12-01 19:44 ` Michael Welsh Duggan
2019-12-01 20:48 ` Eli Zaretskii
2019-12-01 21:35 ` Emanuel Berg via Emacs development discussions.
2019-12-02 3:32 ` Eli Zaretskii
2019-12-02 4:17 ` Emanuel Berg via Emacs development discussions.
2019-12-02 4:48 ` Yuan Fu
2019-12-02 4:53 ` Emanuel Berg via Emacs development discussions.
2019-12-02 15:57 ` Michael Albinus
2019-12-01 22:20 ` Michael Welsh Duggan
2019-12-01 22:46 ` Emanuel Berg via Emacs development discussions.
2019-12-01 6:46 ` Emanuel Berg via Emacs development discussions.
2019-12-01 3:21 ` Emanuel Berg via Emacs development discussions.
2019-12-01 6:04 ` Richard Stallman
2019-12-01 6:15 ` Emanuel Berg via Emacs development discussions.
2019-12-01 6:05 ` Richard Stallman
2019-11-29 15:43 ` Stefan Monnier
2019-11-29 16:04 ` Robert Pluim
2019-11-30 11:21 ` Emanuel Berg via Emacs development discussions.
2019-12-01 2:41 ` VanL
2019-12-01 18:05 ` Stefan Monnier
2019-12-01 18:36 ` Emanuel Berg via Emacs development discussions.
2019-12-03 6:07 ` Ag Ibragimov
2019-12-06 18:30 ` Marcin Borkowski
2019-12-06 19:18 ` Juanma Barranquero
2019-12-06 20:14 ` Marcin Borkowski
2019-12-06 21:22 ` Stefan Monnier
2019-12-06 21:26 ` Juanma Barranquero
2019-12-07 2:13 ` Ag Ibragimov
2019-12-07 3:14 ` Drew Adams
2019-12-10 20:55 ` Marcin Borkowski
2019-12-11 4:21 ` VanL
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=jwvd0damrmy.fsf-monnier+emacs@gnu.org \
--to=monnier@iro.umontreal.ca \
--cc=c4droid@foxmail.com \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=michael.albinus@gmx.de \
--cc=stefan@marxist.se \
/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).