--- Begin Message ---
|
Subject: |
Inconsistent documentation of repeated arguments |
|
Date: |
Sun, 06 Nov 2011 14:10:46 -0500 |
|
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.0.91 (gnu/linux) |
Before making some changes to the docs, I just wanted to give a heads
up. Recall the motivation behind Scheme
"It was designed to have an exceptionally clear and simple semantics and
few different ways to form expressions."
Why not tighten up notation in the docs as well as in the language? My
hunch is that in the long run doing so will help those learning Guile.
Examples from the current Guile Reference:
(1) -- Scheme Procedure: string-append . args
(2) -- Scheme Procedure: append lst1 ... lstN
(3) -- Scheme Procedure: error msg args ...
(4) -- Scheme Procedure: error who message irritant1 ...
IMO, (4) is the right thing. In software documentation '...' means
'repeated zero or more times', so 'arg ...' always includes 'args' as a
possibility, rendering 'args ...' redundant and potentially confusing.
Of course, in principle, we might intend 'args' to mean an aggregate
data structure such as list, but in that case 'arglist', 'list',
etc. would be clearer IMO. Thus, I would fix (1-3) to be
(1) -- Scheme Procedure: string-append arg ...
(2) -- Scheme Procedure: append lst ... obj
(3) -- Scheme Procedure: error msg arg ...
(The 'obj' from (2) is particular to 'append'.) FWIW, highly regarded
docs such as the RnRS reports, _The Scheme Programming Language_ by
Dybvig, CLtL2, etc. are consistent on such things.
Something like 'elem1 ... elemN' might be useful in a discussion of say
the Ith element and so on, but it not easy enough just to use 'elem ...'
in the definition header and then elaborate in the definition body w/
'elem1 ... elemN', etc.?
Thanks,
Bake
--- End Message ---
--- Begin Message ---
|
Subject: |
Re: bug#9973: Inconsistent documentation of repeated arguments |
|
Date: |
Sun, 10 Mar 2013 21:20:45 +0100 |
|
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.2 (gnu/linux) |
On Sun 06 Nov 2011 20:10, address@hidden writes:
> Why not tighten up notation in the docs as well as in the language?
> (4) -- Scheme Procedure: error who message irritant1 ...
>
> IMO, (4) is the right thing.
I just checked and I think we are OK (only simple-format has ". args",
and that only to be consistent with the following C prototype) -- thanks
to your patches, also. Please submit a new patch if you find more
instances of foo . bar in prototypes.
Cheers :)
Andy
--
http://wingolog.org/
--- End Message ---