search

purcell / package-lint

A linting library for elisp package metadata
GNU General Public License v3.0
192 stars 33 forks source link

Replace certain single quotes in docstrings #228

Closed tarsius closed 2 years ago

tarsius commented 2 years ago

The byte-compiler recently got more fussy about quotes.

tarsius commented 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.

purcell commented 2 years ago

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.

purcell commented 2 years ago

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.

tarsius commented 2 years ago 
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.

tarsius commented 2 years ago

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.

purcell commented 2 years ago

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.