Subject: Re: bug#60418: [PATCH] Add :vc keyword to use-package

From: Eli Zaretskii <[email-masked]>
Date: Tue, 18 Apr 2023 15:13:44 +0300

> From: Tony Zorman <[email-masked]>
> Cc: [email-masked], [email-masked], [email-masked],
>  [email-masked]
> Date: Mon, 17 Apr 2023 21:39:47 +0200
> 
> >> +(defun use-package-handler/:vc (name _keyword arg rest state)
> >> +  "Generate code for the :vc keyword."
> >
> > I don't think this is an accurate description of what the function
> > does.  Also, we try very hard to mention at least the mandatory
> > arguments in the first line of the doc strings.
> 
> I think I initially copied this from the handler for ":custom" (where
> it's perhaps more applicable) and then forgot to change it. Still, I'm
> not totally sure what to write here without assuming that the reader
> already knows what the handler for a use-package keyword does (which is,
> I guess, why none of the other handlers have much in the way of
> documentation). Would it be a good idea to link to a relevant entry in
> the info manual ((use-package) > Keyword extensions > Creating an
> extension)?

You could say something short on the first line assuming the reader
knows, then explain a bit more in the subsequent lines.  And yes,
pointing to the Info manual is also an option, but something should
still be in the doc string.