From: Dmitry Gutov <dgutov@yandex.ru>
To: Eli Zaretskii <eliz@gnu.org>
Cc: emacs-devel@gnu.org
Subject: Re: Opaque objects and Emacs documentation
Date: Fri, 17 Jul 2020 16:42:55 +0300 [thread overview]
Message-ID: <f9843db7-fb51-cac1-4a70-d09b31c09190@yandex.ru> (raw)
In-Reply-To: <835zamjsvk.fsf@gnu.org>
On 17.07.2020 14:14, Eli Zaretskii wrote:
>> Cc: emacs-devel@gnu.org
>> From: Dmitry Gutov <dgutov@yandex.ru>
>> Date: Fri, 17 Jul 2020 13:53:35 +0300
>>
>> It shouldn't come as a surprise that I think there is no better
>> technological choice. Otherwise I would have used it.
>
> ??? You are saying that the _only_ way to design project.el is to use
> generics at that high level? Just because sometimes a "project
> instance" is a cons cell and sometimes some other Lisp structure? I'm
> surprised to hear that.
This logic is backwards. The generics are here because we make good use
of them.
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.
>> What should help is coming up with a better, consistent way to document
>> these things.
>
> 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.
But for some reason you are fine with docstrings that say "ARG is a
completion table", or "returns a completion table"?
> Later it became apparent that you are doing this on purpose, because
> you have decided that certain directions of developing the package
> should be made as hard as possible,
That is an unfair misstatement of my words.
> something that I think is
> completely against the spirit of Emacs development. Readers of this
> thread are invited to read
>
> https://lists.gnu.org/archive/html/emacs-devel/2020-07/msg00288.html
>
> especially under "Here are things we want third-party code to be able
> to do" and "Here are, on the other hand, things that people generally
> shouldn't do". Again, I'm interested to know how many of us here
> share those views.
Those are not examples of "developing the package". Those are examples
of using it. Some of them - incorrectly.
>>> Which I think is against long-time Emacs tradition for documenting its
>>> interfaces, and by that facilitating extensibility. It is IMO wrong
>>> to fill Emacs application levels with opaque objects which cannot be
>>> usefully described; they should be a rare exception, but definitely
>>> not the rule.
>>
>> 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.
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.
> Even if you think it is not useful for you, the fact that
> fellow developers tell you the contrary should be a reason to revisit
> your views, and maybe allow for other views as well, even if you
> disagree.
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.
> 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 also talked about the possibility to have this documented in the
manual, etc (in a chapter targeted at developers).
You have skipped and dismissed it all, and now make contrived accusations.
>> The main thing thing the user can do with that value is misuse it, by
>> relying on its shape in the client code.
>
> 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?
> We should treat our users as responsible adults, even
> if some of them aren't. Those who aren't will eventually be amply
> punished, or will recognize their mistakes and get their act together.
Our users are not all "responsible adults", or to put it differently,
are not all professional programmers. Even even those who are, are at
very different levels of skill.
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.
next prev parent reply other threads:[~2020-07-17 13:42 UTC|newest]
Thread overview: 106+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <20200712184908.13140.5739@vcs0.savannah.gnu.org>
[not found] ` <20200712184909.BBC61209B1@vcs0.savannah.gnu.org>
2020-07-12 20:07 ` master 0339325: ; * lisp/progmodes/project.el (project-current): Doc fix Dmitry Gutov
2020-07-13 3:48 ` Eli Zaretskii
2020-07-13 11:09 ` Dmitry Gutov
2020-07-13 13:21 ` Eli Zaretskii
2020-07-13 14:14 ` Dmitry Gutov
2020-07-16 22:40 ` Dmitry Gutov
2020-07-17 6:56 ` Opaque objects and Emacs documentation Eli Zaretskii
2020-07-17 8:13 ` tomas
2020-07-17 10:40 ` Dmitry Gutov
2020-07-17 15:38 ` tomas
2020-07-17 10:37 ` Basil L. Contovounesios
2020-07-17 10:46 ` Dmitry Gutov
2020-07-17 10:53 ` Basil L. Contovounesios
2020-07-17 10:53 ` Dmitry Gutov
2020-07-17 11:14 ` Eli Zaretskii
2020-07-17 12:02 ` Noam Postavsky
2020-07-17 12:52 ` Eli Zaretskii
2020-07-17 13:09 ` Dmitry Gutov
2020-07-17 13:56 ` Eli Zaretskii
2020-07-17 14:35 ` Dmitry Gutov
2020-07-17 14:59 ` Eli Zaretskii
2020-07-17 15:03 ` Dmitry Gutov
2020-07-18 1:54 ` Richard Stallman
2020-07-18 19:17 ` Dmitry Gutov
2020-07-19 2:27 ` Richard Stallman
2020-07-19 14:48 ` Eli Zaretskii
2020-07-21 19:00 ` Dmitry Gutov
2020-07-21 19:36 ` Eli Zaretskii
2020-07-21 20:56 ` Dmitry Gutov
2020-07-21 21:06 ` Tomas Hlavaty
2020-07-21 20:49 ` Tomas Hlavaty
2020-07-21 20:59 ` Dmitry Gutov
2020-07-21 21:20 ` Tomas Hlavaty
2020-07-21 21:25 ` Dmitry Gutov
2020-07-21 19:08 ` Dmitry Gutov
2020-07-21 19:38 ` Eli Zaretskii
2020-07-21 21:02 ` Dmitry Gutov
2020-07-21 20:29 ` John Yates
2020-07-22 0:45 ` Dmitry Gutov
2020-07-22 14:08 ` Eli Zaretskii
2020-07-19 22:02 ` Dmitry Gutov
2020-07-20 2:44 ` Richard Stallman
2020-07-21 1:09 ` Dmitry Gutov
2020-07-21 8:57 ` tomas
2020-07-21 10:14 ` Dmitry Gutov
2020-07-21 10:29 ` tomas
2020-07-21 14:34 ` Eli Zaretskii
2020-07-21 18:56 ` Dmitry Gutov
2020-07-21 19:33 ` Eli Zaretskii
2020-07-21 21:31 ` Dmitry Gutov
2020-07-22 14:28 ` Eli Zaretskii
2020-07-22 15:44 ` Dmitry Gutov
2020-07-22 16:30 ` Eli Zaretskii
2020-07-22 16:37 ` Dmitry Gutov
2020-07-21 19:36 ` Alan Mackenzie
2020-07-21 21:17 ` Dmitry Gutov
2020-07-21 22:12 ` Edebug (was: Opaque objects and Emacs documentation) Stefan Monnier
2020-07-22 14:31 ` Opaque objects and Emacs documentation Eli Zaretskii
2020-07-22 15:33 ` Dmitry Gutov
2020-07-22 16:22 ` Eli Zaretskii
2020-07-22 16:26 ` Dmitry Gutov
2020-07-23 4:04 ` Richard Stallman
2020-07-23 13:42 ` Dmitry Gutov
2020-07-22 11:43 ` João Távora
2020-07-17 13:08 ` Dmitry Gutov
2020-07-17 13:42 ` Dmitry Gutov [this message]
2020-07-17 14:22 ` Eli Zaretskii
2020-07-17 14:56 ` Dmitry Gutov
2020-07-17 16:56 ` John Yates
2020-07-17 17:13 ` Drew Adams
2020-07-17 19:04 ` Eli Zaretskii
2020-07-17 19:26 ` Dmitry Gutov
2020-07-17 19:25 ` Dmitry Gutov
2020-07-17 11:53 ` Gregory Heytings via Emacs development discussions.
2020-07-17 13:13 ` Dmitry Gutov
2020-07-17 14:26 ` Gregory Heytings via Emacs development discussions.
2020-07-17 16:58 ` Drew Adams
2020-07-17 19:22 ` Dmitry Gutov
2020-07-17 22:30 ` Gregory Heytings via Emacs development discussions.
2020-07-18 0:00 ` Yuan Fu
2020-07-18 1:01 ` Drew Adams
2020-07-18 1:55 ` Richard Stallman
2020-07-17 16:48 ` Stefan Monnier
2020-07-23 23:24 ` Andy Moreton
2020-07-23 23:40 ` Andy Moreton
2020-07-24 5:32 ` Eli Zaretskii
2020-07-24 11:23 ` Andy Moreton
2020-07-24 11:43 ` Eli Zaretskii
2020-07-24 0:43 ` Dmitry Gutov
2020-07-24 1:22 ` Andy Moreton
2020-07-24 5:47 ` Eli Zaretskii
2020-07-25 16:33 ` Andy Moreton
2020-07-25 16:51 ` Eli Zaretskii
2020-07-25 20:18 ` Andy Moreton
2020-07-26 2:27 ` Eli Zaretskii
2020-07-26 9:16 ` Andy Moreton
2020-07-26 14:02 ` Eli Zaretskii
2020-07-24 20:49 ` Dmitry Gutov
2020-07-25 16:38 ` Andy Moreton
2020-07-24 5:45 ` Eli Zaretskii
2020-07-24 14:56 ` Dmitry Gutov
2020-07-24 17:21 ` Drew Adams
2020-07-24 17:42 ` Eli Zaretskii
[not found] <<20200712184908.13140.5739@vcs0.savannah.gnu.org>
[not found] ` <<20200712184909.BBC61209B1@vcs0.savannah.gnu.org>
[not found] ` <<7bf4d6ef-c0ec-43dc-ad5d-f6e81422ad90@yandex.ru>
[not found] ` <<83zh84m5ws.fsf@gnu.org>
[not found] ` <<3dd1c224-69b2-40af-5b2e-43a310253632@yandex.ru>
[not found] ` <<83tuybmtxs.fsf@gnu.org>
[not found] ` <<859f594b-1343-6d26-e1ac-7157c44eb56c@yandex.ru>
[not found] ` <<83a6zyk4tt.fsf@gnu.org>
2020-07-17 15:41 ` Drew Adams
2020-07-17 15:49 ` Dmitry Gutov
2020-07-17 15:59 ` Drew Adams
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=f9843db7-fb51-cac1-4a70-d09b31c09190@yandex.ru \
--to=dgutov@yandex.ru \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.