GNU bug report logs - #10522
Patch: Improve optional variable and keyword notation in manual

Previous Next

Full log

View this message in rfc822 format

From: Andy Wingo <wingo <at> pobox.com>
To: b3timmons <at> speedymail.org
Cc: guile-devel <guile-devel <at> gnu.org>, 10522 <at> debbugs.gnu.org
Subject: bug#10522: Patch: Improve optional variable and keyword notation in manual
Date: Fri, 03 Feb 2012 14:28:55 +0100

Hi Bake,

This patch looks great.  I do have a couple of comments before
applying.  It would probably be useful to have input from others as
well, so I'm copying guile-devel.

On Mon 16 Jan 2012 20:46, Bake Timmons <b3timmons <at> speedymail.org> writes:
> -@deffn {Scheme Procedure} resolve-module name [autoload=#t] [version=#f] [#:ensure=#t]
> +@deffn {Scheme Procedure} resolve-module name [autoload=#t [version=#f]] @
> +                          [#:ensure ensure=#t]

Nesting the optional arguments in brackets can get a bit ugly.  It is
precise but verbose.  But I suppose we should not encourage interfaces
with many optional arguments, so perhaps it is a moot point.

Also, it seems pedantic to repeat the keyword arguments (once as
keyword, once as identifier).  Surely #:foo=bar is unambiguous?

Anyway, I'm interested what others think about changes like this.

Cheers,

Andy
-- 
http://wingolog.org/

Previous Next

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