On Sep 29, 2015, at 1:08 PM, Bradley Lucier <xxxxxx@math.purdue.edu> wrote:

>
>> On Sep 29, 2015, at 12:57 PM, Jamison Hope <xxxxxx@alum.mit.edu> wrote:
>
>> I'm having trouble following
>> all of the big long (values ...) expressions in the text.
>
> I presume you mean the text of the SRFI, and not the text of the implementation?

Yes, the text of the SRFI.  I expect to see lots of big long expressions
in the source code of the implementation. :-)

>> Can there be
>> more descriptions in words explaining what those expressions are doing?
>
> I’ll work on it.  Can you point me to the precise language you’re having difficulty with?

In general, where the text has the form "returns <Scheme Expression>".

For example, in (interval-subset? interval1 interval2), it would help
if the English text stated whether #t means that interval1 is a subset
of interval2, or interval2 is a subset of interval1.  I'm pretty sure
that the Scheme expression is written such that interval1 is the subset
and interval2 is the superset, but having to match up ">=" and "<=" and
"lower" and "upper" and do the mental exercise to figure out what is
happening there is something that could be obviated by one line of text:
"interval-subset? returns true if interval1 is a subset of interval2."

Similarly array-curry, array-distinguish-one-axis, and the other array
functions which currently have something like

"array-ACTION returns (call-with-values ... (interval-ACTION ...) ...)"

could use more English-language summary.

So please fill in the blanks:
"array-curry returns a new array of rank ____ such that ____"
"array-distinguish-one-axis returns a new array of rank ____ such that ____"
"array-for-each applies procedure f to each ____ and returns ____"
"array-reduce applies operator to successive _______ in _____ order"
etc.

Thanks,
-Jamie

--
Jamison Hope
xxxxxx@alum.mit.edu