Docstrings and manuals, was: Re: bug#20637: incompatible, undocumented change to vc-working-revision

Docstrings and manuals, was: Re: bug#20637: incompatible, undocumented change to vc-working-revision

[Dmitry Gutov]

On 04/15/2016 04:23 PM, Michael Albinus wrote:

>> I disagree. The manual is the documentation for the users, to explain
>> in depth, give examples, et cetera. The docstrings and VC's internal
>> documentation have to stand on their own. It would be silly if the
>> difference between `vc-backend' and `vc-responsible-backend' were to
>> only be explained in the manual, but not in the docstrings.
>
> Are we speaking about different manuals? I'm speaking about the ‘GNU
> Emacs Lisp Reference Manual’, and not the ‘GNU Emacs Manual’ (the manual
> dedicated to users).

OK, so the Emacs Lisp Reference is a counter-example. And it contains a 
narrative that explains different aspects of Emacs Lisp in a sort-of 
seamless fashion, which is great, because there's no good way to do that 
with just docstrings.

And then it goes ahead and provides its own versions of descriptions for 
functions and variables that are different from the docstrings, and are 
often longer, but sometimes shorter (e.g. for `obarray'), and at times 
it seems like the only reasons for the existence of the two versions is 
to have docstrings in the imperative voice, and the pieces of text in 
the manual, in the passive voice.

And then the two versions start to diverge. For instance, the docstring 
for `mapatoms' is rather short. The manual entry for it is longer, *and* 
it documents that `mapatoms' returns nil. Why would someone put that 
piece of information into the manual, but not the docstring, is beyond me.

So, to be clear, I dislike the ambiguity that manuals that try to be 
all-encompassing, like this one, create about the main source of 
information about each function.

Re: Docstrings and manuals

[Michael Albinus]

Dmitry Gutov <dgutov@yandex.ru> writes:

> So, to be clear, I dislike the ambiguity that manuals that try to be
> all-encompassing, like this one, create about the main source of
> information about each function.

We will always find examples where the entries in the manual are
inferior, compared with the docstring. We will also find examples with
incompatible information in the docstring and the manual.

This does not mean that manuals are useless. It only means, that there's
a bug to be fixed.

Best regards, Michael.

Re: Docstrings and manuals

[Dmitry Gutov]

On 04/17/2016 11:49 AM, Michael Albinus wrote:

> We will always find examples where the entries in the manual are
> inferior, compared with the docstring. We will also find examples with
> incompatible information in the docstring and the manual.

The `mapatoms' manual entry is neither. And yet, wouldn't you agree that 
it's problematic?

> This does not mean that manuals are useless. It only means, that there's
> a bug to be fixed.

Sure. But I think that means that we should have a policy that the 
manual is secondary to the information contained in the source files. 
Right now, I have no idea which one is supposed to be the primary source 
of truth.

Re: Docstrings and manuals

[Michael Albinus]

Dmitry Gutov <dgutov@yandex.ru> writes:

>> This does not mean that manuals are useless. It only means, that there's
>> a bug to be fixed.
>
> Sure. But I think that means that we should have a policy that the
> manual is secondary to the information contained in the source
> files. Right now, I have no idea which one is supposed to be the
> primary source of truth.

No primary or secondary. If docstring and manual are inconsistent, it is
a bug which must be fixed. There is no automatism that the docstring is
always right, and the manual is wrong in this case. It could be also
vice versa.

See also the Elisp Manual (info "(elisp)Caveats")

--8<---------------cut here---------------start------------->8---
   The manual should be fully correct in what it does cover, and it is
therefore open to criticism on anything it says—from specific examples
and descriptive text, to the ordering of chapters and sections.  If
something is confusing, or you find that you have to look at the sources
or experiment to learn something not covered in the manual, then perhaps
the manual should be fixed.  Please let us know.
--8<---------------cut here---------------end--------------->8---

Best regards, Michael.

Re: Docstrings and manuals

[Dmitry Gutov]

On 04/17/2016 02:16 PM, Michael Albinus wrote:

> No primary or secondary. If docstring and manual are inconsistent, it is
> a bug which must be fixed.

What's "inconsistent" in this case? They are almost always different.

> There is no automatism that the docstring is
> always right, and the manual is wrong in this case. It could be also
> vice versa.

Wouldn't it be better if we had this "automatism"?

> See also the Elisp Manual (info "(elisp)Caveats")
>
> --8<---------------cut here---------------start------------->8---
>    The manual should be fully correct in what it does cover, and it is
> therefore open to criticism on anything it says—from specific examples
> and descriptive text, to the ordering of chapters and sections.  If
> something is confusing, or you find that you have to look at the sources
> or experiment to learn something not covered in the manual, then perhaps
> the manual should be fixed.  Please let us know.
> --8<---------------cut here---------------end--------------->8---

I'm not arguing in favor of leaving mistakes in the manual. But I think 
it should be strictly a derivative work. I.e. the docstrings must 
contain the complete information (if maybe presented in a terse 
fashion), and the manual could rephrase that, only to make it more 
accessible (but not more informative).

Re: Docstrings and manuals

[Michael Albinus]

Dmitry Gutov <dgutov@yandex.ru> writes:

> I'm not arguing in favor of leaving mistakes in the manual. But I
> think it should be strictly a derivative work. I.e. the docstrings
> must contain the complete information (if maybe presented in a terse
> fashion), and the manual could rephrase that, only to make it more
> accessible (but not more informative).

I still don't understand what problem you discuss. There are docstrings,
and there are manuals. Both have their reasons to exist.

What do you want else? Nobody urges you to read the manuals, if you
don't want.

I believe it would be good if vc-* functions are covered in a
manual. What is the problem with this?

Best regards, Michael.

Re: Docstrings and manuals

[Dmitry Gutov]

On 04/17/2016 03:19 PM, Michael Albinus wrote:
> Dmitry Gutov <dgutov@yandex.ru> writes:
>
>> I'm not arguing in favor of leaving mistakes in the manual. But I
>> think it should be strictly a derivative work. I.e. the docstrings
>> must contain the complete information (if maybe presented in a terse
>> fashion), and the manual could rephrase that, only to make it more
>> accessible (but not more informative).
>
> I still don't understand what problem you discuss. There are docstrings,
> and there are manuals. Both have their reasons to exist.

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...

> I believe it would be good if vc-* functions are covered in a
> manual. What is the problem with this?

...if it also finds its way into a manual later, I don't see any harm.

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.

Re: Docstrings and manuals

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 17 Apr 2016 13:50:35 +0300
> Cc: Glenn Morris <rgm@gnu.org>, emacs-devel <emacs-devel@gnu.org>
> 
> On 04/17/2016 11:49 AM, Michael Albinus wrote:
> 
> > We will always find examples where the entries in the manual are
> > inferior, compared with the docstring. We will also find examples with
> > incompatible information in the docstring and the manual.
> 
> The `mapatoms' manual entry is neither. And yet, wouldn't you agree that 
> it's problematic?

If you mean that mapatoms' doc string is too terse and omits some
details it shouldn't, I agree.  Otherwise, I'm not sure what you mean;
please elaborate.

> > This does not mean that manuals are useless. It only means, that there's
> > a bug to be fixed.
> 
> Sure. But I think that means that we should have a policy that the 
> manual is secondary to the information contained in the source files. 

No, it's not secondary.  It should be an expanded and augmented
version of the same information.

> Right now, I have no idea which one is supposed to be the primary source 
> of truth.

Both.  There's more than one way to tell the truth.

Re: Docstrings and manuals

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 17 Apr 2016 14:42:28 +0300
> Cc: Glenn Morris <rgm@gnu.org>, emacs-devel <emacs-devel@gnu.org>
> 
> On 04/17/2016 02:16 PM, Michael Albinus wrote:
> 
> > No primary or secondary. If docstring and manual are inconsistent, it is
> > a bug which must be fixed.
> 
> What's "inconsistent" in this case? They are almost always different.

They can be different, but still consistent.  There's more than one
way to tell the same story, without contradicting the others.

> > There is no automatism that the docstring is
> > always right, and the manual is wrong in this case. It could be also
> > vice versa.
> 
> Wouldn't it be better if we had this "automatism"?

No, not IMO.

> I'm not arguing in favor of leaving mistakes in the manual. But I think 
> it should be strictly a derivative work. I.e. the docstrings must 
> contain the complete information (if maybe presented in a terse 
> fashion), and the manual could rephrase that, only to make it more 
> accessible (but not more informative).

Once you allow rephrasing, you already allow deviation.  And there
really is no way around allowing it, because a manual that includes
only the doc strings with a minimum "glue" is much less palatable.
You can look at Guile as one example; GnuTLS is another.  Such manuals
are much less useful, IME, than what we have in Emacs.

One thing that you will never find in doc strings is a discussion of
merits and demerits of different ways of solving some problem,
especially if such a discussion requires to jump back and forth
between these ways, in order to make some point.

IOW, writing a good manual is still a human activity that cannot be
easily automated.  Ideally, doc strings should be phrased like
reference material, covering all the traits as tersely as possible,
while the manual should provide an easier reading with more continuity
text and even some explanations why things are the way they are.  At
least IMO.

Re: Docstrings and manuals

[Eli Zaretskii]

> 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.

Re: Docstrings and manuals

[Dmitry Gutov]

On 04/17/2016 06:03 PM, Eli Zaretskii wrote:

>> The `mapatoms' manual entry is neither. And yet, wouldn't you agree that
>> it's problematic?
>
> If you mean that mapatoms' doc string is too terse and omits some
> details it shouldn't, I agree.  Otherwise, I'm not sure what you mean;
> please elaborate.

That someone saw fit to put "Then it returns ‘nil’" into the manual when 
it's not in the docstring. And that it's easy to make such a mistake.

>> Sure. But I think that means that we should have a policy that the
>> manual is secondary to the information contained in the source files.
>
> No, it's not secondary.  It should be an expanded and augmented
> version of the same information.

Either you're saying the same as me (when writing a manual, you 
elaborate, but not add new essential new information, and thus make a 
derivative), or I don't understand how to produce the manual entries.

