Closed tarsius closed 2 years ago
@purcell IMO the way you addressed these warnings in 468b147ee85b4e963eaac46b8e8428fe740997c4 is weird, so I have rebased this earlier pull-request and would encourage you to either merge it or go with the alternative approach mentioned in the commit message.
IMO the way you addressed these warnings in 468b147 is weird
Can you be more specific than "weird" please? You might be right, but I basically did exactly what was recommended by the compiler warning afaict. But I haven't used the =
syntax previously.
Re. the commit message
This was rebased on top of another attempt to address this, which I find weird. IMO the two options are \='symbol and `symbol', and I prefer the latter. I have been using that all along, even while 'symbol did not result in a warning yet.
it looks like you're expressing a preference. My sense is that the backtick-apostrophe combination refers to a thing named by that symbol (e.g. a function or a variable) rather than a raw symbol: this is based on the fact that sometimes checkdoc will request that such quoted symbols be prefixed with "function" or "variable" to disambiguate the reference. The =
prefix causes the symbol to be rendered with a leading curly single quote in the doc buffer. I couldn't find info in the manual about what's best and when.
package-lint.el:113:2: Warning: defconst `package-lint-symbol-info' docstring
has wrong usage of unescaped single quotes (use \= or different quoting)
Maybe something ate the \
. This might be worded ambiguously but it is trying to tell you to replace 'symbol
with \='symbol
, and because \
has to be quoted itself, you have to write \\='symbol
. If you write =symbol
, then that is shown exactly like that by describe-*
and the user might then think that only symbols whose names begin with =
are valid values.
So if you want describe-*
to continue to show 'symbol
, then you need to quote the quote with \\=
, but I recommend you instead use symbol-quoting, that's how it is done in the docstrings that are part of Emacs. For example, from byte-compile-warnings
:
If the list begins with `not', then
And if you write something like "each element has the form (KEY . VAL), where KEY...", then I would recommend writing it just like that. If you previously wrote '(KEY . VAL), then just drop the '
. I.e. write the form the value has to have after evaluation, not some code that evaluates to that form. Edit: Ah I see, you are already doing it like this.
this is based on the fact that sometimes checkdoc will request that such quoted symbols be prefixed with "function" or "variable" to disambiguate the reference.
That's annoying but I think it only happens if a symbol is actually bound as a variable and function. And at least with 29.0.50 this doesn't appear to happen at all anymore.
That makes sense, thanks, I'll go ahead and merge your version, I agree it's preferable.
I would recommend writing it just like that. If you previously wrote '(KEY . VAL), then just drop the
'
.
Yes, that's what I've tended to do, I think.
The byte-compiler recently got more fussy about quotes.