From: Drew Adams <drew.adams@oracle.com>
To: Stephen Leake <stephen_leake@stephe-leake.org>,
emacs-devel <emacs-devel@gnu.org>
Subject: RE: docstrings and elisp reference
Date: Tue, 6 Jun 2017 13:36:33 -0700 (PDT) [thread overview]
Message-ID: <7acc7d4f-23cc-4b6a-b062-ef92805e465b@default> (raw)
In-Reply-To: <86lgp4q2xa.fsf@stephe-leake.org>
> >> Having a mechanism that generates automatic documentation (a la
> >> javadoc) would be extremely valuable.
> >
> > It could be valuable, but IMO only if we exercise a lot of discipline
> > in producing those comments. Because every project which uses this
> > methodology that I looked at ends up providing _abysmally_ inadequate
> > documentation.
>
> +1
>
> Doc strings are for short reference information for single
> functions/variables.
>
> texinfo docs are for more indepth explanations of several related
> functions/features.
>
> They are complementary; they should not duplicate each other.
Yes.
And this is not JavaDoc. The Elisp manual is not purely
and simply an API reference manual.
And now this question is being rehashed again. Everything
said this time around has already been said before. Please
consult the previous thread, which was already cited.
(If you feel you really have something *new* to say, feel free.)
next prev parent reply other threads:[~2017-06-06 20:36 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 [this message]
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
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=7acc7d4f-23cc-4b6a-b062-ef92805e465b@default \
--to=drew.adams@oracle.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 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.