Subject: bug#44858: [PATCH] Make byte-compiler warn about wide docstrings

From: Stefan Kangas <[email-masked]>
Date: Fri, 27 Nov 2020 12:15:03 +0100

Lars Ingebrigtsen <[email-masked]> writes:

> Eli Zaretskii <[email-masked]> writes:
>
> >> For `substitute-command-keys', it would be nice to get it to work, but I
> >> don't think we can know the values of keymaps at compile-time.  Possibly
> >> there is a good solution for this, but I couldn't find it.
> >
> > How about some simplified heuristics, like assume that the expansion
> > takes no more than N characters (where N could be something like 5)?
> > This should work in, like, 80% of cases, I think.
>
> Yup.  And 15% is mostly when it expands to `M-x some-long-command'
> because the keymap hasn't been loaded yet, I think?  Which we could
> conceivably fix by loading the file when the used `C-h f's an autoloaded
> function with one of these constructs?  Perhaps a bit hacky...

I would be wary of using a heuristic here, because I think false
positives are worse than false negatives in this case.  We
unfortunately don't have any way of silencing individual warnings, so
a user seeing a false positive is left with two suboptimal choices:
ignore the warning (a bad habit to train our users in) or change the
formatting of a docstring to stop it (potentially making it
subjectively worse in the process).

How about using the somewhat safer heuristic of treating substitutions
as one character wide?  Would that make sense?