> Both.  There's more than one way to tell the truth.

Both of them are necessarily fallible, it seems.

RE: Docstrings and manuals

[Drew Adams]

> > > No primary or secondary. If docstring and manual are inconsistent, it
> > > is a bug which must be fixed.
> >
> > What's "inconsistent" in this case? They are almost always different.
> 
> They can be different, but still consistent.  There's more than one
> way to tell the same story, without contradicting the others.
> 
> > > There is no automatism that the docstring is
> > > always right, and the manual is wrong in this case. It could be also
> > > vice versa.
> >
> > Wouldn't it be better if we had this "automatism"?
> 
> No, not IMO.
> 
> > I'm not arguing in favor of leaving mistakes in the manual. But I think
> > it should be strictly a derivative work. I.e. the docstrings must
> > contain the complete information (if maybe presented in a terse
> > fashion), and the manual could rephrase that, only to make it more
> > accessible (but not more informative).
> 
> Once you allow rephrasing, you already allow deviation.  And there
> really is no way around allowing it, because a manual that includes
> only the doc strings with a minimum "glue" is much less palatable.
> You can look at Guile as one example; GnuTLS is another.  Such manuals
> are much less useful, IME, than what we have in Emacs.
> 
> One thing that you will never find in doc strings is a discussion of
> merits and demerits of different ways of solving some problem,
> especially if such a discussion requires to jump back and forth
> between these ways, in order to make some point.
> 
> IOW, writing a good manual is still a human activity that cannot be
> easily automated.  Ideally, doc strings should be phrased like
> reference material, covering all the traits as tersely as possible,
> while the manual should provide an easier reading with more continuity
> text and even some explanations why things are the way they are.  At
> least IMO.

