Re: Opaque objects and Emacs documentation

[Dmitry Gutov]

On 17.07.2020 17:22, Eli Zaretskii wrote:

> That wasn't the issue.  The issue is whether we should use these
> techniques in a way that makes it hard or impossible to document our
> functions and commands.  Even if technically this is the best design
> (and I don't yet see why this should be so, nor see any arguments
> presented to justify that), we may decide that the price is too heavy.

I can hardly understand how we might choose to reject the possibility to 
implement certain useful features only because return values of some 
functions become more difficult to document.

> > The use of cons cells or some other structures, is a choice, basically
> > arbitrary, that can change at will. That is another reason why I don't
> > like to see the low-level description in the docstring of project-current.
>
> As was already written several times, internal implementation details
> can be documented without any real impediment of future development.

In an appropriate place. Say, the "internals" documentation, wherever it 
may reside.

> So this argument is invalid.

Of course.

> > > I tried to find one, but couldn't.  If someone wants to propose a way,
> > > I'm all ears.  I wrote those comments which started this thread
> > > because it surprised me how difficult it was to try to keep the
> > > limitations you impose on what should and what shouldn't be divulged,
> > > and yet produce useful documentation of what the various public
> > > functions do.  In all my 40 years of experience with Emacs, I have
> > > never bumped into such a brick wall, with no way around it.
> >
> > I'm saying it's nothing new: completion tables, for instance, have been
> > quite as abstract.
>
> That one bad example exist doesn't mean we want others.

You seem to be on a crusade against abstraction. Never mind that it is 
the only way to provide features with strong extensibility.

> > But for some reason you are fine with docstrings that say "ARG is a
> > completion table", or "returns a completion table"?
>
> Who said I was fine with them?  Rome wasn't built in a day.

And Carthage must be destroyed, apparently.

> > Those are not examples of "developing the package". Those are examples
> > of using it.
>
> Consuming the package's API and adding backends is development of
> project.el. 

No, it isn't. It's not development of the API, or of the built-in backends.

> (It is also "using" it, but not on the user level, so
> saying that is "using" just muddies the waters, but doesn't affect the
> main issue in any way.)

If the presence of user-level commands inside project.el confuses you, 
we can split them into a different file.

> > > > The problem here is that even if you document a particular value, it's
> > > > _not useful_. It doesn't show you what you can or should do with it.
> > >
> > > It was very useful for me, and so I presume it could be useful for
> > > others.
> >
> > It has been useful to you to find an answer to a minor question: "how
> > projects are compared, which projects are equal?". Which is not
> > something most people will even think about.
>
> Why not?  Of course they will.

That has never come up in several years.

> Besides, the question about what exactly is a "project instance" is
> relevant in many places in the package, just look how many doc strings
> mention that phrase.

Saying that is a cons (and even giving an example), does nothing to 
address that question. This seems to be the main issue you fail to 
understand here.

> > And even answering that question for the project-vc case doesn't give
> > you a general answer. I don't see how you are content with only having
> > that answer for a special case anyway.
>
> That's the only case that we have for now, so it's highly relevant and
> useful.

Two built-in cases. One case in Stefan's backend which you have never 
seen. Some backends out there, either existing or future ones.

But you need to be able to reason about all of them.

> > Perhaps if someone else said "I wanted to do a (valid thing X), couldn't
> > understand how to do it, and this piece of information would have made
> > it easier"?
> >
> > No such declarations so far.
>
> Since when we write documentation only when someone asks a question?

You are refuting something I haven't said.

> Documentation is supposed to be proactive, it should answer the
> important questions before they are asked.

Exactly. The important ones.

> > > Documentation should strive to serve different ways of studying and
> > > developing Emacs, not just a single way that you personally think is
> > > The (only) Right Thing.
> >
> > I already said you can add code comments. Preferably somewhere which is
> > not the main entry point of the API.
>
> I'm sure you understand how low is my motivation to do any work on
> documenting project.el.

Whatever your motivation is, saying I object to any and all 
documentation is false.

> Look what happened last time: I improved
> several doc strings, and suddenly I have a dispute that lasts for a
> month,

I accepted your multiple edits, and changed a couple of functions and 
descriptions myself to better support your personal goals.

And I removed a couple of sentences you wrote. Which you have been 
unable to leave alone, or accept my perspective.

> and ends up accusing me in all the sins on Earth, including
> that I cause contributors to flee and don't understand the code I'm
> reading.  I'm only human, and have a busy schedule; unpleasant jobs
> get pushed back and delayed.

There is no hurry.

> > > Once again: concealing information because someone could be silly
> > > enough to misuse it punishes many valid uses on behalf of a few
> > > invalid ones.
> >
> > Which valid uses, though?
>
> Any and all of them.

That's vague.

> > And even when writing documentation for professional programmers, it is
> > always considered a good taste to structure it so that it encourages
> > writing good code, and discourages writing bad one.
>
> We encourage writing good code, but not through hiding important
> information.

Having private/undocumented functions and variables is a common practice 
even in our project.