From: Eli Zaretskii <eliz@gnu.org>
To: Dmitry Gutov <dgutov@yandex.ru>
Cc: rgm@gnu.org, michael.albinus@gmx.de, emacs-devel@gnu.org
Subject: Re: Docstrings and manuals
Date: Sun, 17 Apr 2016 18:14:45 +0300 [thread overview]
Message-ID: <83y48c9sii.fsf@gnu.org> (raw)
In-Reply-To: <149a61a2-d812-5ae1-d969-d4201872e870@yandex.ru> (message from Dmitry Gutov on Sun, 17 Apr 2016 16:12:05 +0300)
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 17 Apr 2016 16:12:05 +0300
> Cc: Glenn Morris <rgm@gnu.org>, emacs-devel <emacs-devel@gnu.org>
>
> My problem is that you stated the lack of a manual as the reason for
> your lack of understanding of VC's internals. I'm saying the problem is
> them being documented insufficiently in the code. And, like I mentioned,
> if you go ahead and write the newfound revelations in the manual, but
> not anywhere else, a certain slice of developers is going to miss out.
yes, we should update both the doc strings and the manual(s).
> To put a different spin on my statement earlier: if neither the
> docstrings, nor the manual are considered the Single Source of Truth, to
> read a reasonably complete description of a function, I'd have to read
> both the docstring and the manual. And that's just wasteful.
>
> And even the personal preferences aside, we can't make the manual to be
> the SSOT because most functions are not documented there.
The doc strings and the manual should convey the same information,
where they both cover the same turf.
next prev parent reply other threads:[~2016-04-17 15:14 UTC|newest]
Thread overview: 53+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <6ok2vyzwf9.fsf@fencepost.gnu.org>
[not found] ` <08f70cda-44be-0657-e50a-2b2c80d2c21c@yandex.ru>
[not found] ` <87oa9dzgl0.fsf@gmx.de>
[not found] ` <bbdc2630-f791-dace-15d0-c1e73d8c88fc@yandex.ru>
[not found] ` <87potshczh.fsf@gmx.de>
[not found] ` <e3132bc6-f1d4-ebef-00d4-93fa0807fea0@yandex.ru>
[not found] ` <87h9f4ghzg.fsf@gmx.de>
[not found] ` <ec924912-8098-c824-0583-bed1e7150074@yandex.ru>
[not found] ` <8737qnc8ep.fsf@gmx.de>
2016-04-17 0:17 ` Docstrings and manuals, was: Re: bug#20637: incompatible, undocumented change to vc-working-revision Dmitry Gutov
2016-04-17 8:49 ` Docstrings and manuals Michael Albinus
2016-04-17 10:50 ` Dmitry Gutov
2016-04-17 11:16 ` Michael Albinus
2016-04-17 11:42 ` Dmitry Gutov
2016-04-17 12:19 ` Michael Albinus
2016-04-17 13:12 ` Dmitry Gutov
2016-04-17 15:14 ` Eli Zaretskii [this message]
2016-04-17 16:39 ` Michael Albinus
2016-04-17 19:39 ` Dmitry Gutov
2016-04-17 15:12 ` Eli Zaretskii
2016-04-17 19:59 ` Dmitry Gutov
2016-04-18 2:30 ` Eli Zaretskii
2016-04-18 12:55 ` Phillip Lord
2016-04-18 15:35 ` Marcin Borkowski
2016-04-18 15:47 ` Stefan Monnier
2016-04-18 16:30 ` Marcin Borkowski
2016-04-18 18:56 ` Eli Zaretskii
2016-04-18 19:33 ` Stefan Monnier
2016-04-18 19:39 ` Eli Zaretskii
[not found] ` <<83ziss9sml.fsf@gnu.org>
2016-04-17 15:54 ` Drew Adams
2016-04-17 15:03 ` Eli Zaretskii
2016-04-17 15:15 ` Dmitry Gutov
2016-04-17 16:23 ` Eli Zaretskii
2016-04-17 20:22 ` Dmitry Gutov
2016-04-18 2:33 ` Eli Zaretskii
2016-04-18 8:38 ` Richard Stallman
2016-04-18 9:50 ` Dmitry Gutov
2016-04-19 0:25 ` Richard Stallman
2016-04-19 7:59 ` Dmitry Gutov
2016-04-19 23:51 ` Richard Stallman
2016-04-18 14:55 ` vc-state and unregistered (was: bug#20637: incompatible, undocumented change to vc-working-revision) Michael Albinus
2016-04-18 21:11 ` vc-state and unregistered Dmitry Gutov
2016-04-19 8:10 ` Michael Albinus
2016-04-19 8:21 ` Dmitry Gutov
2016-04-19 8:31 ` Michael Albinus
2016-04-19 8:43 ` Dmitry Gutov
2016-04-24 12:11 ` Michael Albinus
2016-04-24 12:21 ` Dmitry Gutov
2016-04-24 12:45 ` Michael Albinus
2016-04-24 12:49 ` Dmitry Gutov
2016-04-24 13:07 ` Michael Albinus
2016-04-24 13:13 ` Dmitry Gutov
2016-04-24 13:24 ` Michael Albinus
2016-04-24 13:27 ` Dmitry Gutov
2016-04-24 14:03 ` Michael Albinus
2016-04-24 17:23 ` Dmitry Gutov
2016-04-24 17:35 ` Dmitry Gutov
2016-04-24 18:13 ` Michael Albinus
2016-04-24 18:58 ` Dmitry Gutov
2016-04-24 19:41 ` Michael Albinus
2016-04-24 20:43 ` Dmitry Gutov
2016-04-24 13:08 ` Dmitry Gutov
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=83y48c9sii.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=dgutov@yandex.ru \
--cc=emacs-devel@gnu.org \
--cc=michael.albinus@gmx.de \
--cc=rgm@gnu.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).