+10 to what Eli and Michael are saying.

Neither doc string nor manual serves the purpose of
the other.  The manual is not Javadoc.

It is up to humans to write the most appropriate text
for each, and to make coherent any differences in
message or presentation.

Differences should be based on the context (including
readers) and should not involve contradiction in
meaning (semantics, behavior) of the things described.

IOW, both need to be faithful descriptions of those
things.  There can be differences in degree of
abstraction or of precision.  But within a given level
of abstraction/precision, each must be a faithful
picture of the behavior it describes.

The same is true of any other communication about these
things to users, including tooltips and error messages:
The behavior/meaning of the program being described is
the same, and that needs to be reflected in a lack of
contradiction wrt description of that behavior/meaning.

Re: Docstrings and manuals

[Eli Zaretskii]

> Cc: michael.albinus@gmx.de, rgm@gnu.org, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 17 Apr 2016 18:15:17 +0300
> 
> On 04/17/2016 06:03 PM, Eli Zaretskii wrote:
> 
> >> The `mapatoms' manual entry is neither. And yet, wouldn't you agree that
> >> it's problematic?
> >
> > If you mean that mapatoms' doc string is too terse and omits some
> > details it shouldn't, I agree.  Otherwise, I'm not sure what you mean;
> > please elaborate.
> 
> That someone saw fit to put "Then it returns ‘nil’" into the manual when 
> it's not in the docstring. And that it's easy to make such a mistake.

Making mistakes is always easier than avoiding them.  I don't think
this fact is significant.

> >> Sure. But I think that means that we should have a policy that the
> >> manual is secondary to the information contained in the source files.
> >
> > No, it's not secondary.  It should be an expanded and augmented
> > version of the same information.
> 
> Either you're saying the same as me (when writing a manual, you 
> elaborate, but not add new essential new information, and thus make a 
> derivative), or I don't understand how to produce the manual entries.

To produce a good manual text, you need to try to describe and explain
the subject in some logical way.  The result is not a derivative, in
that it doesn't necessarily repeat the doc strings and then adds some
more stuff (although doing that is sometimes TRT).  It could be that
most of the text of the manual section has no direct relation at all
to the doc strings.  It could even be an entirely different POV of
looking at the subject.  E.g., compare the node "Generic Functions" in
the ELisp manual with the doc strings of the symbols covered by that
node.  As an even more extreme example, compare the node
"Bidirectional Editing" in the user manual with the doc strings of the
3 variables it covers.

> > Both.  There's more than one way to tell the truth.
> 
> Both of them are necessarily fallible, it seems.

Of course.  "To err is human".

Re: Docstrings and manuals

[Michael Albinus]

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.

Re: Docstrings and manuals

[Dmitry Gutov]

On 04/17/2016 07:39 PM, Michael Albinus wrote:

> So we are in agreement :-)

Kind of. I disagree that "writing the manual" is going to solve any of 
the pressing problems, but it is a valid activity to partake in.

> Personally, I believe a commentary section is a poor man's manual.

Yes and no. It's certainly easier to navigate, at least while it's below 
a certain size (which is still true of vc.el's Commentary).

> 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.

...so I have my reservations about replacing it. But yes, we can discuss 
it later.

Re: Docstrings and manuals

[Dmitry Gutov]

On 04/17/2016 06:12 PM, Eli Zaretskii wrote:

> Once you allow rephrasing, you already allow deviation.  And there
> really is no way around allowing it, because a manual that includes
> only the doc strings with a minimum "glue" is much less palatable.
> You can look at Guile as one example; GnuTLS is another.  Such manuals
> are much less useful, IME, than what we have in Emacs.

I'd rather minimize rephrasing in the manuals, while still allowing the 
"glue" text. Instead of having two ways to describe each important 
variable, I'd rather have just the docstrings, which could be adjusted 
to be more approachable. That would require some new Texinfo syntax to 
"insert the docstring here".

The narrative can still be free-form, but at least there would be one 
fewer source of duplication.

> One thing that you will never find in doc strings is a discussion of
> merits and demerits of different ways of solving some problem,
> especially if such a discussion requires to jump back and forth
> between these ways, in order to make some point.

The counterpart to "glue" text outside of the manuals is the Commentary 
section usually. While they're also terse usually (but not always), they 
aren't bound by the limitation that a docstring has to relate to a 
particular symbol.

> IOW, writing a good manual is still a human activity that cannot be
> easily automated.  Ideally, doc strings should be phrased like
> reference material, covering all the traits as tersely as possible,
> while the manual should provide an easier reading with more continuity
> text and even some explanations why things are the way they are.  At
> least IMO.

That sounds fine, and maybe this way is best for the more complex 
subjects, but in general I'd prefer to see docstrings also written with 
readability in mind. Then, when writing a manual section, you'll only 
need to write the "glue" text, and pick which symbol references, with 
docstrings, to add, and in which order.

Re: Docstrings and manuals

[Dmitry Gutov]

On 04/17/2016 07:23 PM, Eli Zaretskii wrote:

> To produce a good manual text, you need to try to describe and explain
> the subject in some logical way.  The result is not a derivative, in
> that it doesn't necessarily repeat the doc strings and then adds some
> more stuff (although doing that is sometimes TRT).

It should be a derivative in the sense that it's produced based on 
knowing the docstrings and the common context they're used it. But not 
some additional inner details about each symbol that never made it into 
docstrings, I think.

> It could be that
> most of the text of the manual section has no direct relation at all
> to the doc strings.  It could even be an entirely different POV of
> looking at the subject.  E.g., compare the node "Generic Functions" in
> the ELisp manual with the doc strings of the symbols covered by that
> node.  As an even more extreme example, compare the node
> "Bidirectional Editing" in the user manual with the doc strings of the
> 3 variables it covers.

Bidirectional Editing is fine. It describes a facility that's largely 
implemented in C, so the three variables are just a small part of it.

Generic Functions, on the other hand, may be indicative of the problem 
that I've brought up: the descriptions of `cl-defgeneric' and 
`cl-defmethod' and much longer in the manual than their docstrings 
(especially the latter one). I see no particular reason for them to be 
different in this case.

Maybe that will require restructuring the manual text to move the 
enumeration of the possible types (defined in cl--generic-typeof-types) 
to a separate paragraph or section, but that seems only beneficial.

Why would we want to mention that :before methods get called "in the 
most-specific-first order" only in the manual, but not in the docstring? 
And so on.

When a docstring gets too complicated, we can go the way of `cl-loop' 
to, again, avoid repeating ourselves. In that case I at least know to 
consult the manual, and which node to visit.

