[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Opaque objects and Emacs documentation

From: Dmitry Gutov
Subject: Re: Opaque objects and Emacs documentation
Date: Fri, 17 Jul 2020 17:56:57 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0

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

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

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

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

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

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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]