From: Michael Albinus <michael.albinus@gmx.de>
To: Dmitry Gutov <dgutov@yandex.ru>
Cc: Glenn Morris <rgm@gnu.org>, emacs-devel <emacs-devel@gnu.org>
Subject: Re: Docstrings and manuals
Date: Sun, 17 Apr 2016 18:39:18 +0200 [thread overview]
Message-ID: <87h9f02nrd.fsf@gmx.de> (raw)
In-Reply-To: <149a61a2-d812-5ae1-d969-d4201872e870@yandex.ru> (Dmitry Gutov's message of "Sun, 17 Apr 2016 16:12:05 +0300")
Dmitry Gutov <dgutov@yandex.ru> writes:
> 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.
>
> To expand on my message in
> http://debbugs.gnu.org/cgi/bugreport.cgi?bug=20637#91, an example:
>
> If we make a decision that vc-BACKEND-state can rely on FILE not
> having state `unregistered' (I'm not saying we should; it's just one
> option), that information should go into the Commentary at the top of
> vc.el (probably into the description of the `state' command), but...
So we are in agreement :-)
Of course, every relevant documentation must be up-to-date. Docstring,
commentary section, manual.
Personally, I believe a commentary section is a poor man's manual. Once
the information is in the manual, the commentary section is not needed
anymore. But this is nothing we need to worry about just now; let's
discuss it once a proper manual entry about vc exist.
Best regards, Michael.
next prev parent reply other threads:[~2016-04-17 16:39 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
2016-04-17 16:39 ` Michael Albinus [this message]
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=87h9f02nrd.fsf@gmx.de \
--to=michael.albinus@gmx.de \
--cc=dgutov@yandex.ru \
--cc=emacs-devel@gnu.org \
--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).