Re: Docstrings and manuals

[Eli Zaretskii]

> Cc: michael.albinus@gmx.de, rgm@gnu.org, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 17 Apr 2016 22:59:21 +0300
> 
> > IOW, writing a good manual is still a human activity that cannot be
> > easily automated.  Ideally, doc strings should be phrased like
> > reference material, covering all the traits as tersely as possible,
> > while the manual should provide an easier reading with more continuity
> > text and even some explanations why things are the way they are.  At
> > least IMO.
> 
> That sounds fine, and maybe this way is best for the more complex 
> subjects, but in general I'd prefer to see docstrings also written with 
> readability in mind.

This would make them too long ad wordy, something we'd like to avoid,
I think.

Re: Docstrings and manuals

[Eli Zaretskii]

> Cc: michael.albinus@gmx.de, rgm@gnu.org, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 17 Apr 2016 23:22:59 +0300
> 
> Generic Functions, on the other hand, may be indicative of the problem 
> that I've brought up: the descriptions of `cl-defgeneric' and 
> `cl-defmethod' and much longer in the manual than their docstrings 
> (especially the latter one). I see no particular reason for them to be 
> different in this case.

You are looking at the documentation of the specific symbols, while I
invited you to look at the stuff that isn't.  To my mind, that
additional stuff is important for the presentation of the subject as a
whole, and it has no place in the doc strings.

Re: Docstrings and manuals

[Richard Stallman]

[[[ 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. ]]]

  > > If you mean that mapatoms' doc string is too terse and omits some
  > > details it shouldn't, I agree.  Otherwise, I'm not sure what you mean;
  > > please elaborate.

  > That someone saw fit to put "Then it returns ‘nil’" into the manual when 
  > it's not in the docstring. And that it's easy to make such a mistake.

That's not necessarily a flaw.  The fact that mapatoms returns nil is
not very important for using it.  Maybe it is worth mentioning in the
manual but not important enough for the doc string.

-- 
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.

Re: Docstrings and manuals

[Dmitry Gutov]

On 04/18/2016 11:38 AM, Richard Stallman wrote:

> That's not necessarily a flaw.  The fact that mapatoms returns nil is
> not very important for using it.  Maybe it is worth mentioning in the
> manual but not important enough for the doc string.

How come it can be more important to mention in the manual? Returning 
nil is either a part of the function's contract, or not.

Re: Docstrings and manuals

[Phillip Lord]

Eli Zaretskii <eliz@gnu.org> writes:
>> I'm not arguing in favor of leaving mistakes in the manual. But I think 
>> it should be strictly a derivative work. I.e. the docstrings must 
>> contain the complete information (if maybe presented in a terse 
>> fashion), and the manual could rephrase that, only to make it more 
>> accessible (but not more informative).
>
> Once you allow rephrasing, you already allow deviation.  And there
> really is no way around allowing it, because a manual that includes
> only the doc strings with a minimum "glue" is much less palatable.
> You can look at Guile as one example; GnuTLS is another.  Such manuals
> are much less useful, IME, than what we have in Emacs.
>
> One thing that you will never find in doc strings is a discussion of
> merits and demerits of different ways of solving some problem,
> especially if such a discussion requires to jump back and forth
> between these ways, in order to make some point.
>
> IOW, writing a good manual is still a human activity that cannot be
> easily automated.  Ideally, doc strings should be phrased like
> reference material, covering all the traits as tersely as possible,
> while the manual should provide an easier reading with more continuity
> text and even some explanations why things are the way they are.  At
> least IMO.


I think that the two should have a different purpose. I would like more
"tutorial" information in the manual (in the sense of "here is a bit of
code that does something with the functions we are discussing at this
point"), while the docstrings should be the main documentation.

For myself, I think, being able to get to the docstring easily (probably
with a tooltip) from any occurrence of a function or variable in the
manual would be excellent.

Phil

vc-state and unregistered (was: bug#20637: incompatible, undocumented change to vc-working-revision)

[Michael Albinus]

Dmitry Gutov <dgutov@yandex.ru> writes:

Hi Dmitry,

> I don't really see a point in returning `unregistered' from
> `vc-state'. When would the caller treat it differently from nil? And
> returning nil seems like an easier choice, implementation-wise, and
> well as a more conservative one from the backward compatibility
> perspective.

I've checked a little bit more. If we use nil instead of unregistered as
result from vc-state, we cannot use file properties for this function
anymore. nil is meant as "no property set". This would be a regression.

Best regards, Michael.

Re: Docstrings and manuals

[Marcin Borkowski]

On 2016-04-18, at 12:55, Phillip Lord <phillip.lord@russet.org.uk> wrote:

> For myself, I think, being able to get to the docstring easily (probably
> with a tooltip) from any occurrence of a function or variable in the
> manual would be excellent.

Oleh's Lispy does (almost) that with C-1.

> Phil

Hth,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: Docstrings and manuals

[Stefan Monnier]

> I think that the two should have a different purpose. I would like more
> "tutorial" information in the manual (in the sense of "here is a bit of
> code that does something with the functions we are discussing at this
> point"), while the docstrings should be the main documentation.
> For myself, I think, being able to get to the docstring easily (probably
> with a tooltip) from any occurrence of a function or variable in the
> manual would be excellent.

FWIW, I like this idea.  I think we could reduce the amount of
"reference info" in the manual (a part that's already available in the
docstrings) by referring to the docstring instead, and instead increase
the amount of explanation giving tips/examples about how to use it.

This said, the manual was also intended to be used as
a plain-old-burnable book.  So if we decide to reduce the amount of
"reference info" by referring to docstrings, that means we mostly give
up on using lispref as a book and instead we force its use from
within Emacs.  I think it's an acceptable choice, but I wouldn't be
surprised to hear other opinions.


        Stefan

Re: Docstrings and manuals

[Marcin Borkowski]

On 2016-04-18, at 15:47, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> This said, the manual was also intended to be used as
> a plain-old-burnable book.  So if we decide to reduce the amount of
> "reference info" by referring to docstrings, that means we mostly give
> up on using lispref as a book and instead we force its use from
> within Emacs.  I think it's an acceptable choice, but I wouldn't be
> surprised to hear other opinions.

Like mine.  Back in the old days, when I was a student and had a lot of
time, I read most of the Emacs manual.  (Yes, I did it on my computer,
but today I'd probably do it on my ebook reader.  And I have the Elisp
reference on said reader, and I used to read it while commuting some
time ago.  Referring to docstrings would only aggravate me.)

>         Stefan

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

Re: Docstrings and manuals

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Mon, 18 Apr 2016 11:47:17 -0400
> 
> > I think that the two should have a different purpose. I would like more
> > "tutorial" information in the manual (in the sense of "here is a bit of
> > code that does something with the functions we are discussing at this
> > point"), while the docstrings should be the main documentation.
> > For myself, I think, being able to get to the docstring easily (probably
> > with a tooltip) from any occurrence of a function or variable in the
> > manual would be excellent.
> 
> FWIW, I like this idea.  I think we could reduce the amount of
> "reference info" in the manual (a part that's already available in the
> docstrings) by referring to the docstring instead, and instead increase
> the amount of explanation giving tips/examples about how to use it.

Then the manual will be a very awkward reading, even on-line.

To say nothing of the fact that the current doc strings are usually
much worse than the documentation in the manual.

IOW, let's first make sure every changeset is accompanied by good
documentation, and only then consider such significant changes.

Re: Docstrings and manuals

[Stefan Monnier]

>> FWIW, I like this idea.  I think we could reduce the amount of
>> "reference info" in the manual (a part that's already available in the
>> docstrings) by referring to the docstring instead, and instead increase
>> the amount of explanation giving tips/examples about how to use it.
> Then the manual will be a very awkward reading, even on-line.

Maybe we could just change the manual so it's not as
complete-and-definitive, but it's still self-standing (tho with easy
ways to get more details via docstrings).

> To say nothing of the fact that the current doc strings are usually
> much worse than the documentation in the manual.

Docstrings should (ideally) always be as complete as the manual, in the
sense that the actual info is there.  In practice, I find it's usually
the case.  But it's often present in a much rougher shape, indeed, so
you can only figure out that info after reading the manual to figure out
what the docstring really means.

> IOW, let's first make sure every changeset is accompanied by good
> documentation, and only then consider such significant changes.

Agreed,


        Stefan

Re: Docstrings and manuals

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Mon, 18 Apr 2016 15:33:20 -0400
> 
> >> FWIW, I like this idea.  I think we could reduce the amount of
> >> "reference info" in the manual (a part that's already available in the
> >> docstrings) by referring to the docstring instead, and instead increase
> >> the amount of explanation giving tips/examples about how to use it.
> > Then the manual will be a very awkward reading, even on-line.
> 
> Maybe we could just change the manual so it's not as
> complete-and-definitive, but it's still self-standing (tho with easy
> ways to get more details via docstrings).

I think going that way would need a way of inserting doc strings into
the displayed manual, which will require some infrastructure first.
Without having reference material, the manual won't be able to be
self-sufficient.

> > To say nothing of the fact that the current doc strings are usually
> > much worse than the documentation in the manual.
> 
> Docstrings should (ideally) always be as complete as the manual, in the
> sense that the actual info is there.  In practice, I find it's usually
> the case.  But it's often present in a much rougher shape, indeed, so
> you can only figure out that info after reading the manual to figure out
> what the docstring really means.

Indeed, in my experience I frequently need to read the manual to make
sense of the doc string.

Re: vc-state and unregistered

[Dmitry Gutov]

Hi Michael,

On 04/18/2016 05:55 PM, Michael Albinus wrote:

> I've checked a little bit more. If we use nil instead of unregistered as
> result from vc-state, we cannot use file properties for this function
> anymore. nil is meant as "no property set". This would be a regression.

Regression how? We already do exactly that: return `nil' in vc-state to 
mean "unregistered or unknown", and have been doing this for a while.

