Re: [External] : A peek to the other side

[Eli Zaretskii <eliz@gnu.org>]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Tue, 22 Feb 2022 18:25:44 +0000
> Cc: "'Help-Gnu-Emacs \(help-gnu-emacs@gnu.org\)'" <help-gnu-emacs@gnu.org>
> 
> At the very least, every use of `--' should have an
> easily findable comment or doc, explaining what it's
> about - why the labeler labeled it so.  A guess is
> that if that guideline were adopted there'd be a lot
> less gratuitous use (misuse) of `--'.  And updating
> out-of-date `--' would be less problematic.  Today,
> it's an irresponsible, easy "label `--' willy nilly,
> and forget about it."

You make it sound like we are too lazy to do this stuff, so we use a
cop-out.

Nothing is farther from the truth.  The free time we have to work on
Emacs is used to its last second.  There's only so much one can do in
a given time, and it is therefore wise to prioritize the jobs and do
the more important ones first.  Abundantly documenting APIs we
consider to be internal, not-for-use, subject-to-change-without-notice
is way down the priority list, that's all.  So we keep the
documentation of those to the absolute minimum: by using the "--"
indication, and we expect Emacs programmers to trust us on that.
Anything else would simply be a case of bad judgment and misuse of the
time we have to contribute.