From: Richard Stallman <rms@gnu.org>
To: "Etienne Prud’homme" <e.e.f.prudhomme@gmail.com>
Cc: stephen_leake@stephe-leake.org, drew.adams@oracle.com,
emacs-devel@gnu.org
Subject: Re: docstrings and elisp reference
Date: Fri, 09 Jun 2017 23:19:48 -0400 [thread overview]
Message-ID: <E1dJWwG-0004HR-6Q@fencepost.gnu.org> (raw)
In-Reply-To: <877f0ln3dx.fsf@x230.lts> (message from Etienne Prud’homme on Fri, 09 Jun 2017 01:20:26 -0400)
[[[ To any NSA and FBI agents reading my email: please consider ]]]
[[[ whether defending the US Constitution against all enemies, ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> Emacs Lisp doc strings have support for some of JavaDoc features, but
> cannot compare in many things. Many things described in doc strings are
> informal and are pretty difficult to extract. For example, we have no
> formal way of telling:
> - the type of the function return value
> - what exceptions can be thrown from the function
> - does this function has side effects
> - since when it was introduced
> - it’s a hook variable
> - if the comment includes a file system path in the example
What this amounts to is that they are basically similar
but JavaDoc has additional features.
Those that make sense to add, we can add to the doc strings.
> - the type of the function return value
That is not crucial in Lisp the way it is in Java.
Unlike Java, Lisp does not declare or limit the type of any values.
In some cases we document what the type will actually be,
using English text.
> - what exceptions can be thrown from the function
In general, there is no limit to what exceptions can be thrown.
In Lisp, that is dynamic.
> - does this function has side effects
In general, any Lisp function can have side effects.
We could define a more systematic way to indicate in doc strings that a
certain function has no side effects, that you can assume it preserves
the current buffer, or that it preserves the search results.
And whatever else could be useful.
> - since when it was introduced
That does not seem important to me.
> - it’s a hook variable
We could define a systematic way to indicate this in doc strings.
> - if the comment includes a file system path in the example
I don't understand what that means.
--
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.
next prev parent reply other threads:[~2017-06-10 3:19 UTC|newest]
Thread overview: 72+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-06-05 21:26 docstrings and elisp reference Jean-Christophe Helary
2017-06-06 0:09 ` Tino Calancha
2017-06-06 5:10 ` Jean-Christophe Helary
2017-06-06 15:03 ` Eli Zaretskii
2017-06-06 20:25 ` Stephen Leake
2017-06-06 20:36 ` Drew Adams
2017-06-08 2:29 ` Etienne Prud’homme
2017-06-08 3:48 ` Jean-Christophe Helary
2017-06-08 5:39 ` Chad Brown
2017-06-08 8:12 ` Jean-Christophe Helary
2017-06-08 15:11 ` Eli Zaretskii
2017-06-08 15:42 ` Jean-Christophe Helary
2017-06-09 0:25 ` Chad Brown
2017-06-08 18:29 ` Etienne Prud’homme
2017-06-09 4:10 ` Richard Stallman
2017-06-08 15:18 ` Eli Zaretskii
2017-06-08 18:10 ` Etienne Prud’homme
2017-06-08 19:14 ` Eli Zaretskii
2017-06-08 20:07 ` Drew Adams
2017-06-08 20:22 ` Etienne Prud’homme
2017-06-08 22:44 ` Jean-Christophe Helary
2017-06-09 4:10 ` Richard Stallman
2017-06-09 5:20 ` Etienne Prud’homme
2017-06-09 7:08 ` Eli Zaretskii
2017-06-09 8:27 ` Yuri Khan
2017-06-09 9:38 ` Eli Zaretskii
2017-06-09 12:21 ` Eli Zaretskii
2017-06-09 12:32 ` Yuri Khan
2017-06-09 13:46 ` Eli Zaretskii
2017-06-09 19:24 ` Etienne Prud’homme
2017-06-10 1:06 ` Jean-Christophe Helary
2017-06-10 11:36 ` Nikolay Kudryavtsev
2017-06-10 14:26 ` Drew Adams
2017-06-10 3:19 ` Richard Stallman [this message]
2017-06-10 7:31 ` Eli Zaretskii
2017-06-11 2:43 ` Richard Stallman
2017-06-11 2:44 ` Richard Stallman
2017-06-11 15:18 ` Stefan Monnier
2017-06-12 2:52 ` Richard Stallman
2017-06-12 3:27 ` Stefan Monnier
2017-06-13 3:25 ` Richard Stallman
2017-06-10 8:22 ` Yuri Khan
2017-06-10 3:19 ` Richard Stallman
2017-06-06 20:45 ` Joost Kremers
2017-06-07 13:03 ` Stefan Monnier
2017-06-07 13:23 ` Yuri Khan
2017-06-07 13:31 ` Stefan Monnier
2017-06-07 14:18 ` Drew Adams
2017-06-07 15:43 ` Eli Zaretskii
2017-06-06 20:47 ` Dmitry Gutov
2017-06-06 21:21 ` Drew Adams
2017-06-06 21:50 ` Dmitry Gutov
2017-06-07 5:28 ` Eli Zaretskii
2017-06-17 12:46 ` Dmitry Gutov
2017-06-17 13:04 ` Alan Mackenzie
2017-06-17 13:55 ` Dmitry Gutov
2017-06-17 20:14 ` Alan Mackenzie
2017-06-18 2:32 ` Eli Zaretskii
2017-06-18 19:52 ` Richard Stallman
2017-06-17 22:13 ` Richard Stallman
2017-06-20 18:05 ` John Wiegley
2017-06-17 14:10 ` Eli Zaretskii
2017-06-17 15:13 ` Stefan Monnier
2017-06-17 18:59 ` Paul Eggert
2017-06-17 14:52 ` Drew Adams
2017-06-19 18:31 ` Thien-Thi Nguyen
2017-06-07 14:05 ` Drew Adams
2017-06-07 14:27 ` Drew Adams
2017-06-08 1:27 ` Richard Stallman
2017-06-06 22:42 ` Richard Stallman
2017-06-06 22:49 ` Dmitry Gutov
2017-06-07 5:20 ` Eli Zaretskii
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=E1dJWwG-0004HR-6Q@fencepost.gnu.org \
--to=rms@gnu.org \
--cc=drew.adams@oracle.com \
--cc=e.e.f.prudhomme@gmail.com \
--cc=emacs-devel@gnu.org \
--cc=stephen_leake@stephe-leake.org \
/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).