This is not a significant problem, for two reasons:

- The "unregistered" status is tracked by a different property: 
unregistered files have no backend associated with them. vc-registered 
stores `none' as the value of the file's backend in this case. So we 
don't have vc-git-registered called again and again, even for 
unregistered files.

- If the above scheme is deemed insufficient, we could use the same 
approach for the `vc-state' property.

Re: Docstrings and manuals

[Richard Stallman]

[[[ 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. ]]]

  > How come it can be more important to mention in the manual? Returning 
  > nil is either a part of the function's contract, or not.

We don't divide up the function's behaviors in that all-or-nothing way.

Since the return value is documented in the manual, it is something
we would not change without a good reason.  However, that doesn't mean
it needs to be stated in the doc string.

-- 
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.

Re: Docstrings and manuals

[Dmitry Gutov]

On 04/19/2016 03:25 AM, Richard Stallman wrote:

> Since the return value is documented in the manual, it is something
> we would not change without a good reason.  However, that doesn't mean
> it needs to be stated in the doc string.

That sounds silly to me. At the very least, not mentioning a behavior in 
the docstring makes it easier to violate.

Docstrings are changes together with the code, but we allow deferring 
manual updates.

Re: vc-state and unregistered

[Michael Albinus]

Dmitry Gutov <dgutov@yandex.ru> writes:

