Re: master 1e3b0f2: Improve doc strings of project.el

[Eli Zaretskii <eliz@gnu.org>]

> Cc: theo@thornhill.no, philip@warpmail.net, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 12 Jul 2020 18:08:50 +0300
> 
> If I work on parts of Emacs I'm not responsible for, I make doubly sure 
> to check with authors/maintainers.
> 
> How about you extend me this courtesy? I'm the author and the maintainer 
> of this package.

I do.  This longish and frustrating discussion is the best evidence to
that.

> >> Not documenting internal information is a valid choice.
> > 
> > It isn't internal.  Anyone who wants to use the return value will need
> > to understand its possible form(s).
> 
> Yes, it is. Apparently you don't understand how cl-generic works.

Please drop the attitude.

> >>> But other than that, if someone needs to write code for the VC project
> >>> backend, how can they NOT rely on the form of the object that
> >>> project-try-vc returns?
> >>
> >> Nobody should "write code for the VC project backend" except its
> >> author(s).
> > 
> > This is a community project, and everybody is welcome to contribute
> > code to any part of Emacs.  Restricting some parts of code to a single
> > person is not a good way of ensuring Emacs's future.
> 
> Not the person. The place. project-vc lives in project.el.

Irrelevant.  I meant people other than the author of the code, the
person.  Those others will need more detailed documentation than what
you are prepared to provide.

> Internal information can reside there without being documented, if all 
> of its producers and consumers also reside there.

This is a new definition of what is "internal", and I don't agree with
it.  Our accepted definition is different.

> > With respect, I disagree, having read the code and having considered
> > how I would implement something related to it.  That is the single
> > most important reason why I'm trying to improve the documentation of
> > this package: to make it easier for others to expand and extend it.
> 
> If you had asked me questions like "how do I implement this or that", 
> none of my answers would have included the format of the return value of 
> project-try-vc.

I know.  Which is why I don't think your method of answering such
questions is useful enough to be used as basis for good documentation.

> > Then let's say that.  But concealing the information will not solve
> > the problem, because you cannot conceal it.  By not mentioning it and
> > the caveats to go with it we will be punished twice: we will make it
> > harder for people to understand the current code and contribute to it,
> 
> There's nothing hard in understanding what the current code returns: you 
> navigate to the function's definition and look at the end.

Documentation exists so that I won't need to follow a chain of several
functions to find the answer to a simple question.  (And no, just
reading the code of project-try-vc is not enough, not unless you know
by heart what each one of the functions it calls does and returns.)

> > and we will not make sure they realize that relying on these details
> > is not a good idea.
> 
> Like I said, if you're not satisfied with how that recommendation is 
> conveyed, feel free to add clarifications. *Without* giving the example 
> of said values in the docstrings.

I think describing the values returned by public functions is a large
part of good documentation, it clarifies quite a lot in a very
efficient way (a picture is worth a thousand words).

> >> If my method of saying "don't rely on this format" is insufficient,
> >> please go ahead and add some more clarifications on that part. But
> >> without documenting this said value format.
> > 
> > You cannot usefully tell people to not rely on something without
> > describing that something.
> 
> And yet, somehow, parents around the world manage to tell their children 
> not to use swear words without swearing profusely themselves.

Sure, it isn't needed, not after the child him/herself swears, which
is the trigger for the parents telling them not to.

> > And there's the other disadvantage to
> > concealing information: obfuscation of the code.
> 
> The code is not the issue.

Of course it is!  Documentation is a significant aid in understanding
the code.

> >> If they create a new backend, they will read the code of the existing
> >> one.
> > 
> > That's not how we encourage extending Emacs.  Some minimal
> > documentation is needed before we can in good faith tell users to read
> > the code, and project.el currently falls short of that minimum, IMO.
> 
> You seem to be criticizing something else than what I said.

I'm criticizing the "they will read the code" part.

> And I never said we don't need documentation.

I never said you did.

> Okay, internal to project.el, if we want to be more precise.
> 
>  > AFAICT, project-current is backend-agnostic.
> 
> Except when we want to return some project instance where none were 
> detected.

Which is exactly what the text I added says.