[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: master 1e3b0f2: Improve doc strings of project.el
From: |
Eli Zaretskii |
Subject: |
Re: master 1e3b0f2: Improve doc strings of project.el |
Date: |
Sun, 12 Jul 2020 18:36:33 +0300 |
> 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.
- Re: master 1e3b0f2: Improve doc strings of project.el, (continued)
- Re: master 1e3b0f2: Improve doc strings of project.el, Eli Zaretskii, 2020/07/10
- Re: master 1e3b0f2: Improve doc strings of project.el, Dmitry Gutov, 2020/07/10
- Re: master 1e3b0f2: Improve doc strings of project.el, Eli Zaretskii, 2020/07/11
- Re: master 1e3b0f2: Improve doc strings of project.el, Dmitry Gutov, 2020/07/11
- Re: master 1e3b0f2: Improve doc strings of project.el, Eli Zaretskii, 2020/07/11
- Re: master 1e3b0f2: Improve doc strings of project.el, Dmitry Gutov, 2020/07/11
- Re: master 1e3b0f2: Improve doc strings of project.el, Eli Zaretskii, 2020/07/12
- Re: master 1e3b0f2: Improve doc strings of project.el, Dmitry Gutov, 2020/07/12
- Re: master 1e3b0f2: Improve doc strings of project.el, Eli Zaretskii, 2020/07/12
- Re: master 1e3b0f2: Improve doc strings of project.el, Dmitry Gutov, 2020/07/12
- Re: master 1e3b0f2: Improve doc strings of project.el,
Eli Zaretskii <=
- Re: master 1e3b0f2: Improve doc strings of project.el, Eli Zaretskii, 2020/07/12
- Re: master 1e3b0f2: Improve doc strings of project.el, Dmitry Gutov, 2020/07/12
- Re: master 1e3b0f2: Improve doc strings of project.el, Eli Zaretskii, 2020/07/13
- Re: master 1e3b0f2: Improve doc strings of project.el, Gregory Heytings, 2020/07/13
- Re: master 1e3b0f2: Improve doc strings of project.el, Eli Zaretskii, 2020/07/13
- Re: master 1e3b0f2: Improve doc strings of project.el, Gregory Heytings, 2020/07/13
- Re: master 1e3b0f2: Improve doc strings of project.el, Eli Zaretskii, 2020/07/13
- Re: master 1e3b0f2: Improve doc strings of project.el, Dmitry Gutov, 2020/07/13
- Re: master 1e3b0f2: Improve doc strings of project.el, tomas, 2020/07/13
- Re: master 1e3b0f2: Improve doc strings of project.el, Dmitry Gutov, 2020/07/17