> Hi Michael,

Hi Dmitry,

>> I've checked a little bit more. If we use nil instead of unregistered as
>> result from vc-state, we cannot use file properties for this function
>> anymore. nil is meant as "no property set". This would be a regression.
>
> Regression how? We already do exactly that: return `nil' in vc-state
> to mean "unregistered or unknown", and have been doing this for a
> while.

I don't mean this. The problem is how vc caches values. It uses file
properties, and in case `vc-file-getprop' returns nil, it assumes the
property is not cached. Consequently, we can never cache the value nil
for the file property `vc-state'. That is a regression, compared with
caching the value `unregistered'.

Best regards, Michael.

Re: vc-state and unregistered

[Dmitry Gutov]

On 04/19/2016 11:10 AM, Michael Albinus wrote:

> I don't mean this. The problem is how vc caches values. It uses file
> properties, and in case `vc-file-getprop' returns nil, it assumes the
> property is not cached. Consequently, we can never cache the value nil
> for the file property `vc-state'.

Which part of this hasn't been addressed in my previous email?

What are the practical problems that you anticipate?

> That is a regression, compared with
> caching the value `unregistered'.

We've never returned that value anyway. And as such, never cached it. So 
it wouldn't be a regression.

Re: vc-state and unregistered

[Michael Albinus]

Dmitry Gutov <dgutov@yandex.ru> writes:

> On 04/19/2016 11:10 AM, Michael Albinus wrote:
>
>> I don't mean this. The problem is how vc caches values. It uses file
>> properties, and in case `vc-file-getprop' returns nil, it assumes the
>> property is not cached. Consequently, we can never cache the value nil
>> for the file property `vc-state'.
>
> Which part of this hasn't been addressed in my previous email?
>
> What are the practical problems that you anticipate?

The very first line in `vc-state' doesn't make sense for unregistered
files:

  (or (vc-file-getprop file 'vc-state)

Even if we know that a file is unregistered, and we have set the file
property to nil accordingly, This information isn't used. For
unregistered files, the cached value isn't used, and the file's state is
computed again.

IOW: if vc-file-getprop returns nil, we don't know what this
means. Either "don't know", because the state hasn't been computed
yet. Or it means "unregistered".

My problem is *not* what vc-state returns to the caller. Here I could
live with a return value of nil, meaning unregistered.

Best regards, Michael.

Re: vc-state and unregistered

[Dmitry Gutov]

On 04/19/2016 11:31 AM, Michael Albinus wrote:

> The very first line in `vc-state' doesn't make sense for unregistered
> files:
>
>   (or (vc-file-getprop file 'vc-state)
>
> Even if we know that a file is unregistered, and we have set the file
> property to nil accordingly, This information isn't used. For
> unregistered files, the cached value isn't used, and the file's state is
> computed again.

That's not really true, try stepping through the function with Edebug, 
and see for yourself. It does go farther than the first line, but it 
doesn't call `vc-git-state' or `vc-git-registered' every time.

> IOW: if vc-file-getprop returns nil, we don't know what this
> means. Either "don't know", because the state hasn't been computed
> yet. Or it means "unregistered".

That could be fixed with using `none' instead, like `vc-backend' does. 
Which I've mentioned already.

But I'm not convinced we even need to make that effort.

Re: Docstrings and manuals

[Richard Stallman]

[[[ 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. ]]]

  > That sounds silly to me. At the very least, not mentioning a behavior in 
  > the docstring makes it easier to violate.

I don't know what you mean by "violate" in this specific context
(that mapatoms returns nil).

-- 
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.

Re: vc-state and unregistered

[Michael Albinus]

Dmitry Gutov <dgutov@yandex.ru> writes:

Hi Dmitry,

>> IOW: if vc-file-getprop returns nil, we don't know what this
>> means. Either "don't know", because the state hasn't been computed
>> yet. Or it means "unregistered".
>
> That could be fixed with using `none' instead, like `vc-backend'
> does. Which I've mentioned already.

That's the direction I have thought also. But in `vc-state' there is the
following comment:

  ;; Note: in Emacs 22 and older, return of nil meant the file was
  ;; unregistered.  This is potentially a source of
  ;; backward-compatibility bugs.

Since I don't know why nil has been replaced by `unregistered', it might
be a problem to use nil again as indication of unregistered files. And
we shouldn't change the interface wantonly, I believe.

Best regards, Michael.

Re: vc-state and unregistered

[Dmitry Gutov]

On 04/24/2016 03:11 PM, Michael Albinus wrote:

>> That could be fixed with using `none' instead, like `vc-backend'
>> does. Which I've mentioned already.
>
> That's the direction I have thought also. But in `vc-state' there is the
> following comment:

The comment is about the API and which value to return, not how the 
value is cached. My sentence, quoted above, was about how to cache it.

>   ;; Note: in Emacs 22 and older, return of nil meant the file was
>   ;; unregistered.  This is potentially a source of
>   ;; backward-compatibility bugs.

...and I have no idea how to interpret this comment. In Emacs 24, *and* 
in the upcoming 25.1, nil is *still* returned for unregistered files.

> Since I don't know why nil has been replaced by `unregistered', it might
> be a problem to use nil again as indication of unregistered files.

The salient question here is *in what way* has nil been replaced by 
`unregistered'.

> And
> we shouldn't change the interface wantonly, I believe.

The actual behavior will not change. This is what I'm proposing: to put 
the current behavior of (vc-state FILE) into spec.

Re: vc-state and unregistered

[Michael Albinus]

Dmitry Gutov <dgutov@yandex.ru> writes:

> The actual behavior will not change. This is what I'm proposing: to
> put the current behavior of (vc-state FILE) into spec.

Sometimes it returns nil, sometimes unregistered. Is this really what we
want to offer as a spec?

I'm going to push my changes accumulated over the last weeks. You will
see by the comments in vc-test--state, that the situation has been
improved. Less FIXME comments. I'm not saying that I'm satisfied already ...

We still need to check the performance, as said by you (due to external
processes).

Best regards, Michael.

Re: vc-state and unregistered

[Dmitry Gutov]

On 04/24/2016 03:45 PM, Michael Albinus wrote:

>> The actual behavior will not change. This is what I'm proposing: to
>> put the current behavior of (vc-state FILE) into spec.
>
> Sometimes it returns nil, sometimes unregistered.

When does it return `unregistered'?

> Is this really what we
> want to offer as a spec?

Just nil, obviously.

> I'm going to push my changes accumulated over the last weeks. You will
> see by the comments in vc-test--state, that the situation has been
> improved. Less FIXME comments. I'm not saying that I'm satisfied already ...

What about my changes?

Re: vc-state and unregistered

[Michael Albinus]

Dmitry Gutov <dgutov@yandex.ru> writes:

> On 04/24/2016 03:45 PM, Michael Albinus wrote:
>
>>> The actual behavior will not change. This is what I'm proposing: to
>>> put the current behavior of (vc-state FILE) into spec.
>>
>> Sometimes it returns nil, sometimes unregistered.
>
> When does it return `unregistered'?

See my recent commit.

>> Is this really what we
>> want to offer as a spec?
>
> Just nil, obviously.

That's not what's specified.

>> I'm going to push my changes accumulated over the last weeks. You will
>> see by the comments in vc-test--state, that the situation has been
>> improved. Less FIXME comments. I'm not saying that I'm satisfied already ...
>
> What about my changes?

I have applied some of them. I have not applied the reversion of calling
vc-responsible-backend instead of vc-backend, because I'm not convinced
yet that this is proper.

vc-state returns unregistered now in most of the cases when it should,
as it is specified. Pls show me the bugs, I might have introduced.

And yes, I have ackmnowledged already that we must speak about performance.

Best regards, Michael.

Re: vc-state and unregistered

[Dmitry Gutov]

On 04/24/2016 03:49 PM, Dmitry Gutov wrote:

>> I'm going to push my changes accumulated over the last weeks. You will
>> see by the comments in vc-test--state, that the situation has been
>> improved. Less FIXME comments. I'm not saying that I'm satisfied
>> already ...
>
> What about my changes?

I mean, seriously. I gave you a patch that improved the situation with 
tests without regressing performance, but avoided committing it so far 
out of courtesy.

You still haven't commented on it properly, but went ahead with 
different, incompatible changes. The very same changes we've discussed 
at length before, which lead to extra process calls.

Please avoid doing that in the future. I'm going to revert the offending 
parts.

Re: vc-state and unregistered

[Dmitry Gutov]

On 04/24/2016 04:07 PM, Michael Albinus wrote:

>> When does it return `unregistered'?
>
> See my recent commit.

Could you put that into words?

>> Just nil, obviously.
>
> That's not what's specified.

Please re-read my previous messages.

>> What about my changes?
>
> I have applied some of them. I have not applied the reversion of calling
> vc-responsible-backend instead of vc-backend, because I'm not convinced
> yet that this is proper.

I don't have to convince you. Quote the opposite, see "lisp/vc/*" in 
admin/MAINTAINERS.

Or do you want to take over VC maintenance?

> vc-state returns unregistered now in most of the cases when it should,
> as it is specified. Pls show me the bugs, I might have introduced.

We've discussed your current code at length already. It's pretty much 
what was in emacs-25 previously, with some new additions (those I don't 
mind, so far).

> And yes, I have ackmnowledged already that we must speak about performance.

And yet, you've decided to disregard the previous messages on that subject.

Re: vc-state and unregistered

[Michael Albinus]

Dmitry Gutov <dgutov@yandex.ru> writes:

>> I have applied some of them. I have not applied the reversion of calling
>> vc-responsible-backend instead of vc-backend, because I'm not convinced
>> yet that this is proper.
>
> I don't have to convince you. Quote the opposite, see "lisp/vc/*" in
> admin/MAINTAINERS.
>
> Or do you want to take over VC maintenance?

No. Please revert everything I've committed to vc. Remove also vc-tests.el.

I've tried to fix the bugs in vc, respecting the existing interface. If
you have other plans, go ahead.

Best regards, Michael.

Re: vc-state and unregistered

[Dmitry Gutov]

On 04/24/2016 04:24 PM, Michael Albinus wrote:

> Please revert everything I've committed to vc. Remove also vc-tests.el.

Why would I do that?

Re: vc-state and unregistered

[Michael Albinus]

Dmitry Gutov <dgutov@yandex.ru> writes:

> On 04/24/2016 04:24 PM, Michael Albinus wrote:
>
>> Please revert everything I've committed to vc. Remove also vc-tests.el.
>
> Why would I do that?

'Cos you have other plans with vc. Don't count me anymore working on
vc-tests.el.

Best regards, Michael.

Re: vc-state and unregistered

[Dmitry Gutov]

On 04/24/2016 05:03 PM, Michael Albinus wrote:

> 'Cos you have other plans with vc. Don't count me anymore working on
> vc-tests.el.

That is unfortunate. Even so, having a test suite with some level of 
coverage is very beneficial for VC's stability.

Thank you very much for getting it started.

Re: vc-state and unregistered

[Dmitry Gutov]

On 04/24/2016 04:07 PM, Michael Albinus wrote:

> Pls show me the bugs, I might have introduced.

As far as bugs go, here's one: you never return nil from vc-state 
anymore. Try evaluating:

(progn
   (vc-file-clearprops buffer-file-name)
   (vc-state buffer-file-name 'CVS))

And if the goal is to always return non-nil (which would be a change to 
the documented behavior), there is an easier way to do that than 
checking (vc-registered file), like:

diff --git a/lisp/vc/vc-hooks.el b/lisp/vc/vc-hooks.el
index 0535565..5c31d20 100644
--- a/lisp/vc/vc-hooks.el
+++ b/lisp/vc/vc-hooks.el
@@ -475,11 +475,11 @@ vc-state
    ;; FIXME: New (sub)states needed (?):
    ;; - `copied' and `moved' (might be handled by `removed' and `added')
    (or (vc-file-getprop file 'vc-state)
-      (and (not (vc-registered file)) 'unregistered)
        (when (> (length file) 0)         ;Why??  --Stef
-	(setq backend (or backend (vc-responsible-backend file)))
+	(setq backend (or backend (vc-backend file)))
  	(when backend
-	  (vc-state-refresh file backend)))))
+	  (vc-state-refresh file backend)))
+      'unregistered))

  (defun vc-state-refresh (file backend)
    "Quickly recompute the `state' of FILE."

Re: vc-state and unregistered

[Michael Albinus]

Dmitry Gutov <dgutov@yandex.ru> writes:

>> Pls show me the bugs, I might have introduced.
>
> As far as bugs go, here's one: you never return nil from vc-state
> anymore. Try evaluating:
>
> (progn
>   (vc-file-clearprops buffer-file-name)
>   (vc-state buffer-file-name 'CVS))

See the docstring of vc-state:

"A return of nil from this function means we have no information on the
status of this file."

I would expect this for files which are located in a directory not under
version control. None of the tests in vc-tests.el cover this case.

> And if the goal is to always return non-nil (which would be a change
> to the documented behavior), there is an easier way to do that than
> checking (vc-registered file), like:

I haven't said that my changes are perfect. But we differ in the
understanding of the API.

Best regards, Michael.

Re: vc-state and unregistered

[Dmitry Gutov]

On 04/24/2016 09:13 PM, Michael Albinus wrote:

> See the docstring of vc-state:
>
> "A return of nil from this function means we have no information on the
> status of this file."
>
> I would expect this for files which are located in a directory not under
> version control. None of the tests in vc-tests.el cover this case.

And if buffer-file-name is outside of any version control, does your 
version of vc-state return nil?

Re: vc-state and unregistered

[Michael Albinus]

Dmitry Gutov <dgutov@yandex.ru> writes:

>> See the docstring of vc-state:
>>
>> "A return of nil from this function means we have no information on the
>> status of this file."
>>
>> I would expect this for files which are located in a directory not under
>> version control. None of the tests in vc-tests.el cover this case.
>
> And if buffer-file-name is outside of any version control, does your
> version of vc-state return nil?

No. I didn't test this. As said, the tests must be improved, that's what
they are good for. And bugs must be fixed.

But for the other cases, files under version control, my last commits
have shown improvements I believe. That's why I find your reaction to
revert everything ... annoying.

Re: vc-state and unregistered

[Dmitry Gutov]

On 04/24/2016 10:41 PM, Michael Albinus wrote:

>> And if buffer-file-name is outside of any version control, does your
>> version of vc-state return nil?
>
> No. I didn't test this. As said, the tests must be improved, that's what
> they are good for. And bugs must be fixed.

We could add a separate test for that, but the simplest fix would 
require updating the existing tests as well, and then that test wouldn't 
be necessary. See the commit I pushed.

Anyway, feel free to add it. We didn't finish the discussion about 
semantics, so it didn't seem proper to me to add tests for them.

> But for the other cases, files under version control, my last commits
> have shown improvements I believe. That's why I find your reaction to
> revert everything ... annoying.

Not everything, just the parts that conflicted with the patch I've sent 
previously. Which I had to recreate.

So in the interest of speed, I've also removed all

   (should (eq (vc-state tmp-name) (vc-state tmp-name backend)))

checks. They aren't essential, and finding which of them are failing 
exactly is too time-consuming.

Let's only add each of them back after they pass. I'd also like to have 
the different steps of each scenario as separate tests, so that ERT can 
tell us which failed.