bug#29373: 24.5; doc string of `self-insert-uses-region-functions'

[Drew Adams <drew.adams@oracle.com>]

> Sometimes it's impossible to limit a line to 70 characters without
> incurring worse problems.  This is one such case.

I don't see any such "worse problems" in this case.
Without any change to the wording (which does need
to be changed), this shows no "worse problems":

 Special hook to tell if `self-insert-command' will use the region.
 It must be called via `run-hook-with-args-until-success' with no
 arguments.

 Any `post-self-insert-command' which consumes the region should
 register a function on this hook so that things like
 `delete-selection-mode' can refrain from consuming the region.

> > > > The doc string is close to incomprehensible.
> > >
> > > Such derogatory remarks are best kept out of bug reports.
> > > The facts are grave enough to tell we should fix this.
> >
> > Nothing derogatory intended.
> 
> That sentence could simply be omitted without any effect on the
> report.  May I suggest that you try to refrain from such unneeded
> remarks?
> 
> > That's a summary of the problem - lack of clarity overall.
> 
> "Lack of clarity" would be fine (although it, too, adds nothing).
> "Incomprehensible" is not a summary.

"Incomprehensible" was not the summary I used.
"Close to incomprehensible" is the summary I used.

I stand by that characterization, as one user
reporting a doc problem: to me, the doc string was
close to incomprehensible.  You might not find it so.

It's understandable that a new doc string might not
have had the attention it deserves, and so is not
as clear as it could be.

To me, this one was not really understandable.
Perhaps you prefer the statement, "I don't
understand this doc string, and I think others
may also have trouble making sense of it."

And no, I don't think that such a statement adds
nothing, even if it is better if accompanied by
guesses about the meaning, suggestions for
improvement, or pointing out particular places
that are especially problematic for the reporter.

If a reporter has no clue what is meant and no
clue what parts are particularly unclear, the
simple report that a doc string is unclear to
that reporter can help.  We can disagree about
this, of course.

But my guess is that if you agree with the
reporter after reading such an incomplete "Huh?"
report then the aim is reached.  And if you
disagree with the reporter - the doc is clear
to you, even if the reporter doesn't understand
it at all - it is still good that the perceived
problem was reported, and no harm was done.
We can disagree about this too, of course.