GNU bug report logs - #60418
[PATCH] Add :vc keyword to use-package

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: Tony Zorman <soliditsallgood <at> mailbox.org>
Cc: philipk <at> posteo.net, felician.nemeth <at> gmail.com, 60418 <at> debbugs.gnu.org, stefankangas <at> gmail.com
Subject: bug#60418: [PATCH] Add :vc keyword to use-package
Date: Tue, 18 Apr 2023 15:13:44 +0300

> From: Tony Zorman <soliditsallgood <at> mailbox.org>
> Cc: philipk <at> posteo.net, 60418 <at> debbugs.gnu.org, felician.nemeth <at> gmail.com,
>  stefankangas <at> gmail.com
> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.